regex-tools/docs/FORMATTING.md

Pattern formatting

Regex Tools includes a deliberately narrow, local ECMAScript formatter. It canonicalizes representations that can be changed without inventing a visual layout:

• an unescaped literal / becomes \/, making the pattern safe to copy into an ECMAScript regex literal;
• raw NUL and control code units become fixed-width \xNN or their canonical short escape (\t, \n, \v, \f, \r);
• raw U+2028 and U+2029 line separators become \u2028 and \u2029;
• legacy escaped raw controls are replaced as one parser-reported literal token, so the formatter does not introduce an extra backslash.

Existing explicit escape spellings, groups, alternatives, quantifiers, inline flags and literal whitespace are otherwise preserved byte for byte. ECMAScript regex whitespace is normally significant, so the tool does not insert indentation, line breaks or comments and does not claim to be a structural pretty-printer. The transform is idempotent.

Eligibility

Formatting requires the exact current, accepted, non-recovered syntax snapshot from the bundled @eslint-community/regexpp provider. Transformations are derived from the provider's literal-token ranges rather than from a heuristic text scan. A stale parse, malformed pattern, partial provider or any non-ECMAScript profile is reported as unavailable and is never silently rewritten.

Mandatory validation before apply

The preview cannot be applied directly. Regex Tools first:

1. reparses source and candidate independently and checks capture numbering, names, repetition and parent-capture shape;
2. compiles and runs the source and candidate in separate actual ECMAScript engine workers against the current subject and replacement;
3. compares exact normalized match, capture and replacement output, including the engine identity;
4. reruns every enabled unit test whose flavour, version, pattern, flags and engine options exactly match the active source snapshot, and compares both semantic output and assertion outcome.

A compile rejection, one-sided timeout, crash, worker error, cancellation, truncated result, engine-identity change, incomplete test suite or semantic difference blocks application. Matching fixed timeouts are comparable only for an exact unit-test pair; two timeouts on the current interactive snapshot are inconclusive. If no unit test is applicable, the UI says so and still requires the current subject/replacement gate.

Validation is bounded to 1,000 tests, the normal worker/input limits and a 60-second aggregate test wall budget. A test is not started unless its complete configured timeout still fits that budget. The user must explicitly confirm the exact validated candidate before the Apply button is enabled.

Passing these gates is strong, reproducible evidence for the current snapshot and exact tests. It is not a mathematical proof of equivalence for every possible subject.