[FEATURE] Export discovered regex features during source walk (#70)

* Add features export
* Correct placement of backreferences &  prefix-ambiguous top-level alternation in docs
* Remove confusing "multi-engine consistency" comparison from parity tables

Author: TomStrepsil

README.md

@@ -10,6 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Benchmark for construction cost
+- `features: ReadonlySet<RegexFeature>` field of the created `PartialMatchRegExp`, indicating the discovered features found during walk of the regex
+
+### Fixed
+
+- Moved documentation of caveat regarding prefix-ambiguous top-level alternation to its proper location alongside backreferences, since it only applies when they exist
+
+### Removed
+
+- Removed confusing "multi-engine consistency" comparison that differentiates the testing style of RE2 reference implementation from the parity documentation
 
 ## [1.0.0] - 2026-07-22
 

docs/CHANGELOG.md

@@ -63,7 +63,6 @@ RE2 **explicitly excludes backreferences by design**. From `re2.h`: _"backrefere
 | First-match (NFA) vs longest-match (POSIX) semantics | ✅ ECMAScript / NFA first-match — `(a\|aa)\1` on `"aaaa"` yields `m[1]="a"`, not `"aa"` |
 | Capturing groups across anchoring modes              | ✅ Covered — see groups tests                                                           |
 | Backreferences                                       | ✅ Partial matching supported (RE2 excludes them entirely by design)                    |
-| Multi-engine consistency                             | N/A — JS has a single engine per runtime                                                |
 
 ## ☕ OpenJDK (`java.util.regex` — `RegExTest.java`)
 
@@ -106,4 +105,3 @@ The JDK **does** support backreferences, and `RegExTest.java` includes `backRefT
 | hitEnd() / prefix-only match             |           —            |           —           | ✅ (`\=ps` / `\=ph` subject modifiers) |                 ✅                 | ✅ (non-empty exec result) |
 | requireEnd()                             |           —            |           —           |                    —                    |                 ✅                 |       ⚠️ Not exposed       |
 | Backreference partial matching           | ❌ unsupported dialect | ❌ excluded by design |            ⚠️ Not a focus in testdata            | ⚠️ full match only (`backRefTest`) |             ✅             |
-| Multi-engine consistency                 |           —            |          ✅           |                    —                    |                 —                  |            N/A             |

docs/partial-match-parity.md

@@ -2,7 +2,7 @@ import escapeAtom from "./escapeAtom.ts";
 
 const OCCURRENCES_REGEX = /\{\d+,?\d*\}/y;
 const NOT_NUMBERS_REGEX = /\D/g;
-const ALTERNATION_TO_END_OF_INPUT = "|$(?![\\s\\S]))";
+const DISJUNCTION_TO_END_OF_INPUT = "|$(?![\\s\\S]))";
 const MAYBE_HAS_BACKREFERENCE = /\\[1-9]|\\k</;
 
 interface NumericBackreference {
@@ -26,12 +26,46 @@ const isBackreference = (part: Part): part is Backreference =>
 const isNumericBackreference = (part: Part): part is NumericBackreference =>
   isBackreference(part) && typeof part.ref === "number";
 
-function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
+export type RegexFeature =
+  | "patternCharacter"
+  | "startAnchor"
+  | "endAnchor"
+  | "wordBoundary"
+  | "nonWordBoundary"
+  | "lookahead"
+  | "negativeLookahead"
+  | "lookbehind"
+  | "negativeLookbehind"
+  | "backreference"
+  | "namedBackreference"
+  | "namedGroup"
+  | "capturingGroup"
+  | "nonCapturingGroup"
+  | "modifierGroup"
+  | "modifierGroupWithRemoval"
+  | "characterClass"
+  | "nestedCharacterClass"
+  | "classIntersection"
+  | "classSubtraction"
+  | "disjunction"
+  | "quantifier"
+  | "unicodePropertyEscape"
+  | "characterClassEscape"
+  | "controlEscape"
+  | "controlLetterEscape"
+  | "hexEscapeSequence"
+  | "unicodeEscapeSequence"
+  | "otherEscape";
+
+function walk(
+  regex: RegExp
+): { parts: Part[]; groupCount: number; features: Set<RegexFeature> } {
   const source = regex.source;
   const isUnicode = regex.unicode || regex.unicodeSets;
 
   let i = 0;
   let groupCount = 0;
+  const features = new Set<RegexFeature>();
 
   function extractSlice(length: number): string {
     return source.slice(i, (i += length));
@@ -41,7 +75,7 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
     const result: Part[] = [];
 
     function appendOptional(length: number) {
-      result.push("(?:" + extractSlice(length) + ALTERNATION_TO_END_OF_INPUT);
+      result.push("(?:" + extractSlice(length) + DISJUNCTION_TO_END_OF_INPUT);
     }
 
     function appendRaw(length: number) {
@@ -60,6 +94,7 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
         case "\\":
           switch (source[i + 1]) {
             case "c":
+              features.add("controlLetterEscape");
               appendOptional(3);
               break;
             case "k": {
@@ -68,6 +103,7 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
               if (referenceEnd === -1) {
                 appendOptional(2);
               } else {
+                features.add("namedBackreference");
                 const start = i;
                 const ref = source.slice(i + 3, referenceEnd);
                 i = referenceEnd + 1;
@@ -76,6 +112,7 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
               break;
             }
             case "u":
+              features.add("unicodeEscapeSequence");
               if (isUnicode && source[i + 2] === "{") {
                 appendOptional(source.indexOf("}", i) - i + 1);
               } else {
@@ -85,14 +122,32 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
             case "p":
             case "P":
               if (isUnicode) {
+                features.add("unicodePropertyEscape");
                 appendOptional(source.indexOf("}", i) - i + 1);
               } else {
                 appendOptional(2);
               }
               break;
             case "x":
+              features.add("hexEscapeSequence");
               appendOptional(4);
               break;
+            case "b":
+              features.add("wordBoundary");
+              appendOptional(2);
+              break;
+            case "B":
+              features.add("nonWordBoundary");
+              appendOptional(2);
+              break;
+            case "f":
+            case "n":
+            case "r":
+            case "t":
+            case "v":
+              features.add("controlEscape");
+              appendOptional(2);
+              break;
             case "1":
             case "2":
             case "3":
@@ -102,6 +157,7 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
             case "7":
             case "8":
             case "9": {
+              features.add("backreference");
               NOT_NUMBERS_REGEX.lastIndex = i + 1;
               const nextNonDigit = NOT_NUMBERS_REGEX.exec(source);
               const start = i;
@@ -111,43 +167,82 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
               result.push({ ref, start, end });
               break;
             }
+            case "d":
+            case "D":
+            case "w":
+            case "W":
+            case "s":
+            case "S":
+              features.add("characterClassEscape");
+              appendOptional(2);
+              break;
             default:
+              features.add("otherEscape");
               appendOptional(2);
               break;
           }
           break;
         case "[": {
+          features.add("characterClass");
           let depth = 1,
-            j = i + 1;
+            j = i + 1,
+            previousSetOperatorCharacter: string | undefined;
           while (depth) {
-            switch (source[j]) {
+            const character = source[j];
+            switch (character) {
               case "\\":
                 j += 2;
+                previousSetOperatorCharacter = undefined;
                 continue;
               case "[":
-                if (regex.unicodeSets) depth++;
+                if (regex.unicodeSets) {
+                  features.add("nestedCharacterClass");
+                  depth++;
+                }
                 break;
               case "]":
                 depth--;
                 break;
+              case "&":
+                if (regex.unicodeSets && previousSetOperatorCharacter === "&") {
+                  features.add("classIntersection");
+                }
+                break;
+              case "-":
+                if (regex.unicodeSets && previousSetOperatorCharacter === "-") {
+                  features.add("classSubtraction");
+                }
+                break;
             }
+            previousSetOperatorCharacter = character;
             j++;
           }
           appendOptional(j - i);
           break;
         }
-        case "|":
         case "^":
+          features.add("startAnchor");
+          appendRaw(1);
+          break;
+        case "$":
+          features.add("endAnchor");
+          appendRaw(1);
+          break;
+        case "|":
+          features.add("disjunction");
+          appendRaw(1);
+          break;
         case "*":
         case "+":
         case "?":
-        case "$":
+          features.add("quantifier");
           appendRaw(1);
           break;
         case "{": {
           OCCURRENCES_REGEX.lastIndex = i;
           const regExpExecArray = OCCURRENCES_REGEX.exec(source);
           if (regExpExecArray) {
+            features.add("quantifier");
             appendRaw(regExpExecArray[0].length);
           } else {
             appendOptional(1);
@@ -158,11 +253,13 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
           if (source[i + 1] == "?") {
             switch (source[i + 2]) {
               case ":":
+                features.add("nonCapturingGroup");
                 result.push("(?:");
                 i += 3;
-                result.push(...process(), ALTERNATION_TO_END_OF_INPUT);
+                result.push(...process(), DISJUNCTION_TO_END_OF_INPUT);
                 break;
               case "=":
+                features.add("lookahead");
                 result.push("(?=");
                 i += 3;
                 result.push(...process(), ")");
@@ -173,38 +270,53 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
               case "m": {
                 const flagsStart = i + 2,
                   colonIndex = source.indexOf(":", flagsStart);
-                result.push("(?" + source.slice(flagsStart, colonIndex) + ":");
+                const modifiers = source.slice(flagsStart, colonIndex);
+                features.add(
+                  modifiers.includes("-")
+                    ? "modifierGroupWithRemoval"
+                    : "modifierGroup"
+                );
+                result.push("(?" + modifiers + ":");
                 i = colonIndex + 1;
                 result.push(...process(), ")");
                 break;
               }
               case "!":
+                features.add("negativeLookahead");
                 appendRawGroup(3);
                 break;
               case "<":
                 switch (source[i + 3]) {
                   case "=":
+                    features.add("lookbehind");
+                    appendRawGroup(4);
+                    break;
                   case "!":
+                    features.add("negativeLookbehind");
                     appendRawGroup(4);
                     break;
                   default:
+                    features.add("namedGroup");
+                    features.add("capturingGroup");
                     ++groupCount;
                     appendRaw(source.indexOf(">", i) - i + 1);
-                    result.push(...process(), ALTERNATION_TO_END_OF_INPUT);
+                    result.push(...process(), DISJUNCTION_TO_END_OF_INPUT);
                     break;
                 }
                 break;
             }
           } else {
+            features.add("capturingGroup");
             ++groupCount;
             appendRaw(1);
-            result.push(...process(), ALTERNATION_TO_END_OF_INPUT);
+            result.push(...process(), DISJUNCTION_TO_END_OF_INPUT );
           }
           break;
         case ")":
           ++i;
           return result;
         default:
+          features.add("patternCharacter");
           appendOptional(
             isUnicode && (source.codePointAt(i) ?? 0) > 0xffff ? 2 : 1
           );
@@ -214,7 +326,7 @@ function walk(regex: RegExp): { parts: Part[]; groupCount: number } {
     return result;
   }
 
-  return { parts: process(), groupCount };
+  return { parts: process(), groupCount, features };
 }
 
 function render(
@@ -239,7 +351,7 @@ function reclassifyOctalEscapes(
 ): Part[] {
   return parts.map((part) =>
     isNumericBackreference(part) && part.ref > groupCount
-      ? "(?:" + source.slice(part.start, part.end) + ALTERNATION_TO_END_OF_INPUT
+      ? "(?:" + source.slice(part.start, part.end) + DISJUNCTION_TO_END_OF_INPUT
       : part
   );
 }
@@ -259,7 +371,7 @@ function spliceOriginalSource(
 
 function expandCaptured(value: string, isUnicode: boolean): string {
   return (isUnicode ? Array.from(value) : value.split(""))
-    .map((atom) => "(?:" + escapeAtom(atom) + ALTERNATION_TO_END_OF_INPUT)
+    .map((atom) => "(?:" + escapeAtom(atom) + DISJUNCTION_TO_END_OF_INPUT)
     .join("");
 }
 
@@ -269,17 +381,19 @@ export interface DynamicPath {
   expand: (capture: RegExpExecArray) => string;
 }
 
-export type CompiledPartial =
+export type CompiledPartial = (
   | { kind: "static"; regex: RegExp }
-  | { kind: "dynamic"; dynamic: DynamicPath };
+  | { kind: "dynamic"; dynamic: DynamicPath }
+) & { features: Set<RegexFeature> };
 
 export const compilePartial = (regex: RegExp): CompiledPartial => {
-  const { parts, groupCount } = walk(regex);
+  const { parts, groupCount, features } = walk(regex);
 
   if (!MAYBE_HAS_BACKREFERENCE.test(regex.source)) {
     return {
       kind: "static",
-      regex: new RegExp(render(parts, backrefToken), regex.flags)
+      regex: new RegExp(render(parts, backrefToken), regex.flags),
+      features
     };
   }
 
@@ -291,12 +405,14 @@ export const compilePartial = (regex: RegExp): CompiledPartial => {
   if (backreferences.length === 0) {
     return {
       kind: "static",
-      regex: new RegExp(render(sanitizedParts, backrefToken), regex.flags)
+      regex: new RegExp(render(sanitizedParts, backrefToken), regex.flags),
+      features
     };
   }
 
   return {
     kind: "dynamic",
+    features,
     dynamic: {
       originalCaptureScan: new RegExp(
         spliceOriginalSource(regex.source, backreferences),
@@ -312,7 +428,7 @@ export const compilePartial = (regex: RegExp): CompiledPartial => {
             ? capture[backref.ref]
             : capture.groups?.[backref.ref];
           return captured === undefined
-            ? "(?:" + backrefToken(backref) + ALTERNATION_TO_END_OF_INPUT
+            ? "(?:" + backrefToken(backref) + DISJUNCTION_TO_END_OF_INPUT
             : expandCaptured(captured, isUnicode);
         })
     }