fix(router): normalize Java named capture groups in route constraints (#2989)

* fix(router): normalize Java named capture groups in route constraints

A constraint containing (?<name>...) still counted as a capturing group
in $mergeRoutePattern's match-position arithmetic, silently shifting
every subsequent route variable's value on java-regex engines — and
legacy-regex engines rejected the syntax outright at match time.
Extend $nonCapturingConstraint's char-class-aware scanner to rewrite
the whole (?<name> opener to (?:, leaving lookbehinds ((?<=, (?<!) and
literals inside character classes untouched.

Fixes #2976

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(router): address Reviewer A/B consensus findings (round 1)

- Add spec asserting Wheels.InvalidRegex is thrown at draw time when a
  named-capture constraint also backreferences the name (e.g.
  `(?<n>\d+)\k<n>`). After normalization the group disappears but the
  `\k<n>` backref remains, so Pattern.compile() rejects it and
  $compileRegex rethrows. Closes the loop on issue #2976's second
  acceptance criterion from the PR description, which was previously
  asserted only in the changelog.
- Replace the unnecessary `##` escape in the existing `(issue ##2976)`
  comment with a single `#`. CFML's `#` sigil is special only in
  double-quoted strings and output contexts; in `//` comments inside
  a script-mode cfc it is a literal character, so `##2976` rendered
  as two hash signs in IDEs, git output, and GitHub diffs.

Cosmetic and test-only — no production code change.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(router): address Reviewer A/B consensus findings (round 2)

Remove the `local.` prefix from `constraintMapper` in the backref
fail-fast spec (`vendor/wheels/tests/specs/mapperModernSpec.cfc`
lines 407 and 417). Each anonymous closure has its own `local`
scope on Adobe CF, so `local.constraintMapper` inside the
`expect(function() { ... })` closure was unbound and would throw an
undefined-variable error before `whereMatch` could fail with
`Wheels.InvalidRegex`, defeating the spec. The unscoped assignment
goes to the CFC-level `variables` scope, which inner closures
inherit — the same pattern used by the sister "invalid regex throws
at draw time" spec just above (line 341). Reference: CLAUDE.md
Anti-Pattern 10.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* chore(docs): move changelog entry to changelog.d fragment

Eliminates the [Unreleased]-anchor merge conflicts across campaign PRs;
fragments are assembled into CHANGELOG.md at release promotion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>
Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: 3 people

changelog.d/router-named-capture-groups.fixed.md

@@ -0,0 +1 @@
+- Route constraints containing a Java named capture group (`whereMatch("year", "(?<yr>20\d{2})")`) no longer corrupt route matching. `$nonCapturingConstraint` now normalizes the whole `(?<name>` opener to `(?:`, the same treatment anonymous capturing groups already receive — previously a named group both shifted every subsequent route variable's value in `$mergeRoutePattern`'s positional extraction (java-regex engines) and threw `Sequence (?<...) not recognized` at match time (legacy-regex engines). Lookbehinds (`(?<=`, `(?<!`) and parenthesis runs inside character classes are left untouched; a constraint that also backreferences the name (`\k<name>`) fails fast at draw time via `$compileRegex` (#2976)

vendor/wheels/Mapper.cfc

@@ -163,14 +163,32 @@ component output="false" {
 				local.rv &= local.char;
 				continue;
 			}
-			if (
-				!local.escaped
-				&& local.char == "("
-				&& local.charClassDepth == 0
-				&& (local.i == local.length || Mid(arguments.pattern, local.i + 1, 1) != "?")
-			) {
-				// Unescaped capturing group outside any character class: make it non-capturing.
-				local.rv &= "(?:";
+			if (!local.escaped && local.char == "(" && local.charClassDepth == 0) {
+				if (local.i == local.length || Mid(arguments.pattern, local.i + 1, 1) != "?") {
+					// Unescaped capturing group outside any character class: make it non-capturing.
+					local.rv &= "(?:";
+				} else {
+					// `(?` opens a non-capturing construct ((?:, (?=, (?!, (?<=, (?<!)
+					// — EXCEPT a Java named capturing group `(?<name>`, which still
+					// counts in the positional group arithmetic $mergeRoutePattern
+					// relies on (and which legacy CFML regex engines reject outright).
+					// Normalize the whole `(?<name>` opener to `(?:`; lookbehinds have
+					// `=` or `!` after `(?<` and are left untouched (issue #2976).
+					// A constraint that also backreferences the name (`\k<name>`)
+					// fails fast at draw time via $compileRegex.
+					local.namedGroup = ReFind(
+						"^\(\?<[A-Za-z][A-Za-z0-9]*>",
+						Mid(arguments.pattern, local.i, local.length - local.i + 1),
+						1,
+						true
+					);
+					if (local.namedGroup.pos[1] == 1) {
+						local.rv &= "(?:";
+						local.i += local.namedGroup.len[1] - 1;
+					} else {
+						local.rv &= local.char;
+					}
+				}
 			} else {
 				local.rv &= local.char;
 			}

vendor/wheels/tests/specs/mapperModernSpec.cfc

@@ -369,6 +369,55 @@ component extends="wheels.WheelsTest" {
 				expect(ArrayLen(local.matches.pos)).toBe(3)
 			})
 
+			it("rewrites Java named capture groups in constraints to non-capturing groups", function() {
+				local.mapper = $mapper()
+					.$draw()
+					.get(name="namedArchive", pattern="archive/[year]/[month]", to="archive##show")
+						.whereMatch("year", "(?<yr>20\d{2})")
+					.end()
+
+				local.routes = local.mapper.getRoutes()
+				local.route = local.routes[1]
+				expect("archive/2024/05").toMatch(local.route.regex)
+
+				// Java named groups still count in the positional group arithmetic
+				// $mergeRoutePattern relies on, so they must be normalized away
+				// exactly like anonymous capturing groups — otherwise [month]
+				// would silently receive the year's value (issue #2976).
+				local.matches = ReFind(local.route.regex, "archive/2024/05", 1, true)
+				expect(ArrayLen(local.matches.pos)).toBe(3)
+			})
+
+			it("normalizes named groups but preserves lookbehinds in $nonCapturingConstraint", function() {
+				local.mapper = $mapper()
+
+				// Named capturing group opener is replaced wholesale with `(?:`.
+				expect(local.mapper.$nonCapturingConstraint("(?<yr>20\d{2})")).toBe("(?:20\d{2})")
+
+				// Lookbehinds start with `(?<` too but are NOT capturing groups —
+				// the rewrite must leave them untouched.
+				expect(local.mapper.$nonCapturingConstraint("\w+(?<!tmp)")).toBe("\w+(?<!tmp)")
+				expect(local.mapper.$nonCapturingConstraint("\w+(?<=pdf)")).toBe("\w+(?<=pdf)")
+
+				// Inside a character class, `(?<x>` is a run of literal characters.
+				expect(local.mapper.$nonCapturingConstraint("[(?<x>)]")).toBe("[(?<x>)]")
+			})
+
+			it("throws Wheels.InvalidRegex when a normalized named group leaves a dangling backref", function() {
+				constraintMapper = $mapper()
+					.$draw()
+					.get(name="backrefs", pattern="items/[id]", to="items##show")
+
+				// After normalization, `(?<n>\d+)` becomes `(?:\d+)`, so the
+				// trailing `\k<n>` backref points at a group name that no longer
+				// exists. java.util.regex.Pattern.compile() rejects this, and
+				// $compileRegex rethrows it as Wheels.InvalidRegex at draw time
+				// — closing the loop on issue #2976's second acceptance criterion.
+				expect(function() {
+					constraintMapper.whereMatch("id", "(?<n>\d+)\k<n>")
+				}).toThrow("Wheels.InvalidRegex")
+			})
+
 			it("leaves parentheses inside character classes untouched", function() {
 				local.mapper = $mapper()
 					.$draw()