chore: drop internal version codenames from code/tests/docs

dkryaklin · claude · dkryaklin · commit 48d345431e47 · 2026-05-23T19:38:42.000+03:00
The original branch was scaffolded as a 'v3 spike' and individual
test annotations referenced a development-time 'v11.3' milestone.
Both leak internal naming into permanent files. This pass converts
those references plus the load-bearing 'v10' / 'v11' framing into
evergreen wording.

- test/index.js: slim header explaining the three-flag wrapper,
  drop the csstools-oracle env-var toggle (debugging-only), and
  compact every divergence annotation to one short line in the
  form `// &lt;change description&gt;`. Keeps the `/* legacy output */
  new output` inline syntax so each diff is visible at a glance.
  Drops the 'flag mechanics' comments on tests whose expected
  output is unchanged — the wrapper at the top explains the
  flags once.
- README: rename 'Migrating from postcss-calc 10.x' section to
  'Behavior differences from the legacy parser'. The substantive
  content (three-flag combo + spec-aligned defaults list) is
  preserved with version-free phrasing.
- src/, scripts/, configs: 'v3' → 'this implementation' /
  'pratt pipeline'; 'v11.3' → 'planned follow-up'; 'v10' →
  'legacy' / 'previously'. CHANGELOG left untouched (historical
  release entries pre-date this PR).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.dependency-cruiser.cjs b/.dependency-cruiser.cjs
@@ -1,5 +1,5 @@
 // dependency-cruiser config — enforces module-boundary rules for the
-// TypeScript v11 sources. Keeps `core/` PostCSS-free so it stays portable,
+// TypeScript sources. Keeps `core/` PostCSS-free so it stays portable,
 // and stops test code from being reachable from production.
 
 module.exports = {
diff --git a/README.md b/README.md
@@ -169,14 +169,14 @@ calc({dropZeroIdentities: true})
 | `calc(99.99% * 1/1 - 0rem)` | `calc(99.99% + 0rem)` | `99.99%` |
 | `calc((100px - 1em) + (-50px + 1em))` | `calc(50px + 0em)` | `50px` |
 
-### Migrating from `postcss-calc` 10.x
+### Behavior differences from the legacy parser
 
-10.x used a [jison][jison]-generated parser; 11.x ships a hand-written
+The legacy [jison][jison]-generated parser was replaced by a hand-written
 Pratt parser whose simplifier follows [CSS Values 4][css-values-4]. Most
-inputs reduce to identical output, but some 10.x results were jison
-implementation choices rather than spec-required behavior. The three opt-
-in flags above recover the most visible differences. Setting all three
-matches 10.x as closely as 11.x will go:
+inputs reduce to identical output, but some legacy results were jison
+implementation choices rather than spec-required behavior. The three
+opt-in flags above recover the most visible differences. Setting all
+three matches the legacy output as closely as possible:
 
 ```js
 calc({
@@ -186,14 +186,14 @@ calc({
 })
 ```
 
-A handful of 11.x behaviors aren't flag-controlled — they're spec-aligned
+A handful of behaviors aren't flag-controlled — they're spec-aligned
 or canonical-form decisions:
 
 - **Constant folding.** `calc(43 + pi)` now folds to `46.14159` (§10.7.1).
-  10.x kept `pi` / `e` symbolic.
+  Previously `pi` / `e` stayed symbolic.
 - **Reciprocal conversion.** `calc(var(--x) / 2)` becomes
-  `calc(var(--x) * 0.5)`. The two are mathematically equivalent; 10.x kept
-  the division shape.
+  `calc(var(--x) * 0.5)`. The two are mathematically equivalent;
+  previously the division shape was kept.
 - **Distributive multiplication.** `calc(0.5 * (100vw - 10px))` becomes
   `calc(50vw - 5px)`.
 - **Unit case normalization.** `2PX` becomes `2px` (CSS units are case-
diff --git a/eslint.config.js b/eslint.config.js
@@ -14,7 +14,7 @@ module.exports = [
     ],
   },
   js.configs.recommended,
-  // Type-aware lint for the v11 TypeScript sources.
+  // Type-aware lint for the TypeScript sources.
   ...tseslint.configs.recommendedTypeChecked.map((c) => ({
     ...c,
     files: ['src/pratt/**/*.ts', 'scripts/**/*.ts'],
@@ -32,7 +32,7 @@ module.exports = [
     plugins: { sonarjs },
     rules: sonarjs.configs.recommended.rules,
   },
-  // Project-specific lint adjustments for the v11 TypeScript sources.
+  // Project-specific lint adjustments for the TypeScript sources.
   {
     files: ['src/pratt/**/*.ts', 'scripts/**/*.ts'],
     rules: {
diff --git a/scripts/check-issues.ts b/scripts/check-issues.ts
@@ -1,6 +1,6 @@
 // Run each open issue's test case through the pratt pipeline and report
-// whether v3 resolves the v10-era complaint. See gh issue list --repo
-// postcss/postcss-calc --state open.
+// whether the new implementation resolves the legacy complaint. See
+// `gh issue list --repo postcss/postcss-calc --state open`.
 
 import postcss from 'postcss';
 import plugin from '../src/pratt/src/plugin/plugin.ts';
@@ -130,7 +130,7 @@ const cases: Case[] = [
 ];
 
 const META_NOTES: Record<number, string> = {
-  198: 'Meta: hand-written Pratt parser is exactly what v3 ships.',
+  198: 'Meta: hand-written Pratt parser is exactly what this rewrite ships.',
   67:  'Meta: browserlist integration is out of scope (cssnano territory).',
 };
 
@@ -159,7 +159,7 @@ async function run(declaration: string): Promise<Run> {
 }
 
 async function main(): Promise<void> {
-  console.log(`Running ${cases.length} test cases against pratt v3.\n`);
+  console.log(`Running ${cases.length} test cases against the pratt pipeline.\n`);
 
   let resolved = 0;
   let unresolved = 0;
diff --git a/src/pratt/src/core/simplify/product.ts b/src/pratt/src/core/simplify/product.ts
@@ -65,7 +65,7 @@ export function simplifyProduct(
 
   // §10.10 distributive multiplication: `0.5 * (100vw - 10px)` → `50vw - 5px`.
   // Only distribute when every Sum term is Num/Dim — partial distribution
-  // over opaque terms matches neither v10 nor csstools.
+  // over opaque terms matches neither the legacy implementation nor csstools.
   if (
     remainingDims.length === 0 &&
     opaque.length === 1 &&
diff --git a/src/pratt/src/core/simplify/sum.ts b/src/pratt/src/core/simplify/sum.ts
@@ -79,8 +79,8 @@ export function simplifySum(
   });
   for (const bucket of finalBuckets) {
     // Default: emit `0<unit>` for type info (WPT calc-serialization-002).
-    // dropZeroIdentities flips to v10's "drop zero terms when typed siblings
-    // survive" behavior.
+    // dropZeroIdentities flips to the legacy "drop zero terms when typed
+    // siblings survive" behavior.
     if (
       options.dropZeroIdentities &&
       bucket.total === 0 &&
diff --git a/src/pratt/src/plugin/plugin-csstools.ts b/src/pratt/src/plugin/plugin-csstools.ts
@@ -1,5 +1,5 @@
 // Drop-in alternative that delegates to @csstools/css-calc, used for
-// head-to-head comparison against the v10 regression suite.
+// head-to-head comparison against the legacy regression suite.
 
 import type { PluginCreator } from 'postcss';
 import { calc as csstoolsCalc } from '@csstools/css-calc';
diff --git a/src/pratt/src/plugin/plugin.ts b/src/pratt/src/plugin/plugin.ts
@@ -1,7 +1,7 @@
 // PostCSS adapter. Walks declaration values (and optionally @rule params
 // and selectors), feeds calc() bodies through tokenize → parse → simplify
 // → serialize, and writes the result back. Drop-in compatible with the
-// v10 public option surface.
+// legacy public option surface.
 
 import valueParser from 'postcss-value-parser';
 import type { PluginCreator, Result, ChildNode } from 'postcss';
diff --git a/src/pratt/test/conformance/csstools.test.ts b/src/pratt/test/conformance/csstools.test.ts
@@ -5,7 +5,7 @@
 // produces the same output as csstools. Deliberately excluded:
 //   - csstools `globals` option (variable substitution) — not in our scope
 //   - relative-color math (`rgb(from ...)`) — out of scope
-//   - exponential family (pow/sqrt/hypot/log/exp) — not yet implemented (v11.3)
+//   - exponential family (pow/sqrt/hypot/log/exp) — not yet implemented
 //   - cases where floating-point serialization precision differs (we use
 //     `precision: false` to emit full-float, but csstools occasionally
 //     rounds at ~15 significant figures in its own way)
diff --git a/src/pratt/test/conformance/wpt.test.ts b/src/pratt/test/conformance/wpt.test.ts
@@ -9,7 +9,7 @@
 //   - infinity / NaN serialization (covered when full IEEE-754 fold lands).
 //
 // Trig (§10.4: sin/cos/tan/asin/acos/atan/atan2) is covered below; the
-// exponential family (pow/sqrt/hypot/log/exp) lands in v11.3.
+// exponential family (pow/sqrt/hypot/log/exp) is a planned follow-up.
 //
 // Divergences are documented with `DIVERGE:` comments.
 
diff --git a/src/pratt/test/unit/options.test.ts b/src/pratt/test/unit/options.test.ts
@@ -1,7 +1,8 @@
-// Coverage for the three opt-in flags that recover v10 / jison behavior:
-// strictWhitespace (tokenizer-level), preserveOrder (simplifier output
-// order), dropZeroIdentities (simplifier zero-bucket pruning). Defaults
-// match the spec; each flag is independent and composes cleanly.
+// Coverage for the three opt-in flags that recover legacy jison
+// behavior: strictWhitespace (tokenizer-level), preserveOrder
+// (simplifier output order), dropZeroIdentities (simplifier zero-bucket
+// pruning). Defaults match the spec; each flag is independent and
+// composes cleanly.
 
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
diff --git a/src/pratt/test/unit/plugin.test.ts b/src/pratt/test/unit/plugin.test.ts
@@ -136,8 +136,8 @@ test('plugin: onParseError receives the inner calc body, not the full decl', asy
 });
 
 test('plugin: division by zero now folds to infinity (no error)', async () => {
-  // Pre-v11.3 this threw; §10.9.1 specifies IEEE-754 propagation, so the
-  // simplifier yields Dim(Infinity, px) which serializes as the canonical
+  // §10.9.1 specifies IEEE-754 propagation, so the simplifier yields
+  // Dim(Infinity, px) which serializes as the canonical
   // calc(infinity * 1px) form.
   const captured: Error[] = [];
   const { css } = await process('a{b:calc(1px / 0)}', {
@@ -173,8 +173,8 @@ test('plugin: preserve + warnWhenCannotResolve — both fire together', async ()
     warnWhenCannotResolve: true,
   });
   // preserve clones the original alongside — both have the same
-  // serialized value since v3 can't fully simplify this expression,
-  // but the clone step still runs.
+  // serialized value since the simplifier can't fully reduce this
+  // expression, but the clone step still runs.
   assert.match(css, /calc\(100% \+ var\(--x\)\)/);
   assert.equal(warnings.length, 1);
 });
diff --git a/src/pratt/test/unit/serialize.test.ts b/src/pratt/test/unit/serialize.test.ts
@@ -7,8 +7,8 @@ import { mkSum, mkProduct, type Node } from '../../src/core/node.ts';
 // Direct serialize() tests — build canonical AST nodes by hand to pin
 // output shape without depending on the parser/simplify.
 
-// With v3's signed-leaf canonical form, negatives live directly in the
-// Num/Dim value — no wrapper needed.
+// Signed-leaf canonical form: negatives live directly in the Num/Dim
+// value — no wrapper needed.
 const num = (v: number): Node => ({ type: 'Num', value: v });
 const dim = (v: number, u: string): Node => ({ type: 'Dim', value: v, unit: u });
 
@@ -68,7 +68,7 @@ test('serialize: Sum inside Product gets parens', () => {
 });
 
 test('serialize: negative Dim via signed leaf → bare -Xpx', () => {
-  // v3: negatives live directly in the Dim value. The constructor helper
+  // Negatives live directly in the Dim value. The constructor helper
   // `dim(-1, 'px')` returns a Dim with value -1, no Sum wrapper.
   assert.equal(serialize(dim(-1, 'px')), '-1px');
 });
diff --git a/src/pratt/test/unit/simplify/general.test.ts b/src/pratt/test/unit/simplify/general.test.ts
@@ -18,9 +18,9 @@ test('simplify: sum with dim terms only (hasNum stays false)', () => {
 });
 
 test('simplify: division by Dim(0, unit) flows through (no throw)', () => {
-  // Pre-v11.3 this threw; per §10.9.1 the Product simplifier now produces
-  // an opaque Call shape — `1 / 0px` is invalid typed-arith (number /
-  // length) and stays unreduced.
+  // Per §10.9.1 the Product simplifier produces an opaque Call shape —
+  // `1 / 0px` is invalid typed-arith (number / length) and stays
+  // unreduced rather than throwing.
   assert.equal(out('calc(1 / 0px)'), 'calc(1 / 0px)');
 });
 
diff --git a/src/pratt/test/unit/simplify/inverse-trig.test.ts b/src/pratt/test/unit/simplify/inverse-trig.test.ts
@@ -5,8 +5,8 @@ import { out } from '../../helpers/out.ts';
 
 //
 // Numbers in (spec §10.4 line 1046: "must resolve to a <number>"); result
-// in degrees. NaN out-of-domain results stay as bare NaN until the
-// degenerate-numeric serialization (calc(NaN * 1deg)) lands in v11.3.
+// in degrees. NaN out-of-domain results stay as bare NaN — degenerate-
+// numeric serialization (calc(NaN * 1deg)) is a planned follow-up.
 
 test('asin: 0 → 0deg', () => {
   assert.equal(out('asin(0)'), '0deg');
diff --git a/stryker.conf.mjs b/stryker.conf.mjs
@@ -1,12 +1,12 @@
 // Stryker mutation testing config.
 //
-// Mutates the core v3 logic (simplify + serialize + node constructors) and
+// Mutates the core pipeline (simplify + serialize + node constructors) and
 // reports the kill rate. A surviving mutant means the test suite would
 // accept a wrong implementation — i.e. a real coverage hole.
 //
 // We use the `command` runner since our test harness is `node --test` via
-// tsx. Each mutant runs the whole v11 suite; the suite is fast
-// enough (<400ms) that this is practical.
+// tsx. Each mutant runs the whole pratt suite; the suite is fast enough
+// (<400ms) that this is practical.
 
 /** @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */
 export default {
diff --git a/test/index.js b/test/index.js
