Skip to content

fix(docs): compare tsconfig options order-insensitively - #14

Merged
bloxster merged 2 commits into
mainfrom
fix/drift-guard-canon
Jul 27, 2026
Merged

bloxster merged 2 commits into
mainfrom
fix/drift-guard-canon

Conversation

@bloxster

Copy link
Copy Markdown
Contributor

Why

JSON.stringify(a) !== JSON.stringify(b) is order-sensitive for objects, so an upstream key reordering would report drift and fail CI even when the options are semantically identical — a false positive in exactly the scenario the guard exists to handle.

Found by Copilot on erigontech/erigon#22764 and fixed there first; this propagates the same fix so the three docs sites keep an identical guard.

Fix

function canon(v) {
  const norm = (x) =>
    Array.isArray(x) ? x.map(norm)
      : x && typeof x === "object"
        ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, norm(x[k])]))
        : x;
  return JSON.stringify(norm(v));
}

Objects get sorted, arrays do not. Sorting arrays too would be the tempting over-application, but paths entries are an ordered fallback list — that would trade a false positive for a false negative.

Verification

case expected result
baseline pass pass
upstream reorders compilerOptions keys pass (was failing) pass
upstream reorders a paths array still fail fail
target ES2022 -> ES2023 still fail fail

npm run check:tsconfig passes clean after the change.

🤖 Generated with Claude Code

bloxster and others added 2 commits July 27, 2026 17:14
`JSON.stringify(a) !== JSON.stringify(b)` is order-sensitive for objects, so an
upstream key reordering would report drift and fail CI even when the options
are semantically identical — a false positive in exactly the scenario the guard
exists to handle.

Canonicalize before comparing: object keys sorted recursively, array order
preserved. Arrays stay order-sensitive deliberately — `paths` entries are an
ordered fallback list, so a genuine reordering there must still report.

Found by Copilot on erigontech/erigon#22764 and fixed there first; this
propagates the same fix so the three docs sites keep an identical guard.
Verified against four cases: baseline passes; upstream reordering
compilerOptions keys now passes; reordering a `paths` array still fails; a real
value change (target ES2022 -> ES2023) still fails.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The comment claimed "Array order IS meaningful" for tsconfig arrays in general,
which overstates it: order matters for a `paths` fallback list but not for
`lib` or `types`. Flagged by Copilot on erigontech/cocoon#39.

The implementation is unchanged and stays correct — preserving order everywhere
is the safe direction, since a reordered `lib` costs one harmless
reconciliation whereas sorting arrays would silently hide a real `paths`
change. Only the justification is reworded to say that rather than implying all
tsconfig arrays carry ordered semantics.

Comment-only; the three copies stay byte-identical (normalised).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@bloxster
bloxster merged commit 0e0a238 into main Jul 27, 2026
1 check passed
@bloxster
bloxster deleted the fix/drift-guard-canon branch July 27, 2026 16:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant