chore: tooling scripts (benchmarks, randomizer, harvester, issue-checker) + README

Author: dkryaklin

README.md

@@ -120,6 +120,115 @@ div[data-size="calc(3*3)"] {
 }
 ```
 
+#### `strictWhitespace` (default: `true`)
+
+Reject inputs that don't follow [CSS Values 4 §10.1][css-values-4-syntax]'s
+whitespace rule around binary `+` / `-`. With the default, `calc(2px+3px)`
+is rejected (it tokenizes as `[2px, +, 3px]` but lacks whitespace around
+the `+`). Set to `false` to recover jison-era lenient parsing.
+
+```js
+calc({strictWhitespace: false})
+```
+
+#### `preserveOrder` (default: `false`)
+
+Preserve input order of commutative operands rather than reordering to the
+canonical (numeric-first, then by-discovery, then opaque) shape that
+[`@csstools/css-calc`][csstools-css-calc] also uses.
+
+```js
+calc({preserveOrder: true})
+```
+
+| Input | Default | `preserveOrder: true` |
+|---|---|---|
+| `calc(var(--foo) + 10px)` | `calc(10px + var(--foo))` | `calc(var(--foo) + 10px)` |
+| `calc(1px + 1)` | `calc(1 + 1px)` | `calc(1px + 1)` |
+| `calc(var(--m) * 1px)` | `calc(1px * var(--m))` | `calc(var(--m) * 1px)` |
+
+`preserveOrder` operates on outer-expression positions; nested-sum
+flattening, constant folding, and reciprocal conversion (`a / 2` →
+`a * 0.5`) all collapse positions before assembly and can't be recovered.
+
+#### `dropZeroIdentities` (default: `false`)
+
+Drop `+ 0px` / `+ 0em` identities from sums when another term in the same
+sum already carries the type. The default preserves zero-valued buckets
+because [WPT calc-serialization-002][wpt-calc-serialization] and the
+round-trip property both require it (`calc(0px + 100%)` is a length-
+percentage; collapsing to `100%` loses the type signal).
+
+```js
+calc({dropZeroIdentities: true})
+```
+
+| Input | Default | `dropZeroIdentities: true` |
+|---|---|---|
+| `calc(100px - (100px - 100%))` | `calc(0px + 100%)` | `100%` |
+| `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
+
+10.x used a [jison][jison]-generated parser; 11.x ships 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:
+
+```js
+calc({
+  strictWhitespace: false,
+  preserveOrder: true,
+  dropZeroIdentities: true,
+})
+```
+
+A handful of 11.x 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.
+- **Reciprocal conversion.** `calc(var(--x) / 2)` becomes
+  `calc(var(--x) * 0.5)`. The two are mathematically equivalent; 10.x kept
+  the division shape.
+- **Distributive multiplication.** `calc(0.5 * (100vw - 10px))` becomes
+  `calc(50vw - 5px)`.
+- **Unit case normalization.** `2PX` becomes `2px` (CSS units are case-
+  insensitive; lowercase is conventional).
+- **Calc unwrap (§10.6).** `calc(var(--foo))` becomes `var(--foo)` — a
+  `calc()` containing a single value is replaced by that value.
+- **Spec-style spaced operators.** `2px*var(--x)` is serialized as
+  `2px * var(--x)`. The tokenizer is unaffected; only output spacing
+  differs.
+- **Division by zero / by a unit.** `calc(500px/0)` reduces to
+  `calc(infinity * 1px)` (§10.13) instead of throwing. Use `onParseError`
+  if you want validation behavior.
+
+#### `onParseError`
+
+Callback invoked when a `calc()` body fails to parse or simplify. Matches
+[`@csstools/css-calc`][csstools-css-calc]'s shape:
+
+```js
+calc({
+  onParseError: (err, input) => {
+    throw err; // or log, route to a different channel, etc.
+  }
+})
+```
+
+When omitted, errors are reported via PostCSS `result.warn()` so the
+plugin never throws at the postcss level.
+
+[css-values-4]: https://www.w3.org/TR/css-values-4/
+[css-values-4-syntax]: https://www.w3.org/TR/css-values-4/#calc-syntax
+[csstools-css-calc]: https://www.npmjs.com/package/@csstools/css-calc
+[wpt-calc-serialization]: https://github.com/web-platform-tests/wpt/blob/master/css/css-values/calc-serialization-002.html
+[jison]: https://github.com/zaach/jison
+
 ---
 
 ## Related PostCSS plugins

scripts/benchmark-v10.ts

@@ -0,0 +1,62 @@
+// Benchmark: v10 (legacy jison) vs pratt against the harvested corpus.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import postcss, { type AcceptedPlugin } from 'postcss';
+
+interface BenchResult {
+  name: string;
+  perRun: number;
+  total: number;
+}
+
+async function main(): Promise<void> {
+  // Dynamic imports so CJS/ESM interop works under tsx.
+  const v10Plugin = (await import('../src/index.js')).default as () => AcceptedPlugin;
+  const v3Plugin = (await import('../src/pratt/src/plugin/plugin.ts')).default as () => AcceptedPlugin;
+
+  const HERE = dirname(fileURLToPath(import.meta.url));
+  const CORPUS_DIR = join(HERE, '..', 'src', 'pratt', 'test', 'corpus');
+
+  const calcs = readdirSync(CORPUS_DIR)
+    .filter((f) => f.endsWith('.txt'))
+    .flatMap((f) =>
+      readFileSync(join(CORPUS_DIR, f), 'utf8')
+        .split('\n')
+        .filter((l) => l.trim().length > 0)
+    );
+
+  const css = calcs.map((calc, i) => `.rule-${i} { prop: ${calc}; }`).join('\n');
+
+  const ITERATIONS = 100;
+  const POSTCSS_OPTS = { from: undefined };
+
+  async function bench(name: string, plugin: () => AcceptedPlugin): Promise<BenchResult> {
+    for (let i = 0; i < 5; i++) {
+      await postcss(plugin()).process(css, POSTCSS_OPTS);
+    }
+    const start = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+      await postcss(plugin()).process(css, POSTCSS_OPTS);
+    }
+    const total = performance.now() - start;
+    return { name, perRun: total / ITERATIONS, total };
+  }
+
+  console.log(`\nInput: ${calcs.length} real-world calc() expressions`);
+  console.log(`CSS size: ${css.length} bytes, ${calcs.length} declarations`);
+  console.log(`Iterations: ${ITERATIONS} each\n`);
+
+  const v10 = await bench('v10 (jison)', v10Plugin);
+  const v3 = await bench('v3 (pratt)', v3Plugin);
+
+  console.log(`  ${v10.name}:  ${v10.perRun.toFixed(2)}ms / run  (${v10.total.toFixed(0)}ms total)`);
+  console.log(`  ${v3.name}:   ${v3.perRun.toFixed(2)}ms / run  (${v3.total.toFixed(0)}ms total)`);
+
+  const ratio = v3.perRun / v10.perRun;
+  const direction = ratio < 1 ? 'faster' : 'slower';
+  console.log(`\n  v3 is ${(ratio < 1 ? 1 / ratio : ratio).toFixed(2)}x ${direction} than v10`);
+}
+
+main();

scripts/benchmark.ts

@@ -0,0 +1,92 @@
+// Benchmark: postcss-calc (pratt) vs @csstools/css-calc on the harvested
+// real-world corpus.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { tokenize } from '../src/pratt/src/core/tokenizer.ts';
+import { parse } from '../src/pratt/src/core/parser.ts';
+import { simplify } from '../src/pratt/src/core/simplify.ts';
+import { serialize } from '../src/pratt/src/core/serialize.ts';
+import { calc as csstoolsCalc } from '@csstools/css-calc';
+
+const ROOT = dirname(fileURLToPath(import.meta.url));
+const CORPUS = join(ROOT, '..', 'src/pratt/test/corpus/github-pure.txt');
+const corpus = readFileSync(CORPUS, 'utf8')
+  .split('\n')
+  .map((l) => l.trim())
+  .filter(Boolean);
+
+const ours = (s: string): string | null => {
+  try {
+    return serialize(simplify(parse(tokenize(s))), { precision: false });
+  } catch {
+    return null;
+  }
+};
+const theirs = (s: string): string | null => {
+  try {
+    const r = csstoolsCalc(s);
+    return typeof r === 'string' ? r : null;
+  } catch {
+    return null;
+  }
+};
+
+interface Stat {
+  name: string;
+  totalMs: number;
+  okCount: number;
+  threwCount: number;
+}
+
+function bench(name: string, fn: (s: string) => string | null): Stat {
+  for (let i = 0; i < 3; i++) for (const s of corpus) fn(s);
+
+  const ITERS = 5;
+  let okCount = 0;
+  let threwCount = 0;
+  const start = performance.now();
+  for (let it = 0; it < ITERS; it++) {
+    okCount = 0;
+    threwCount = 0;
+    for (const s of corpus) {
+      const r = fn(s);
+      if (r === null) threwCount++;
+      else okCount++;
+    }
+  }
+  const totalMs = (performance.now() - start) / ITERS;
+  return { name, totalMs, okCount, threwCount };
+}
+
+console.log(`Corpus: ${corpus.length.toLocaleString()} real-world calc() expressions`);
+console.log('Running 3 warmup + 5 measured iterations each…\n');
+
+const a = bench('postcss-calc (pratt)', ours);
+const b = bench('@csstools/css-calc  ', theirs);
+
+const fmt = (s: Stat): string => {
+  const perCallUs = (s.totalMs * 1000) / corpus.length;
+  return [
+    s.name,
+    `total ${s.totalMs.toFixed(1).padStart(6)} ms`,
+    `${perCallUs.toFixed(2).padStart(5)} µs/expr`,
+    `accepted ${s.okCount.toString().padStart(5)}`,
+    `threw ${s.threwCount.toString().padStart(4)}`,
+  ].join('   ');
+};
+console.log(fmt(a));
+console.log(fmt(b));
+
+const ratio = b.totalMs / a.totalMs;
+const speedLabel =
+  ratio >= 1
+    ? `${ratio.toFixed(2)}× faster`
+    : `${(1 / ratio).toFixed(2)}× slower`;
+console.log(`\nSpeed: postcss-calc is ${speedLabel} than csstools.`);
+console.log(
+  `Coverage: postcss-calc accepts ${a.okCount}, csstools accepts ${b.okCount} ` +
+    `(diff ${a.okCount - b.okCount > 0 ? '+' : ''}${a.okCount - b.okCount}).`
+);