feat: publish Regex Tools 0.2.0

docs/FORMATTING.md

@@ -0,0 +1,57 @@
+# 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, a malformed pattern, a partial provider, PCRE2 or any
+other flavour 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.