* docs(#3881): answer §8.1's open question and correct three wrong premises ADR-3473 §8.1 carries a blocking open question with a forcing function: it must be answered before any implementation PR for the rule opens. Answered here as (a), a string-coercing adapter, with the measurement that settles it. The sequencing note bet that §8.8's schema would make (b) tractable. Measured against merged reality it does not: only 33 of extractFrontmatter's 78 non-test call sites read STATE.md, and two of the five compensating mechanisms §8.1 lists survive real types, leaving ~31 lines across 3 call sites as the actual prize. Also corrects three claims verified false while answering it. §8.1's justifying sentence names #3349 and #3360 as defects a real parser would fix; both are already fixed on next, confirmed by executing the compiled parser rather than reading it. The guard roster calls lint-frontmatter-scalar-broad-grep.cjs an expected casualty of this rule, but it guards shell grep idioms in workflow bash fences and never touches our parser. The same roster calls lint-vendored-deps.cjs reusable as-is; it is hardcoded to re2js throughout. The last two were caught by applying the rule this amendment records -- a factual claim in this ADR is a hypothesis until the implementing phase executes it -- on its first use. Refs #3881 * docs(#3881): record that §8.1's fork is ill-posed and (a) is not implementable An adversarial pass on the Phase 4 design established by execution that extractFrontmatter is not a YAML parser but a line-oriented scanner whose output is a function of raw source text. Four spellings of the same value collapse to one js-yaml tree but produce four distinct legacy strings, one of them mangled. No adapter over a tree can choose among outputs the tree does not distinguish, so fork (a) -- keep a string-coercing adapter so the existing contract holds -- cannot be built. For any document with a non-scalar value, (a) collapses into (b); about 26 percent of frontmatter-carrying documents have one. Also records three design defects and one new attack surface, all confirmed by execution: catching a parse failure and returning {} would delete the frontmatter block on the next write at eight call sites that conflate empty with unparseable; an empty value yields null where legacy yields {}, and reconstructFrontmatter omits null-valued keys, so the shipped state template's empty progress key would vanish; the #1882 truncation probe is parseYamlRegion itself rather than a pre-parse heuristic, so it cannot both stay unchanged and survive that deletion; and FAILSAFE_SCHEMA still resolves aliases, expanding seven lines to 22.8 MB. The rule is not deferred. The measurement is the deliverable and the re-scoping is recorded as an open question with a forcing function, per section 8's own rule. Refs #3881 * test(#3881): failing-first rows for block scalars, unicode keys and the missing #3594 matrix Creates tests/feat-3594-parser-adversarial-frontmatter.test.cjs, the file the fixture README instructs contributors to register fixtures in but which never existed. Section C: table-driven ownership check over tests/fixtures/adversarial/frontmatter/ so a fixture with no matrix entry fails loudly; six existing fixtures (duplicate-keys, crlf-mixed, unclosed-block, unicode-keys-and-values, null-byte-value, huge-bounded) each get the invariant its README states. B1 blockScalarValueIsNotTheBlockIndicator: parsing commands/gsd/add-tests.md must give argument-instructions the instruction text, not the literal '|'. RED today. B2 blockScalarDoesNotInventATopLevelKey: same parse must not produce a top-level Example key scraped from inside the block body. RED today. B3 unicodeKeyRoundTripsAsIs: the 相 key in unicode-keys-and-values.md must survive parsing; today it is silently dropped. RED today. Refs #3881 * chore(#3881): vendor js-yaml and generalize the vendored-deps guard to a manifest Packaging step for ADR-3473 §8.1: makes js-yaml available to gsd-core/bin/** without promoting it out of devDependencies (promoting broke every installed tree, #3496). gsd-core/bin/lib/vendor/js-yaml.cjs is a verbatim copy of node_modules/js-yaml/dist/js-yaml.js (the self-contained UMD dist bundle, not index.js), exposing load/dump/FAILSAFE_SCHEMA/YAMLException with zero require() calls of its own. src/vendor/js-yaml.d.cts is hand-authored, not copied, because js-yaml ships no upstream .d.ts and @types/js-yaml is not installed. It is deliberately narrow, declaring only the four symbols in use, so anchors/aliases/custom types/loadAll are unreachable from typed code -- a compile-time enforcement of ADR-3473 §8.1's refusal to expand alias resolution for security reasons. Because it has no upstream counterpart it is excluded from the byte-compare. scripts/lint-vendored-deps.cjs is refactored from a script hardcoded to re2js into a table-driven VENDORED manifest (one row per package: upstream/vendored .cjs paths, optional .d.cts paths, twin kind upstream-verbatim vs hand-authored) so a second vendored package does not require a second hardcoded check block, per ADR-3473 §8.3 'one implementation per rule'. The four existing re2js checks (vendored .cjs vs node_modules, vendored .d.cts vs node_modules, src/vendor twin vs bin-side twin, devDependency version pin vs installed version) are preserved unchanged; verified pass/fail identical before and after the refactor, and the guard's ability to fail was re-proven with a deliberate one-byte append to both re2js.cjs and js-yaml.cjs, then restored. docs/INVENTORY.md and docs/INVENTORY-MANIFEST.json (via gen-inventory-manifest.cjs --write, run after build:lib) register vendor/js-yaml.cjs. gsd-core/bin/lib/vendor/README.md documents both vendored packages and the two twin kinds. Refs #3881 * feat(#3881): parse .planning frontmatter with the vendored js-yaml ADR-3473 §8.1: extractFrontmatter's read path is no longer a hand-rolled line scanner. parseYamlRegion, escapeDoubleQuoted, unescapeDoubleQuoted and parseQuotedScalar are deleted (not patched); parsing now goes through the vendored js-yaml (./vendor/js-yaml.cjs) under { schema: FAILSAFE_SCHEMA, json: true }. Everything js-yaml does not do is layered on top, in one place, carrying the seven design-doc consequences: 1. Empty value: a null js-yaml value is coerced to {} (matching legacy's own empty-value contract) so reconstructFrontmatter — which omits null-valued keys — still round-trips a bare `key:` line instead of deleting it. Verified live: progress: with no value survives parse -> reconstruct -> re-parse. 2. Unparseable no longer collapses to a bare {}: a new FRONTMATTER_UNPARSEABLE Symbol (exported), keyed exactly like the existing #3257 FULL_LINE_COMMENTS channel, is carried on the {} returned for malformed/refused YAML. Invisible to Object.keys/entries/JSON.stringify/for-in, so the 70 call sites that never inspect it are unaffected; wiring the 8 hasFrontmatter sites to consult it is a separate change, not done here. 3. Non-scalar object-list items (the four spellings of `- test: a b` that js-yaml collapses into one tree shape) are rendered as a canonical `key: value[, key2: value2]` string per item, keeping the existing array-of-strings value SHAPE. A full corpus differential over all 1702 tracked markdown files found 11 residual divergences from the legacy parser (enumerated in the PR/report), most of them the parser now being MORE correct (a dropped quoted top-level key, the block-scalar/phantom-key defect, a dropped Unicode key). 4. The #1882 truncation probe still runs the one real parser, but derives its key count from js-yaml's own thrown error and mark.line when the whole region doesn't parse cleanly (the dominant real truncation shape: fence opened, well-formed keys, no closing fence). Verified against both the clean-parse and the exception-fallback path. 5. The #3257 comment channel now attributes each pending column-0 comment against js-yaml's own parsed top-level key list (matched by literal key text, in document order) instead of the legacy ASCII-only key regex, so a comment above a Unicode key attaches correctly. 6. Anchors, aliases and merge keys are refused outright (a raw-text pre-scan, since FAILSAFE_SCHEMA still resolves them) — corpus occurrences today: zero. A 7-line billion-laughs fixture is verified refused rather than expanded. 7. A literal U+0000 is swapped for a private-use sentinel before the parse and restored in every resulting string afterward, since js-yaml rejects NUL unconditionally under every schema. escapeDoubleQuoted is deleted and reimplemented via js-yaml's dump() (forced double-quoted style), with control-char hex escapes lowercased to keep serialized output byte-stable (#1779 emitted lowercase); it keeps its exported name and signature for its two other call sites (commands.cts, runtime-artifact-conversion.cts), which need no change. frontmatterDeepEqual, the comment channel, sliceTopLevelFrontmatterSegments, regenerateFrontmatterKey's guard, noOpObjectListSetError and parseMustHavesBlock are all unchanged — retiring them is fork (b) and is not this phase. Refs #3881 * fix(#3881): quote template placeholders and preserve unparseable frontmatter SECURITY.md/UI-SPEC.md/VALIDATION.md wrote frontmatter placeholders as bare {N}/{phase-slug}/{date}, which is valid YAML flow-mapping syntax under the vendored js-yaml parser, not the literal placeholder text intended. Quote them so they parse as strings. Wire the FRONTMATTER_UNPARSEABLE Symbol (exported but unused) at the 8 call sites in state.cts/state-transition.cts that compute hasFrontmatter via Object.keys(extractFrontmatter(...)).length > 0 and reassemble the document without a frontmatter block when false. That check conflated 'no frontmatter' with 'unparseable frontmatter' (both parse to {}), so a document with a merge-conflict marker or refused alias in its frontmatter had that block silently dropped on write. Each site now preserves the exact raw bytes stripFrontmatter removed when the marker is set, leaving the genuinely-empty case unchanged. Refs #3881 * test(#3881): consequence and boundary coverage for the js-yaml migration Rows: A1 emptyValuedKeySurvivesAWrite, A2 unparseableDocumentKeepsItsFrontmatterBlock, A3 unparseableIsDistinguishableFromEmpty, A4 nonScalarValuesCanonicalize, A5 truncationProbeStillFiresOnAnOpenFence, A6 commentsStayOnTheirOwnKey, A7 anchorsAndAliasesAreRefused, A8 aliasExpansionCannotExhaustMemory, F1 UNTERMINATED_KEY_THRESHOLD boundary, F2 alias/nesting refusal bound, F3 frontmatter size boundary (huge-bounded.md + larger). Adds tests/fixtures/adversarial/frontmatter/anchor-alias-bomb.md and its entry in the feat-3594 fixture matrix. Refs #3881 * docs(#3881): document the vendored parser, correct a stale rationale, add a vendoring how-to Refs #3881 * docs(#3881): correct the frontmatter glossary entry Two errors in the entry as first written: it named parseYamlRegion as part of the read path when that function is deleted, and it recorded the eight hasFrontmatter call sites as unwired follow-on work when they were wired in e35ac2a2c. Also records the scope caveat that the CLI write path rebuilds the frontmatter block independently, so the marker binds at the transform layer. Refs #3881 * docs(#3881): record the semantic-migration decision and the counted guard ledger The maintainer chose the full semantic migration over splitting the rule into its own epic or patching the scanner, so section 8.1 is answered as "the fork was ill-posed and the migration is semantic" rather than as (a) or (b). Also replaces the pre-implementation guess that this phase would shrink the guard surface with the counted result: excluding vendored third-party lines the hand-maintained surface is net +307, and frontmatter.cts grew by 68 lines despite four functions being deleted, because the compatibility layer over js-yaml is larger than the scanner it replaced. Section 8.1's stated benefit is therefore not delivered as written; what improved is the kind of code maintained, not the amount. Decision 6 requires recording that rather than netting it away. Refs #3881 * chore(#3881): changeset for the vendored YAML parser migration Refs #3881 * test(#3881): golden parity, round-trip property and packaging coverage Refs #3881 * fix(#3881): refuse anchors structurally and fold in review findings ADR-3473 §8.1 review findings, addressed inline: Finding 1 (BLOCKER): refuseAnchorsAndAliases was a raw-line regex that matched only the bare-key spelling (key: &x). A quoted key ("a": &x), a flow mapping ({b: &x}) and a flow sequence ([&x, *x]) all define/use the SAME anchor mechanics while never matching that line shape, so the exact expansion the guard exists to stop went straight through unrefused (a 303-byte quoted-key bomb expanded to ~35.8MB). Replaced with js-yaml's own `load` `listener` callback, which reports `state.anchor` for every event belonging to an anchored node in every spelling, and throws from inside the callback to abort before any expansion (~1-2ms vs full expand-then-discard). A merge key with an alias is still refused (merge always requires a previously anchored node, so the alias itself trips the listener); a bare merge key with NO alias is no longer separately refused, documented as intentional: FAILSAFE_SCHEMA never resolves `!!merge`, so it carries no expansion risk. Table-driven tests added for all four bypass spellings + merge key, plus a quoted-key-spelled billion-laughs fixture registered in the adversarial matrix and README. Finding 2: src/vendor/js-yaml.d.cts's docblock falsely claimed anchors/ aliases were "simply UNREACHABLE from typed code" through the twin. Corrected to state the truth: anchor/alias resolution is document-level `load` mechanics reachable through exactly the declared surface, and refusal is enforced at RUNTIME (Finding 1's listener), not by the type surface. Finding 3 (MAJOR): the null-byte sentinel (U+E000) round-trip was non-injective — restoreNullBytesDeep rewrote every U+E000 in the parsed tree back to NUL, including one the document author legitimately wrote, silently corrupting it. Now refuses outright whenever the raw region already contains U+E000 (consistent with the existing anchor/merge-key refusal path), making the substitution provably injective. Tests added for a real NUL alone (preserved), a pre-existing U+E000 alone (refused, not corrupted), and both together (refused, not merged into one byte). Finding 4 (MAJOR): scripts/lint-vendored-deps.cjs's `srcTwin` field was dead for a hand-authored row (only read inside the upstream-verbatim branch) — exactly how Finding 2's stale docblock drifted unnoticed. Added checkHandAuthoredTwin: every value-level export the twin DECLARES must be an actual own property of the vendored runtime module at require-time. Tests added, including a sensor that a declared-but-nonexistent export IS caught. Finding 5: the existingFm/hasFrontmatter/stripFrontmatter/fmPrefix/ unparseableFm/reassemble preamble, copy-pasted at 7 sites in state-transition.cts plus a sixth hand-inlined copy in state.cts's cmdStateCompletePhase, is now one exported helper (beginFrontmatterReassembly) every site routes through, including the hand-inlined one. Three call sites (beginPhaseCore, patchCore, updateCore) keep a literal `body = stripFrontmatter(content)` assignment alongside the helper call so scripts/lint-state-write-path-drift.cjs's single-hop backward scan (which does not chase aliases) still sees the strip; stripFrontmatter is pure/idempotent so the extra call changes nothing observable. Finding 6: corrected the frontmatter.cts docblock's stale "wiring is a separate change" claim (the 8 call sites are wired on this branch) and the changeset's backlink from (#3473) to (#3881). Finding 7: fixed the lint:ci failures blocking the gate — an @typescript-eslint/only-throw-error violation from throwing a bare Symbol as the anchor-detected signal (now a real Error subclass), unused-var warnings left over from the Finding 5 refactor, a lint-test-file-count cap exceeded by two migration-specific test files (allowlisted with justification), and the lint-state-write-path-drift false positive from Finding 5's helper (fixed above). tests/frontmatter-golden-parity.test.cjs:117's execFileSync already carried an explicit timeout; no change was needed there. Golden fixture: added a golden entry for the new anchor-alias-bomb-quoted.md fixture ({} — matches what the legacy line scanner would also produce, since it independently dropped every quoted top-level key). No other corpus document diverges: real .planning/ documents carry zero anchors/aliases/merge keys/U+E000 today. Refs #3881 * fix(#3881): fold in second-round review findings Finding 1 (BLOCKER): tests/frontmatter.test.cjs pinned the pre-migration ASCII-only key regex for the Unicode fixture; updated to require the 相 key's value now that js-yaml has no such restriction. Audited the rest of the file for other pre-migration pins (block scalars, quoted keys, flattened values, empty values, duplicate keys, unclosed blocks, null bytes) by execution against real fixtures; found none regressed. Finding 2: parseYamlRegion and escapeDoubleQuoted renamed to parseGuardedYamlRegion and escapeDoubleQuotedScalar in src/frontmatter.cts so no function still answers to the deleted hand-rolled scanner's name (ADR-3473 §8.1 "deleted, not patched"). escapeDoubleQuotedScalar's three external call sites (src/commands.cts, src/runtime-artifact-conversion.cts) updated in the same change — a mechanical rename, not an ADR-amendment matter. Finding 3 (BLOCKER): fixed a real crash and a silent data-loss bug found by execution. A top-level key named constructor/__proto__/toString/ valueOf/hasOwnProperty crashed reconstructFrontmatter (bracket read resolving an inherited Object.prototype member); a key literally named __proto__ was silently DROPPED entirely (bracket assignment on an ordinary {} invoked the inherited __proto__ setter instead of creating a data property). Fixed by building every parsed Frontmatter object with Object.create(null), and replacing an `in` check with hasOwnProperty.call in propagateCommentChannel. Added round-trip tests for all five hostile keys, each with its own leading comment. Finding 4 (MAJOR): escapeDoubleQuotedScalar's docstring falsely claimed full byte-stability across the migration. Verified by execution: BEL/NUL/ NEL/NBSP/LS/PS/BOM now emit YAML-named escapes instead of the old hex/raw- literal forms. Proved round-trip equivalence (each escape re-parses to the exact source codepoint) and corrected the docstring. Found and fixed a related real defect while verifying: a lone UTF-16 surrogate was emitted BARE (scalarNeedsDoubleQuoting didn't trigger), producing genuinely unparseable YAML that silently collapsed to {} on re-read — extended scalarNeedsDoubleQuoting to route surrogates through the quoted+escaped path. Finding 5 (MAJOR): countKeysBeforeTruncation went silent on 4 real truncation shapes (unquoted colon, open flow collection, mis-indented sibling key, refused anchor). Root cause: the mark-based prefix recovery excluded the very line whose key needed counting, and a mark-less refusal never entered the recovery branch at all. Fixed by taking the max of two lower bounds: the longest parser-verified line-prefix, and a raw-text count of key-shaped lines (reusing the same key-shape pattern this file already uses for isFrontmatterShaped). Extended test-matrix row A5 table-driven over all 4 regressed shapes. Finding 6: the design doc's claim that no test owned the #3594 adversarial fixture corpus was false — consolidation epic #1969 had already folded it into tests/frontmatter.test.cjs. An earlier commit on this branch re-created a standalone duplicate under that false premise; folded its genuinely-new coverage (fixture-ownership check, anchor-bomb fixtures, block-scalar B1/B2 rows) into frontmatter.test.cjs and deleted the duplicate file. Corrected the false claims in 40-design.md §3.3.1 and the ADR's §8.1 note, including the roadmap-sibling claim (no such file exists). Finding 7: the golden serializer sorted object keys, making it structurally blind to the key-order-parity invariant ADR-3473 §8.1 actually claims. Made it order-preserving and regenerated the golden fixture from a standalone compile of the legacy (pre-#3881) parser at ddde001af; the current parser matches it with zero undocumented divergences, confirming key-order parity genuinely holds. Extended row A2 table-driven across 6 of the remaining 7 transitionCore kinds (all pass) plus documented, by execution, a newly-discovered 8th-site regression: state.cts's cmdStateCompletePhase calls the same preservation helper but its result is clobbered by a later unconditional resync — filed as a distinct finding rather than fixed here (touches syncAndPreserveStateMd, outside this change's verified scope). Refs #3881 * fix(#3881): preserve unparseable frontmatter through the CLI write path Characterization (executed, before/after shown): case (b), not (a). The frontmatter FENCE survives — `state complete-phase` on a conflict-marked STATE.md returns success and a well-formed, freshly-derived frontmatter block, not a document with no frontmatter at all. But the block's actual content (the merge-conflict markers, and with them any signal to a human that the document was in conflict) is silently discarded and replaced. Root cause was two clobber sites, not one: 1. syncStateFrontmatter (src/state.cts) re-parses the already-preserved `transformedContent` from readModifyWriteStateMd, finds {} + the FRONTMATTER_UNPARSEABLE marker, and unconditionally rebuilt a fresh frontmatter block from the body anyway. 2. Even after (1) is fixed, applyPostSyncPreservation's own postFm/applyStatePreservation/authoritativeFm-reassertion machinery re-extracts frontmatter from syncedContent, restores curated fields from the pre-write snapshot, and reconstructs a NEW block again — confirmed live via `state begin-phase`, which still lost the markers after fixing (1) alone. Both are now guarded by the same predicate (isUnparseableFrontmatter, checking FRONTMATTER_UNPARSEABLE): when the ORIGINAL frontmatter did not parse and the caller is not on ADR-3408 §8.3's closed "body wins" list, both functions return their input content unchanged rather than re-deriving over it. The closed list (cmdStateSync #905, /gsd-health --repair's REGENERATE_STATE, both routed only through writeStateMd, which never reaches applyPostSyncPreservation and passes sanctionedPermanentEmptyFallback=true to syncStateFrontmatter) is untouched — neither widened nor narrowed; verified by execution that `state sync` still overwrites the conflict-marked block exactly as before. Other verbs sharing the same readModifyWriteStateMd path were checked and were equally affected before this fix: state update, query state.patch, and state begin-phase all lost the conflict markers (RED, shown by execution), and all three now preserve them (GREEN). Covered table-driven in tests/feat-3881-yaml-parser-consequences.test.cjs's new A2b describe block, which drives the real CLI verbs via runGsdTools — not just the pure transitionCore layer the earlier A2 rows exercised — plus a control asserting state sync's body-wins contract is unchanged. Refs #3881 * fix(#3881): restore the parse surface's prototype and fix remote-runner failures Root cause of the bulk of the 88 remote-runner failures: extractFrontmatter/parseGuardedYamlRegion handed back Object.create(null) trees for prototype-pollution safety, but assert.deepStrictEqual compares prototypes, so every assertion against a plain object literal failed (57 frontmatter.unit.test.cjs + 5 frontmatter.test.cjs + others). Fixed by keeping the internal construction null-prototype (unchanged) and converting to a plain-prototype tree via Object.defineProperty (never bracket assignment, so __proto__/constructor/toString keys stay safe) at the parseGuardedYamlRegion/unparseableResult return boundary only; the internal FULL_LINE_COMMENTS Symbol channel is copied by reference, not recursed, so its own __proto__-safety is untouched. Per-class fixes: (1) bomAcrossArtifactTypes was the same prototype bug, no separate code change needed. (2) frontmatter-cli #1660: added objectListFieldWouldLoseData, a broader lossy-field detector alongside the existing byte-identical noOpObjectListSetError -- js-yaml's flattenObjectListItem now correctly includes every sub-key of an object-list item (a real bug fix over the legacy scanner, which silently dropped every field but the first), so a set that drops that now-included data is no longer byte-identical to the original and needs its own guard. (3) uat.test.cjs: updated the pinned expectation for the human_verification quote-stripping artifact -- js-yaml resolves quoting correctly where the legacy regex left an unbalanced quote; documented as an intentional, non-lossy behavior change. (4) smart-entry: added a fallback-only loadWithAmbiguousColonRepair so a column-0 key: value line whose value itself contains an unquoted colon (the #2571 hand-edited-STATE.md shape) round-trips instead of failing the whole frontmatter block closed. (5) frontmatter.unit.test.cjs bracket-array leniency: added a second fallback, repairMalformedInlineArrays, restoring the legacy scanner's tolerant inline-array handling (consecutive/blank commas, unclosed bracket) -- both repairs run ONLY after the primary parse already threw, so well-formed documents are unaffected. (6) prompt-injection-scan: src/frontmatter.cts had a literal U+FEFF BOM embedded in a comment illustrating the #2977 fix; replaced with the U+FEFF text escape. (7) eslint-glob-coverage: allowlisted the new src/vendor/js-yaml.d.cts vendored type declaration, same precedent as the existing re2js.d.cts entry. (8) frontmatter-golden-parity: git ls-files *.md now runs with -c safe.directory=* (process-scoped) so it survives the remote runner's dubious-ownership check without a persistent git config write. Refs #3881 * chore(#3881): backfill changeset PR number Refs #3881 * test(#3881): make golden parity resistant to unrelated tree churn A corpus-wide snapshot keyed to every tracked *.md file was coupled to mutable-by-design files: .changeset/*.md's pr:0 -> real-PR-number backfill is a required workflow step, not a parser change, yet it turned this suite red. Training people to 'just regenerate the golden' on that kind of failure defeats the point of the snapshot. Exclude .changeset/** from the golden corpus entirely, tolerate tracked *.md files with no golden entry (they postdate the capture) instead of failing on them, keep hard failures for a golden entry whose file has vanished from the tree and for any real parity divergence, and add a coverage floor so the enumeration cannot quietly degrade to comparing a handful of files. Golden regenerated by recompiling the legacy pre-migration parser (git show ddde001af:src/frontmatter.cts) standalone, independent of the current parser, over the same non-changeset corpus. Refs #3881 * test(#3881): make the parser golden hermetic instead of tree-keyed This repo merges ~21 commits/day; a 14-day sample measured 937 touches of the exact files (commands/gsd/*.md, gsd-core/workflows/*.md, agents/*.md, docs/*.md) the prior golden pinned by tracked path. Any PR editing one of those files' frontmatter for reasons unrelated to the parser (an argument-hint addition, an allowed-tools tweak) turned the suite red, and the reflex fix -- "regenerate the golden" -- overwrote the very snapshot meant to catch a real regression. Excluding .changeset/** was not enough; the design itself was wrong: a regression fixture must not be keyed to mutable repo paths, and a single 376-entry JSON every such PR touches is also a guaranteed merge-conflict surface. Rebuilt the fixture to carry its own documents: each of 51 entries stores a stable id, literal documentText (shrunk from a real ddde001af-era corpus document), and an expectedParse captured independently from the pre-migration legacy parser (git show ddde001af:src/frontmatter.cts, compiled standalone against its byte-identical sibling modules). The test reads no tracked path, shells out to no git command, and enumerates no tree -- a PR editing commands/gsd/help.md cannot affect it. Every entry's reconstruction was verified at capture time to reproduce both the current and legacy parser's output on the original document; 0 of 51 candidates were dropped by that check (1, the deliberately-unterminated unclosed-block.md adversarial fixture, has no closing fence to truncate at and is stored unshrunk). Kept the 5 documented DIVERGENCES rows (now diverges:true entries) and the D2 order-preserving structural serializer that keeps the comparison from passing vacuously; dropped the tree-enumeration helpers, the coverage floor, the post-capture-skip logic, and the vanished-file check -- all artifacts of the path-keyed design. Refs #3881 * fix(#3881): resolve vendored-deps paths independently of cwd shape Five rows in tests/lint-vendored-deps-manifest.test.cjs failed on windows-latest CI: the test passed absolute scratch-file paths into compareFiles()/checkRow(), whose helpers joined every input onto ROOT via path.join(ROOT, rel), producing garbage when the input was already absolute. It surfaced on windows-latest specifically because GitHub's Windows runners checkout the repo on a different drive than TEMP, so path.relative(REPO_ROOT, tmpFile) returned the absolute path unchanged (no relative traversal is representable across drives) rather than the relative form the test assumed. The remote gsd-test runner this repo gates pushes on is Linux-only and could never have caught this; GitHub CI's windows-latest job is the only signal that does, and it did. Fixed the helper itself (scripts/lint-vendored-deps.cjs's new resolvePath()) to treat an already-absolute input as absolute-in, absolute-out instead of silently mis-joining it, and updated the test to pass the scratch file's absolute path directly rather than relying on a relative conversion that is not always representable. Kept every mutation-sensor assertion intact and added coverage proving resolvePath is a no-op for relative inputs and correctly passes absolute ones through unchanged. Refs #3881 * fix(#3881): warn when state sync regenerates over unparseable frontmatter state sync (ADR-3408 §8.3's sanctioned regenerate path) correctly overwrites an unparseable frontmatter block per its 'body wins' contract — that overwrite behavior is unchanged here. The defect was the silence: synced:true/exit 0 gave no signal that the existing block (including git merge-conflict markers) could not be parsed and was destroyed, per ADR-3473 §8.5 ('a derived conclusion may not be reported as authoritative when the derivation dropped input it could not resolve') and §8.4 ('failure is a value'). Adds a gsd: warning — ... (#3881) line on stderr, matching the existing #3573 precedent, and surfaces the same disclosure in the JSON result's existing changes[] array so a machine consumer sees it too. Exit code and synced:true are left unchanged — sync did what its contract says. REGENERATE_STATE (/gsd-health --repair's sibling on the same sanctioned-regenerate list) is DESTRUCTIVE-risk and unconditionally refused by applyRepairs's dispatcher before runRepairAction ever runs (src/health-diagnostic.cts), so it is not a live path today and is not in scope for this fix. Refs #3881 * fix(#3881): exit non-zero when a state command returns an error Refs #3881 * chore(#3881): changeset for the state exit-code fix Refs #3881 * fix(#3881): honor the documented --project-dir flag Refs #3881 * revert(#3881): restore exit-0 result envelopes for state errors Reverts 9638f2936 and its changeset. The change was wrong and the revert is the correction. This repo distinguishes two error mechanisms deliberately. error() in src/io.cts writes to stderr and calls process.exit(1) -- the hard-failure path. output({error: ...}) writes a JSON result envelope to stdout and returns normally with exit 0. The reverted commit converted 23 result-envelope sites into hard failures, which is a different contract, not a bug fix. tests/state-contract.test.cjs's errorPathDoesNotPublish asserts the envelope contract directly -- a failing command exits 0 with a JSON error envelope and must not publish state.json -- and the remote matrix run caught it along with four cases in the QA scenario walk. Thirteen tests in tests/state.test.cjs that the original commit rewrote were encoding that real contract, not the bug it claimed; they are restored. Whether an error envelope on stdout with exit 0 is the right CLI design is a genuine question, and it is section 8.4's rule ('failure is a value') with its own phase. It is not something to flip inside this PR. Refs #3881 * chore(#3881): backfill changeset PR number for the project-dir fix Refs #3881 * test(#3881): keep the frontmatter mutation shard inside its time budget The Stryker (frontmatter) shard hit the documented 15-minute (900s) shard cap. Root cause is NOT row-level spawn overhead (contrast the #2790/ core-utils precedent): the three shard test files' own logic runs in ~413ms total (356+30+27ms) with all 392 assertions passing. Instead, src/frontmatter.cts grew from ~825 to 1496 lines (+671/-187) migrating to the vendored YAML parser, proportionally growing the mutant count Stryker generates for gsd-core/bin/lib/frontmatter.cjs. Stryker's command runner bills the full 'node --test <3 files>' invocation once per mutant, and node:test's default per-file process isolation forks a child process for each of the three files on every one of those invocations — pure fork overhead multiplied by a much larger mutant population. Fix: scripts/mutation-matrix.cjs COVERED.frontmatter now declares isolation: 'none', and .github/workflows/mutation.yml passes --test-isolation=${{ matrix.isolation }} (defaulting to 'process' — i.e. unchanged behavior — for the other 8 shards, which were not individually audited for cross-file state leakage under shared-process execution). Measured locally via node:test's run() API on the exact 3-file set: isolation:'process' took ~593ms vs isolation:'none' ~478ms for the same 392 passing assertions. The true CI-shard number can only be confirmed on the GitHub Actions run (Stryker cannot run locally, and 'node --test' is hard-blocked in this environment). Refs #3881 * test(#3881): register the vendored-parser tests in the frontmatter mutation shard stryker.config.mjs's own rule ("Keep this list in sync with the tests arrays in scripts/mutation-matrix.cjs COVERED") was violated: #3881 grew src/frontmatter.cts from ~825 to 1496 lines but its new tests (tests/feat-3881-yaml-parser-consequences.test.cjs, tests/frontmatter-golden-parity.test.cjs, tests/frontmatter-roundtrip.property.test.cjs, and +167 lines in tests/frontmatter.test.cjs) were never added to the frontmatter shard's tests array, so Stryker's mutants in the new vendored-js-yaml adapter had nothing constraining them. PR #3888 measured 55.8% against the 65 floor (748 killed / 593 survived / 17 timeout) and the shard was separately cancelled at 15m04s against the 15-minute per-shard cap. Registers all four files (each earns its slot on evidence of a unique constraining assertion, documented inline), gives the shard a measured/projected 180-minute budget via a new per-module timeoutMinutes field threaded through mutation.yml's job-level timeout-minutes the same way isolation is threaded, and removes the prior isolation:'none' override (re-measured at this file-set size, its savings are within run-to-run noise, not worth the unaudited cross-file-state-leakage risk). Refs #3881 * feat(#3881): derive the mutation test list and ratchet the score floor Refs #3881 * test(#3881): ratchet five stale mutation floors and close the frontmatter gap Raised five module minScore floors per CI run 33012034388 (floor(achieved)-1): config-schema 75.51%->74, prompt-budget 88.95%->87, context-composer 79.92%->78, context-utilization 92.31%->91, active-workstream-store 87.42%->86. Updated both scripts/mutation-matrix.cjs COVERED entries and tests/mutation-matrix-ratchet.test.cjs RATCHET_BASELINE in the same diff per the ratchet's own contract. Closed the frontmatter shard's 63.03%-vs-65 gap with new behavioral tests in tests/feat-3881-yaml-parser-consequences.test.cjs, each paired with a documented near-miss: frontmatterDeepEqual's array-order/length/type-mismatch/key-order semantics (via spliceFrontmatter's no-op guard), scalarNeedsDoubleQuoting's leading/trailing-whitespace and dash/surrogate triggers (via reconstructFrontmatter), repairAmbiguousColonValues' already-quoted vs ambiguous-colon repair paths (via extractFrontmatter), and the null-byte sentinel round-trip surviving at region offset 1. Did not lower minScore. Refs #3881 * test(#3881): decouple the ratchet test from real module floors The CLI end-to-end rows in tests/mutation-score-ratchet.test.cjs hardcoded config-schema's real floor (52), which commit 973321541 legitimately ratcheted to 74 -- breaking a test pinned to the exact value the mechanism under test exists to change. Add an injectable --matrix seam to scripts/check-mutation-score-ratchet.cjs and point the CLI rows at a synthetic module + synthetic floor built via a temp fixture, so the rows are indifferent to any real module's floor moving while still exercising the same fail/pass behaviour. Refs #3881 * refactor(#3881): parse must_haves with the vendored parser and drop re-implemented leniency Refs #3881 * fix(#3881): restore the ambiguous-colon repair its hand-edited-STATE.md contract needs A tracked-document sweep of 910 *.md files cannot see this dependent: repairAmbiguousColonValues's one real caller is user hand-edited STATE.md content that never lives in this repo's tree, only on end users' machines, and is pinned by tests/smart-entry.unit.test.cjs. Restores the function plus its post-throw fallback path (loadWithAmbiguousColonRepair) only; repairMalformedInlineArrays and splitLegacyInlineArrayItems stay deleted, reverified against the full frontmatter test shard. Adds a frontmatter-level regression row in tests/feat-3881-yaml-parser-consequences.test.cjs so the dependency is visible where the function lives. Closes #2571 Refs #3881 --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
5
.changeset/jolly-geese-roar.md
Normal file
5
.changeset/jolly-geese-roar.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 3888
|
||||
---
|
||||
**`.planning/` frontmatter is now parsed by a real YAML parser.** Block scalars, quoted keys and non-ASCII keys are read correctly instead of being mangled or silently dropped, and a document whose frontmatter cannot be parsed keeps its frontmatter block instead of losing it on the next write. (#3881)
|
||||
5
.changeset/patient-jaguars-frolic.md
Normal file
5
.changeset/patient-jaguars-frolic.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Fixed
|
||||
pr: 3888
|
||||
---
|
||||
**`gsd-tools --project-dir <path>` now works** — the flag was documented in docs/CONFIGURATION.md's multi-repo workspace resolution section but wired nowhere, so it was silently ignored and every command still resolved the project root from cwd. Passing `--project-dir` now sets the project root directly and skips the ancestor walk-up, as documented. (#3881)
|
||||
23
.github/workflows/mutation.yml
vendored
23
.github/workflows/mutation.yml
vendored
@@ -108,7 +108,11 @@ jobs:
|
||||
# GitHub-hosted runners only. Speed comes from running shards in PARALLEL
|
||||
# (one job per changed module), not from larger/3rd-party runners.
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15 # per-shard; lower than the old 30-min serial budget
|
||||
# Per-shard; lower than the old 30-min serial budget. Matrix-driven so only shards that
|
||||
# document a measured need (mutation-matrix.cjs COVERED[<module>].timeoutMinutes, e.g.
|
||||
# frontmatter's 180) get more; every other shard keeps the 15-minute default emitted by
|
||||
# buildResult() in scripts/mutation-matrix.cjs.
|
||||
timeout-minutes: ${{ matrix.timeoutMinutes }}
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix: ${{ fromJSON(needs.detect.outputs.matrix) }}
|
||||
@@ -143,7 +147,7 @@ jobs:
|
||||
# repo's no-defer rule.
|
||||
env:
|
||||
NODE_OPTIONS: '--max-old-space-size=4096'
|
||||
MUTATION_TEST_CMD: node --test ${{ matrix.tests }}
|
||||
MUTATION_TEST_CMD: node --test --test-isolation=${{ matrix.isolation }} ${{ matrix.tests }}
|
||||
MUTATION_BREAK: ${{ matrix.minScore }}
|
||||
MODULE_NAME: ${{ matrix.name }}
|
||||
MUTATE_GLOB: ${{ matrix.mutate }}
|
||||
@@ -155,6 +159,21 @@ jobs:
|
||||
echo "MinScore: ${MUTATION_BREAK}"
|
||||
npx stryker run --incremental --mutate "${MUTATE_GLOB}"
|
||||
|
||||
- name: Check score ratchet — ${{ matrix.name }}
|
||||
# #3881 follow-up, mutation-matrix piece 3: only runs when the shard above actually
|
||||
# passed (a failed shard is a floor problem — Stryker's own MUTATION_BREAK exit code
|
||||
# already reports that; this step is strictly about a floor that should be RAISED).
|
||||
# Reads the 'json' reporter's reports/mutation/mutation.json (stryker.config.mjs)
|
||||
# and fails, with the exact remedy, when the achieved score clears the module's
|
||||
# declared floor by more than scripts/check-mutation-score-ratchet.cjs's documented
|
||||
# slack — the "ratchet up" half of the piece-3 requirement. The "never lower without
|
||||
# a reasoned marker" half is enforced separately, at review time, by
|
||||
# tests/mutation-matrix-ratchet.test.cjs's RATCHET_BASELINE equality check.
|
||||
if: success()
|
||||
env:
|
||||
MODULE_NAME: ${{ matrix.name }}
|
||||
run: node scripts/check-mutation-score-ratchet.cjs --module "${MODULE_NAME}"
|
||||
|
||||
- name: Upload mutation report — ${{ matrix.name }}
|
||||
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
|
||||
if: always() # upload even on failure so the score is visible
|
||||
|
||||
@@ -21,7 +21,7 @@ Module owning the pure phase-id parsing and matching helpers: phase-name normali
|
||||
Module owning phase create, rename, complete, remove, list, and plan-index operations, plus phase-dir prefix validation, STATE.md staleness detection, and auto-prune behaviour. Entry point: `gsd-core/bin/lib/phase.cjs` (CJS surface). Typed phase events: `GSDPhaseStartEvent`, `GSDPhaseStepStartEvent`, `GSDPhaseStepCompleteEvent`, `GSDPhaseCompleteEvent`. (The SDK native-query surface, the `types.ts` event definitions, `phase-runner.ts`, and `phase-prompt.ts` were retired with the SDK package per ADR-0174.)
|
||||
|
||||
### Phase Estimation Module
|
||||
Module owning phase-effort estimation and its calibration against measured reality (ADR-2629, epic #1952). Pure — no I/O, no config reads; the CLI seam (`src/estimate-cli.cts`, verbs `estimate-check` / `estimate-calibration`) owns reading `.planning/config.json` and `.planning/estimation-calibration.json`. Interface: `parseEstimate`/`renderEstimate` (the PLAN.md `estimate: {tokens, tasks, confidence}` block), `parseActuals`/`renderActuals` (the SUMMARY.md `actuals: {tokens, tasks, commits}` block), `deriveConfidence(sampleCount) → low|med|high`, `classifyAgainstBudget(estimate, budget) → {overBudget, ratio, recommendation, budgetValid}`, `computeCalibration(samples) → {factor, sampleCount, applied, confidence, clamped}`, `applyCalibration`, `parseCalibrationDocument`/`renderCalibrationDocument`, `extractFrontmatterBlock` (leading-`---`-anchored scalar-block reader; hand-rolled because core ships no external deps), `calibrationBasis` (returns `estimate.raw_tokens` when present, else `tokens` — calibration must measure actual/raw or the loop un-corrects itself), and `measureTokens` (a re-export of `prompt-budget`'s `estimateTokens`). **Domain terms: _raw_ vs _calibrated_ tokens** — the same token count in two mutually incompatible states, carried by the compile-time brands `RawTokens` (the planner's uncorrected projection, and the only legal calibration denominator) and `CalibratedTokens` (the projection with the project's factor applied, and the only figure meaningful against the budget), constructed at trust boundaries via `asRawTokens` / `asCalibratedTokens` (#2671). The brands erase at compile time — the emitted `.cjs`, the CLI JSON, and both frontmatter schemas are unchanged — and exist because mixing the two states was NOT catchable at runtime: both are positive integers of the same magnitude, and the mix-up shipped twice past a green ~26,800-test suite (#2631 factor², #2632 self-defeating loop). `asRawTokens` refuses a `CalibratedTokens` by design; the single legitimate crossover (a pre-#2632 plan whose `tokens` IS the raw projection) lives behind one commented assertion in `calibrationBasis`. Compile fixtures: `tests/fixtures/brand-typing/`. **_smart zone_** — the usable prefix of a model's context window before output quality degrades, expressed as the configurable `workflow.smart_zone_tokens` budget (default 100000, a *policy default* rather than a benchmark constant since the effective ceiling is model/task-dependent); **_estimate/actuals_** — a projected phase cost recorded at plan time and the measured cost recorded at completion, both on the **same `estimateTokens` scale** so their ratio measures the miss rather than a difference between two measurement methods. Two invariants: (1) every signal is **exogenous** — the correction routes on a measured actual/estimate ratio and `confidence` routes on a calibration sample count, never on a model's self-assessment (this project measured self-rated confidence and found it weak — `gsd-core/references/honest-verifier.md:25-29`; see `.out-of-scope/general-purpose-agent-prompt-skills.md`); (2) the over-budget flag is **advisory** — a warning plus a split recommendation, never a block. Calibration is median-of-ratios, clamped to `[0.5, 3.0]`, and inert below 3 samples. CLI seam verbs: `estimate-check` (classify one figure; `--calibrated` when the input already has the factor applied — omitting it squares the correction), `estimate-calibration` (report the current factor), `estimate-calibrate` (#2632 — pair every completed phase's PLAN `estimate` with its SUMMARY `actuals`, rebuild `.planning/estimation-calibration.json` idempotently, and report the result; this is what closes the loop). Source of truth: `gsd-core/bin/lib/phase-estimation.cjs` and `src/estimate-cli.cts`. Test anchors: `tests/phase-estimation.test.cjs`, `tests/estimate-calibrate.test.cjs`.
|
||||
Module owning phase-effort estimation and its calibration against measured reality (ADR-2629, epic #1952). Pure — no I/O, no config reads; the CLI seam (`src/estimate-cli.cts`, verbs `estimate-check` / `estimate-calibration`) owns reading `.planning/config.json` and `.planning/estimation-calibration.json`. Interface: `parseEstimate`/`renderEstimate` (the PLAN.md `estimate: {tokens, tasks, confidence}` block), `parseActuals`/`renderActuals` (the SUMMARY.md `actuals: {tokens, tasks, commits}` block), `deriveConfidence(sampleCount) → low|med|high`, `classifyAgainstBudget(estimate, budget) → {overBudget, ratio, recommendation, budgetValid}`, `computeCalibration(samples) → {factor, sampleCount, applied, confidence, clamped}`, `applyCalibration`, `parseCalibrationDocument`/`renderCalibrationDocument`, `extractFrontmatterBlock` (leading-`---`-anchored scalar-block reader; stays hand-rolled for its TYPE CONTRACT — it returns numeric-looking values as numbers so `parseEstimate`/`parseActuals` see the types they validate, whereas the migrated `extractFrontmatter`, ADR-3473 §8.1/#3881, resolves every scalar as a string under js-yaml's FAILSAFE_SCHEMA; migrating this function onto the shared parser is follow-on work under ADR-3473 §8.1, not done), `calibrationBasis` (returns `estimate.raw_tokens` when present, else `tokens` — calibration must measure actual/raw or the loop un-corrects itself), and `measureTokens` (a re-export of `prompt-budget`'s `estimateTokens`). **Domain terms: _raw_ vs _calibrated_ tokens** — the same token count in two mutually incompatible states, carried by the compile-time brands `RawTokens` (the planner's uncorrected projection, and the only legal calibration denominator) and `CalibratedTokens` (the projection with the project's factor applied, and the only figure meaningful against the budget), constructed at trust boundaries via `asRawTokens` / `asCalibratedTokens` (#2671). The brands erase at compile time — the emitted `.cjs`, the CLI JSON, and both frontmatter schemas are unchanged — and exist because mixing the two states was NOT catchable at runtime: both are positive integers of the same magnitude, and the mix-up shipped twice past a green ~26,800-test suite (#2631 factor², #2632 self-defeating loop). `asRawTokens` refuses a `CalibratedTokens` by design; the single legitimate crossover (a pre-#2632 plan whose `tokens` IS the raw projection) lives behind one commented assertion in `calibrationBasis`. Compile fixtures: `tests/fixtures/brand-typing/`. **_smart zone_** — the usable prefix of a model's context window before output quality degrades, expressed as the configurable `workflow.smart_zone_tokens` budget (default 100000, a *policy default* rather than a benchmark constant since the effective ceiling is model/task-dependent); **_estimate/actuals_** — a projected phase cost recorded at plan time and the measured cost recorded at completion, both on the **same `estimateTokens` scale** so their ratio measures the miss rather than a difference between two measurement methods. Two invariants: (1) every signal is **exogenous** — the correction routes on a measured actual/estimate ratio and `confidence` routes on a calibration sample count, never on a model's self-assessment (this project measured self-rated confidence and found it weak — `gsd-core/references/honest-verifier.md:25-29`; see `.out-of-scope/general-purpose-agent-prompt-skills.md`); (2) the over-budget flag is **advisory** — a warning plus a split recommendation, never a block. Calibration is median-of-ratios, clamped to `[0.5, 3.0]`, and inert below 3 samples. CLI seam verbs: `estimate-check` (classify one figure; `--calibrated` when the input already has the factor applied — omitting it squares the correction), `estimate-calibration` (report the current factor), `estimate-calibrate` (#2632 — pair every completed phase's PLAN `estimate` with its SUMMARY `actuals`, rebuild `.planning/estimation-calibration.json` idempotently, and report the result; this is what closes the loop). Source of truth: `gsd-core/bin/lib/phase-estimation.cjs` and `src/estimate-cli.cts`. Test anchors: `tests/phase-estimation.test.cjs`, `tests/estimate-calibrate.test.cjs`.
|
||||
|
||||
### Verification Module
|
||||
Module owning the canonical phase-verification status projection shared by phase transition, progress, manager, autonomous, and closeout readiness paths. `readVerificationStatus(phaseDir, opts?)` reads the first `*-VERIFICATION.md` frontmatter `status`, maps it through `VERIFICATION_ROUTING_TABLE`, and fail-closes — only `{passed}` satisfies the canonical gate; `missing`/`unknown`/`gaps_found`/`human_needed`/`stale` all route away from "complete" (#1522). `findStaleVerificationSummary` flags a SUMMARY newer than the VERIFICATION file (status `stale`). Both honor a no-throw, degrade-to-safe contract (any FS error → `missing` / not-stale) and an injectable `opts.fs` seam. `isPhaseComplete(phaseDir, deps?)` is the single canonical owner of "is phase P complete?" (ADR-3180 §7.4, issue #3186, disk-strict per #2957): it wraps `readVerificationStatus`, calling it UNCONDITIONALLY — plan count is never a precondition, so a zero-plan phase with a passing `*-VERIFICATION.md` is complete (#3168) — and returns `{ value: { complete, verification }, scope }`; `complete` is exactly `verification.status === 'passed'`. A ROADMAP checkbox carries no machine authority and is never consulted. `cmdPhaseComplete`, `buildPhaseCompletionProjection`, and `buildStateFrontmatter` all route through it. Source of truth: `gsd-core/bin/lib/verification.cjs` (generated from `src/verification.cts`).
|
||||
@@ -120,6 +120,9 @@ Leaf module owning the construction of a regex from a **runtime value**, per ADR
|
||||
### Text Lines Module
|
||||
Leaf module owning `\r?\n` line-terminator splitting and CRLF normalization, per ADR-3212 §3 (epic #3212 Phase 2, #3413). Exposes `splitLines(content) → string[]` (splits on `\r\n` or `\n`; a lone `\r` is not a delimiter), `normalizeEol(content) → string` (strips every `\r`, matching the four `scripts/gen-*.cjs` `--check` copies it replaces), `detectEol(content) → '\n' | '\r\n'` (dominant terminator, `'\r\n'`-default on a tie or no terminator), and `joinLines(lines, eol?) → string` (inverse of `splitLines`; round-trips byte-for-byte with `detectEol`). Closes #3360: `parseMustHavesBlock` (`src/frontmatter.cts`) matched `^(\s*)must_haves:\s*$` and a sibling block-header regex against the WHOLE multi-line YAML string under `/m`, and `\r` is its own ECMA-262 LineTerminator — a greedy `\s*` anchored on `^` could cross a CRLF boundary and inflate the captured indent by one character, tripping the nesting guard and silently returning `[]` for every `must_haves` block on a CRLF plan file. The fix reroutes both lookups through split-then-match (`splitLines` first, then match per already-split line), which cannot straddle the delimiter that produced it. Pure and import-free — a leaf, so any consumer can depend on it without a cycle (mirrors the Pattern Module's position). Enforced going forward by the widened `eslint-rules/no-crlf-fragile-split.cjs` (now also scanned against `src/**/*.cts`, not only `tests/`). Source of truth: `gsd-core/bin/lib/text-lines.cjs` (generated from `src/text-lines.cts`). Design: `.gsd/phase/chore-3413-text-lines-seam/40-design.md`.
|
||||
|
||||
### Frontmatter Module
|
||||
Module owning YAML frontmatter parsing, serialization and CRUD commands. As of ADR-3473 §8.1 (#3881) the read path is no longer a hand-rolled line scanner — `parseYamlRegion`, `escapeDoubleQuoted`, `unescapeDoubleQuoted` and `parseQuotedScalar` are **deleted, not patched** (§8.1's words), and `extractFrontmatter` parses through the vendored js-yaml (`gsd-core/bin/lib/vendor/js-yaml.cjs`, type twin `src/vendor/js-yaml.d.cts`) under `FAILSAFE_SCHEMA` + `json: true`. `FAILSAFE_SCHEMA` resolves only `!!str`/`!!seq`/`!!map`, so every scalar still comes back a string (today's contract, unchanged for callers), and `json: true` makes a duplicate key overwrite rather than throw — the documented last-wins invariant `tests/fixtures/adversarial/frontmatter/duplicate-keys.md` pins. What js-yaml does not do is layered on top in this module: anchors, aliases and merge keys are refused outright (a raw-text pre-scan, `refuseAnchorsAndAliases`) because `FAILSAFE_SCHEMA` still resolves core YAML anchor/alias mechanics — not a tag-resolution concern a schema choice can disable — and `.planning/` documents are untrusted, user-authored input a hostile few-line alias fan-out could otherwise expand by orders of magnitude in milliseconds; the #3257 full-line-comment channel and the #1882 truncation probe are likewise preserved unchanged. A closed region that js-yaml itself cannot parse (malformed YAML, or a refused anchor/alias/merge key) returns `{}` carrying an exported `FRONTMATTER_UNPARSEABLE` Symbol rather than a bare, indistinguishable `{}` — Symbol-keyed so it is invisible to `Object.keys`/`JSON.stringify`/`for-in` and the ~70 call sites that never inspect it are unaffected, while the ~8 `hasFrontmatter = Object.keys(...).length > 0` call sites can consult it to tell "genuinely empty" apart from "could not parse" and avoid reassembling a document without its (unparsed but still present) frontmatter block. **All 8 sites are wired** — 7 in `src/state-transition.cts` (`beginPhaseCore`, `advancePlanCore`, complete-phase, planned-phase, milestone-complete, `patchCore`, `updateCore`) and 1 in `src/state.cts` — verified against a STATE.md carrying git merge-conflict markers, which previously lost its frontmatter block entirely on the next write and now round-trips intact. Scope note: the full CLI write path (`readModifyWriteStateMd` → `syncAndPreserveStateMd` → `syncStateFrontmatter`) re-derives and rebuilds the frontmatter block on every write regardless of what the transform returned, so the marker's observable effect is at the transform layer and for any caller bypassing that rebuild — it does not change on-disk output for today's `state update` / `state patch`. `extractFrontmatterBlock` (Phase Estimation Module) is a deliberate sibling, not a duplicate: it stays hand-rolled because it returns numeric-looking values as numbers rather than strings, a type contract `FAILSAFE_SCHEMA` cannot express. Source of truth: `gsd-core/bin/lib/frontmatter.cjs` (generated from `src/frontmatter.cts`).
|
||||
|
||||
### Token Scanner Module
|
||||
Leaf module generalizing the proven `hooks/lib/git-cmd.js` token-walk (#3129) into a shared primitive for stateful grammars, per ADR-3212 §4 (epic #3212 Phase 3, #3414). Exposes `tokenizeShellLike(cmd) → string[]` (quote-aware shell tokenizer — single/double-quoted spans as one token, no escape or brace/variable expansion, byte-identical port of `git-cmd.js`'s original `tokenize()`) and `indentWidth(line) → number` (leading-whitespace column count, tabs counted as one column each, no tab-width policy introduced). `hooks/lib/git-cmd.js` migrates its `tokenize()`/`isGitSubcommand()` onto `tokenizeShellLike` with zero behavior change (ADR §6 extend-never-mutate; parity-asserted against every existing fixture) and gains `extractBranchArgument(cmd) → string | null` (`git checkout -b <name>` / `git branch <name>`) — a new capability exercising the seam on the domain the ADR names, not a migration of existing duplicated logic (none existed). Closes #3169: `src/decisions.cts`'s decision-bullet parser could not distinguish a cross-reference bullet NESTED under an already-open decision from a fresh, malformed top-level declaration attempt — both have identical shape under any bullet-*content* classifier (an earlier design using bold-run-content classification was disproven against the repo's own existing FIX-B fixtures before being adopted, per the phase's design doc). `indentWidth` supplies the structural signal a per-line regex cannot see: a bulleted line indented deeper than the currently-open decision's own bullet is that decision's elaboration, folded into its text like a continuation line, never tested against the declaration/parse-miss regexes. A bullet at the same-or-shallower indent is unaffected. Pure and import-free — a leaf, so any consumer can depend on it without a cycle (mirrors the Pattern and Text Lines modules' position). Hook-staging note: `hooks/` scripts are staged as standalone files at install time, so `git-cmd.js` requires the BUILT `gsd-core/bin/lib/token-scanner.cjs` artifact (matching Phase 2's `scripts/gen-*.cjs` consolidation), not a sibling `hooks/lib/` file. Source of truth: `gsd-core/bin/lib/token-scanner.cjs` (generated from `src/token-scanner.cts`). Design: `.gsd/phase/chore-3414-tokenizer-first-seam/40-design.md`.
|
||||
|
||||
|
||||
@@ -527,6 +527,7 @@
|
||||
"user-artifact-staging.cjs",
|
||||
"validate-command-router.cjs",
|
||||
"validate.cjs",
|
||||
"vendor/js-yaml.cjs",
|
||||
"vendor/re2js.cjs",
|
||||
"verification-command-router.cjs",
|
||||
"verification.cjs",
|
||||
|
||||
@@ -673,6 +673,7 @@ Full listing: `gsd-core/bin/lib/*.cjs`.
|
||||
| `worktree-base-ref.cjs` | Worktree base-ref drift detection and degrade decision (`evaluateWorktreeBaseDegrade`) plus no-clobber `worktree.baseRef` settings management for the `base-check`/`set-baseref` subcommands (#683) |
|
||||
| `health-diagnostic-rules/worktree-health.cjs` | Health-diagnostic rules: worktree health checks (W020, W017, W027 — the split-off stale-worktree subject), ported behavior-preserving from `cmdValidateHealth` (ADR-3180 §8.2/§8.3/§8.5, Phase 11, #3309) |
|
||||
| `worktree-safety.cjs` | Worktree-root resolution and non-destructive prune policy decisions; owns W017 health-check logic |
|
||||
| `vendor/js-yaml.cjs` | **Vendored third-party artifact, not a GSD module.** Verbatim copy of `js-yaml`'s UMD `dist` build (ADR-3473 §8.1, #3881) — the single YAML parser adopted to replace this repo's hand-rolled frontmatter scanner. Vendored because `gsd-core/bin/**` is copied into installed trees that have no `node_modules`, so it may contain no external requires (enforced by `local/no-external-require-in-bin`). Its type twin, `src/vendor/js-yaml.d.cts`, is hand-authored (js-yaml ships no `.d.ts` upstream and `@types/js-yaml` is not installed) and deliberately narrow — only `load`/`dump`/`FAILSAFE_SCHEMA`/`YAMLException` are declared, so anchors/aliases/custom types/`loadAll` are unreachable from typed code. Never hand-edit the `.cjs`; `scripts/lint-vendored-deps.cjs` byte-compares it against the pinned `js-yaml` devDependency in `lint:ci` (the hand-authored twin is excluded from that byte-compare — there is no upstream file to compare against). See `gsd-core/bin/lib/vendor/README.md` |
|
||||
| `vendor/re2js.cjs` | **Vendored third-party artifact, not a GSD module.** Verbatim copy of `re2js`' CJS build — the RE2 linear-time regex engine used by `pattern.cjs` to evaluate untrusted `key_links` patterns without catastrophic backtracking (#3477). Vendored because `gsd-core/bin/**` is copied into installed trees that have no `node_modules`, so it may contain no external requires (enforced by `local/no-external-require-in-bin`). Never hand-edit; `scripts/lint-vendored-deps.cjs` byte-compares it against the pinned `re2js` devDependency in `lint:ci`. See `gsd-core/bin/lib/vendor/README.md` |
|
||||
| `write-set.cjs` | Shared fail-loud `Result<T>` (`{ok:true,value}\|{ok:false,reason}`) and per-surface write-set contracts (ADR-2143, epic #2143) — `WriteOutcome` (`{surface,applied}`), `WriteSet` (`WriteOutcome[]`), and `writeSetComplete(ws)` (true only when the set is non-empty AND every surface applied, never an OR-into-one-flag); `markdown-table.cjs` re-exports `Result` from here so existing importers are unaffected; consumed by `milestone.cts`'s `requirements mark-complete` handler to report a structured per-surface (`checkbox`/`traceability`) write-set alongside its existing fields (fixes the structural half of #2140) |
|
||||
|
||||
|
||||
@@ -64,6 +64,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
- [Take over a capability or EoS integration](how-to/take-over-a-capability-or-eos.md) — assume maintainership of an existing third-party capability, reviewer lane, or EoS host integration through a handoff, an adoption fork, first-party absorption, or a de-listing
|
||||
- [Add or update a host's integration](how-to/add-or-update-a-host-integration.md) — set a host's documentation-sourced `runtime.hostIntegration` axes (ADR-1239 Phase A), with the `undocumented` sentinel rule
|
||||
- [Migrate an install test to the executed plan](how-to/migrate-an-install-test-to-the-executed-plan.md) — convert an `fs.existsSync`-probing install test group to a value assertion against `installRuntimeArtifacts`'s executed-plan return, and test against a fake fs adapter
|
||||
- [Vendor a dependency](how-to/vendor-a-dependency.md) — add a third-party package `gsd-core/bin/**` needs at runtime as a verbatim vendored artifact, keep it out of `dependencies`, and pick the right upstream bundle
|
||||
- [Turn a capability off (and keep it off)](how-to/turn-a-capability-off.md) — disable a capability via the surface, or gate individual hooks off without removing the capability
|
||||
- [Drive GSD from a tracker issue](how-to/drive-gsd-from-a-tracker-issue.md) — start a phase from a GitHub, Linear, or Jira issue
|
||||
- [Migrate from GSD 2](how-to/migrate-from-gsd-2.md) — upgrade an existing GSD 2 project to GSD Core
|
||||
|
||||
@@ -135,11 +135,11 @@ Decisions 1–7 answer *how* this epic is organized. This section says *what the
|
||||
- Amending a rule here is an amendment to this ADR, not a code change with a comment.
|
||||
- Each rule carries a **status**: *Enforced* or *Required — Phase N*.
|
||||
|
||||
#### 8.1 One YAML parser — *Required — phase unassigned*
|
||||
#### 8.1 One YAML parser — *Required — Phase 4*
|
||||
|
||||
**Question.** What parses and serializes `.planning/` frontmatter?
|
||||
|
||||
**Owner.** A single vendored parser. `parseYamlRegion` and `escapeDoubleQuoted` are **deleted, not patched**.
|
||||
**Owner.** A single vendored parser. `parseYamlRegion` and `escapeDoubleQuoted` are **deleted, not patched**. (Post-#3881-review, finding 2: the hand-rolled implementations behind both names are gone — `src/frontmatter.cts` now renames them to `parseGuardedYamlRegion` and `escapeDoubleQuotedScalar` so no function still answers to the deleted scanner's name; see those functions' docblocks for the full reasoning, including why `escapeDoubleQuotedScalar`'s rename required updating its three call sites rather than being treated as an ADR-amendment matter.)
|
||||
|
||||
**Rule.** Escaping, quoting, CRLF handling and indentation leave this repo's maintenance surface. Round-trip *values* are identical; a property-based `fast-check` round-trip test is the gate.
|
||||
|
||||
@@ -162,6 +162,153 @@ Both close #3349 and #3360, which are **read-side** defects a real parser fixes
|
||||
|
||||
**Sequencing note, decided 2026-08-25.** This rule lands **after** Phases 1–3. §8.8's schema declares each key's real type, cardinality and enum — which is precisely the artifact that makes (b) tractable rather than epic-sized. Answering the fork before the schema exists means guessing the type contract; answering it after means reading it off the schema.
|
||||
|
||||
> **ANSWER, 2026-08-26 (Phase 4, #3881) — the fork is (a), a string-coercing adapter.** The forcing
|
||||
> function above is discharged here: the question is answered before the implementation PR opens.
|
||||
>
|
||||
> The sequencing note's bet did not pay. Measured against the merged schema rather than predicted:
|
||||
> `extractFrontmatter` has **78 non-test call sites across 23 files**, and only **33 of them (42%)**
|
||||
> read STATE.md. The other 45 read PLAN, VERIFICATION, SUMMARY, UAT, roadmap or generic agent/skill
|
||||
> frontmatter — document kinds §8.8's schema does not model. `FRONTMATTER_SCHEMAS` still declares
|
||||
> four kinds with **no type declaration for any of them**, and `STATE_FIELD_SCHEMA` has no
|
||||
> cross-reference to it. (b) would therefore still require net-new type contracts for four-plus
|
||||
> document kinds: the schema shrank the STATE.md slice of an otherwise unchanged epic-sized
|
||||
> migration.
|
||||
>
|
||||
> The prize is also smaller than the list above implies. Of the five compensating mechanisms named,
|
||||
> **two survive real types**: `frontmatterDeepEqual` (17 lines, 3 callers) is required for
|
||||
> no-op/dirty-key detection whatever the value types are, and the #3257 comment channel is orthogonal
|
||||
> to typing — a faithful parser discards comments, so that channel is needed *more* under (b), not
|
||||
> less. Only `sliceTopLevelFrontmatterSegments`, the `[object Object]` guard and
|
||||
> `noOpObjectListSetError` die: **~31 lines across 3 call sites.**
|
||||
>
|
||||
> (b) remains the larger prize and is **not** silently dropped — it is recorded here with the numbers
|
||||
> that say why it stays epic-sized, so a future reader inherits the measurement rather than the
|
||||
> intuition.
|
||||
>
|
||||
> Implementation note: fork (a) needs **no hand-written coercion layer** for scalars. js-yaml's
|
||||
> `FAILSAFE_SCHEMA` resolves only `!!str`/`!!seq`/`!!map`, so every scalar returns a string by spec.
|
||||
> `gap_closure: true` stays `"true"` and `FRONTMATTER_SCHEMAS['plan-gap-closure'].requiredValues`
|
||||
> keeps matching with no call site changed. Verified across `true`, `null`, `~`, `1.5`, `0x10`, a
|
||||
> date, `yes`, `on`, `.inf`, `NaN` and quoted-vs-unquoted numbers: all agree with legacy.
|
||||
|
||||
> **CORRECTION to the answer above, 2026-08-26 (Phase 4, #3881) — fork (a) as this ADR specifies it
|
||||
> is NOT IMPLEMENTABLE, and the fork itself is ill-posed.** An adversarial pass on the Phase 4 design
|
||||
> established this by execution, and it supersedes the "(a)" answer recorded above.
|
||||
>
|
||||
> (a) is defined as *"keep a string-coercing adapter over the parser so the existing contract holds."*
|
||||
> That presumes the existing contract is expressible as a function of a parsed YAML tree. **It is
|
||||
> not.** `extractFrontmatter` is not a YAML parser; it is a **line-oriented scanner whose output is a
|
||||
> function of the raw source text.** Four spellings of the same value:
|
||||
>
|
||||
> | source line | legacy | js-yaml |
|
||||
> |---|---|---|
|
||||
> | ` - test: "a b"` | `["test: \"a b"]` | `[{"test":"a b"}]` |
|
||||
> | ` - test: a b` | `["test: a b"]` | `[{"test":"a b"}]` |
|
||||
> | ` - test: 'a b'` | `["test: 'a b"]` | `[{"test":"a b"}]` |
|
||||
> | ` - {test: a b}` | `["{test: a b}"]` | `[{"test":"a b"}]` |
|
||||
>
|
||||
> One tree, four legacy strings — one of them mangled, with the closing quote stripped. **No adapter
|
||||
> over a tree can choose among four outputs that the tree does not distinguish.** Reproducing them
|
||||
> requires keeping the legacy line scanner, which is the surface §8.1 exists to delete.
|
||||
>
|
||||
> The consequence for the fork: **for any document with a non-scalar value, (a) collapses into (b).**
|
||||
> Structured values cannot be flattened back to their source spelling, so consumers must either accept
|
||||
> a canonicalized string or move to real types. There is no third option, and roughly 26% of
|
||||
> frontmatter-carrying documents (230 of 897 by the adversarial count; 239 of 901 by mine — the
|
||||
> denominators differ by fence-detection edge cases and are reconciled during implementation) hold at
|
||||
> least one non-scalar top-level value.
|
||||
>
|
||||
> **Three further defects in the design this correction replaces**, all confirmed by execution:
|
||||
>
|
||||
> 1. **Returning `{}` on a parse failure is destructive, not benign.** Eight call sites across
|
||||
> `state-transition.cjs` and `state.cjs` compute `hasFrontmatter =
|
||||
> Object.keys(extractFrontmatter(...)).length > 0` and, when false, reassemble the document
|
||||
> **without a frontmatter block**. A STATE.md carrying a git merge-conflict marker, a tab indent or
|
||||
> a duplicate key parses today and would, under a catch-and-return-`{}` adapter, have its
|
||||
> frontmatter **deleted on the next write**. The caller conflates "empty" with "unparseable"; the
|
||||
> adapter must not feed that conflation. (Not a live bug today: the only four tracked documents
|
||||
> legacy parses to empty are archived changesets, which never reach the state write path.)
|
||||
> 2. **An empty value silently drops its key.** Legacy parses `progress:` to `{}`; js-yaml yields
|
||||
> `null`; `reconstructFrontmatter` **omits any null-valued key**. `gsd-core/templates/state.md`
|
||||
> ships an empty `progress:`, so passing null through deletes it on the next write.
|
||||
> 3. **The truncation probe is not a pre-parse heuristic — it IS `parseYamlRegion`.** #1882's
|
||||
> diagnostic cannot both "stay unchanged" and survive that function's deletion. Pointing it at
|
||||
> js-yaml silences it on the dominant real shape (fence opened, body follows: legacy sees 2 keys
|
||||
> and fires; js-yaml raises `bad indentation` and yields 0 keys, so it stays silent). Keeping it
|
||||
> hand-rolled recreates precisely the parallel-surface divergence `frontmatter.cts`'s own comment
|
||||
> warns against.
|
||||
>
|
||||
> **A new attack surface the fork never considered.** `FAILSAFE_SCHEMA` still resolves anchors and
|
||||
> aliases. A 7-line frontmatter block expands to a **22.8 MB** structure in 0 ms, and one further
|
||||
> nesting level is ~200 MB — which `frontmatterDeepEqual` and `reconstructFrontmatter` then walk.
|
||||
> The legacy scanner is immune, because `&a [...]` is just a string to it. `.planning/` documents are
|
||||
> **user documents**, so this is a real regression vector that any implementation must close, not a
|
||||
> theoretical one. Current corpus occurrences of anchors, aliases and merge keys: **zero**, so nothing
|
||||
> is lost by refusing them outright.
|
||||
>
|
||||
> **Verified clean, and worth recording as negatives:** top-level key **order** agrees across all
|
||||
> frontmatter-carrying tracked documents (0 disagreements); the never-throw claim holds (legacy threw
|
||||
> on 0 of 11 hostile inputs, including a 200 KB scalar, 20k keys and 5k nested opens); and the ten
|
||||
> scalar spellings above all agree.
|
||||
>
|
||||
> **RESOLUTION, 2026-08-26 (maintainer decision).** Presented with three options — split §8.1 into
|
||||
> its own epic, take the full semantic migration now, or patch the scanner and drop the vendoring —
|
||||
> the maintainer chose **the full semantic migration**. Phase 4 therefore adopts js-yaml's semantics
|
||||
> as truth and carries all seven consequences above, rather than attempting the contract-preservation
|
||||
> that §0.1 proves impossible. The fork is not answered as (a) or as (b); it is answered as **"the
|
||||
> fork was ill-posed, and the migration is semantic."**
|
||||
>
|
||||
> **Guard ledger, counted rather than estimated — Phase 4 GROWS.** Excluding the 3,014 vendored
|
||||
> third-party lines, the hand-maintained surface is **+307 lines** net: `src/frontmatter.cts` alone is
|
||||
> +248/−180 = **+68**, growing *despite* deleting four functions, because the compatibility layer that
|
||||
> reproduces this repo's bespoke contract on top of js-yaml is larger than the scanner it replaced.
|
||||
>
|
||||
> So §8.1's stated benefit — *"escaping, quoting, CRLF handling and indentation leave this repo's
|
||||
> maintenance surface"* — **is not delivered as written.** Those concerns did leave; a compatibility
|
||||
> layer replaced them and the line count rose. What genuinely improved is the *kind* of code
|
||||
> maintained: this repo no longer owns YAML spec conformance, whose bugs were #1779, #1882, #1572,
|
||||
> #1660, #3257 and #3497. It owns a thin adapter over a parser whose correctness is upstream's
|
||||
> problem. That is a real gain, and a smaller one than the rule claimed.
|
||||
>
|
||||
> Decision 6 requires the growth be recorded rather than netted away — a net fall achieved by not
|
||||
> counting an increase is the Goodhart outcome Decision 5 exists to prevent. Across the epic: Phase 1
|
||||
> shrank (−665 lines, −1 file); Phase 2 was flat; Phase 3 grew (+2 guard surfaces); Phase 4 grows
|
||||
> (+307 lines). **Only one of four phases delivered the shrink this epic was framed around.**
|
||||
|
||||
> **Amendment, 2026-08-26 (Phase 4, #3881) — the justifying sentence above is wrong, and this is the
|
||||
> THIRD wrong premise in this ADR.** The claim *"Both close #3349 and #3360, which are read-side
|
||||
> defects a real parser fixes regardless of the value types it hands back"* describes defects that no
|
||||
> longer exist. Verified by **executing** the compiled parser at `ddde001af`, not by reading it:
|
||||
>
|
||||
> - **#3349** (escape never inverted on read → `b → 2b+1` growth per read-modify-write until OOM): four
|
||||
> successive round-trips of a value containing `"` and `\` return it **byte-identical every time**,
|
||||
> length stable. `unescapeDoubleQuoted` is a genuine inverse, shipped under **#3497**.
|
||||
> - **#3360** (`\s` at `^` under `/m` eating the `\n` of a CRLF pair → `[]` for every CRLF `must_haves`
|
||||
> block): LF and CRLF inputs both return `["alpha","beta"]`.
|
||||
>
|
||||
> Both issues are CLOSED. After §8.6's "keeps only its raw-write check" (no such check existed) and
|
||||
> §8.8's "delete `lint-state-field-drift.cjs`" (it guards an unrelated contract), the pattern is now
|
||||
> established firmly enough to be stated as a rule: **a factual claim in this ADR is a hypothesis
|
||||
> until the implementing phase executes it.** Decision 6 obliges a phase to verify a claim before
|
||||
> acting on it, not merely to count the result.
|
||||
>
|
||||
> **The Rule survives the collapse; only the justification died.** *"Escaping, quoting, CRLF handling
|
||||
> and indentation leave this repo's maintenance surface"* is untouched, and the evidence for it is
|
||||
> better than the two dead issues ever were: #1779, #1882, #1572, #1660, #3257 and #3497 are all this
|
||||
> repo paying, repeatedly, to maintain a YAML parser.
|
||||
>
|
||||
> **And the phase found live defects the dead ones did not cover.** A differential across all 901
|
||||
> frontmatter-bearing tracked documents shows **99.1% exact key-set agreement** and 2,177 of 2,178
|
||||
> scalars byte-identical — with **every disagreement being the legacy parser wrong**:
|
||||
> - **Block scalars are not parsed at all.** `commands/gsd/add-tests.md` declares
|
||||
> `argument-instructions: |`; the legacy parser returns the block indicator `"|"` as the value,
|
||||
> discards the instruction text, and invents a **phantom top-level key `Example`** from inside the
|
||||
> block body. A live defect in a shipped artifact.
|
||||
> - **A Unicode key is silently dropped.**
|
||||
>
|
||||
> §8.1 closes both by construction. That is the payoff this rule actually has, and it is recorded
|
||||
> from measurement rather than inherited from a sentence.
|
||||
|
||||
#### 8.2 Enumerations return correct values by construction — *Required — phase unassigned*
|
||||
|
||||
**Question.** What does an enumeration of phases, plans or artifacts return?
|
||||
@@ -319,9 +466,37 @@ Net across the set: one guard retired, one increase recorded honestly. The incre
|
||||
|---|---|
|
||||
| `scripts/lint-state-write-path-drift.cjs` | retained, shrunk (§8.6) — seam-bypass `writeStateMd(` arm and its ratchet retired at Phase 1; composition-bypass arm retained and made terminal; raw-write check added net-new. See §8.6's amendment. |
|
||||
| `scripts/lint-state-field-drift.cjs` | **RETAINED** — the Phase-3 retirement instruction rested on a wrong premise about what this guard does; see §8.8's amendment. It guards the ADR-3180 §7.7 / #3187 coercion ladder, which no schema makes unrepresentable. |
|
||||
| `scripts/lint-vendored-deps.cjs` | reused as-is for §8.1's vendoring rule |
|
||||
| `scripts/lint-vendored-deps.cjs` | **not reusable as-is** — generalized to a manifest by §8.1; see the correction below |
|
||||
| `local/no-external-require-in-bin` | reused as-is; enforces §8.1's packaging rule |
|
||||
| `local/no-adhoc-markdown-parsing` | widened past `src/**/*.cts` per Decision 5 (coverage fix, tracked on #3426/#3239) |
|
||||
| `local/no-adhoc-regex-escape` | widened to `MemberExpression`/`TSAsExpression` with a `.source`-aware exemption (§8.3) |
|
||||
| `scripts/lint-frontmatter-scalar-broad-grep.cjs` | expected casualty of §8.1; phase unassigned |
|
||||
| `scripts/lint-phase-enumeration-drift.cjs` | expected casualty of §8.2; phase unassigned |
|
||||
| `scripts/lint-frontmatter-scalar-broad-grep.cjs` | **NOT a casualty of §8.1 — retained.** See the correction below. |
|
||||
| `scripts/lint-phase-enumeration-drift.cjs` | expected casualty of §8.2 — **verify before retiring** (Phase 5) |
|
||||
|
||||
> **Correction, 2026-08-26 (Phase 4, #3881) — two rows in this roster were wrong, and they are the
|
||||
> FOURTH and FIFTH wrong premises in this ADR.** Both were caught by applying the rule recorded in
|
||||
> §8.1's amendment — *a factual claim in this ADR is a hypothesis until the implementing phase
|
||||
> executes it* — on its first use.
|
||||
>
|
||||
> **`lint-frontmatter-scalar-broad-grep.cjs` is not a casualty of §8.1 and is retained.** It has
|
||||
> nothing to do with the TypeScript parser. It is `DEFECT.FRONTMATTER-SCALAR-BROAD-GREP` (#586 /
|
||||
> PR #650): it scans fenced ```bash / ```sh blocks in `gsd-core/workflows/*.md`, `agents/*.md` and
|
||||
> `commands/**/*.md` for shell `grep "^key:"` invocations that read a frontmatter scalar from the
|
||||
> whole markdown body instead of scoping to the frontmatter block — the failure that once yielded
|
||||
> `passed+gaps_found+human_needed` instead of `passed` and blocked a passing phase. **The prompt
|
||||
> layer does not call our parser; it runs `grep` in a shell.** Vendoring js-yaml makes a shell grep
|
||||
> no safer, so retiring this guard would be a pure coverage loss dressed as a guard-count win —
|
||||
> the Goodhart outcome Decision 6 exists to prevent, and the third time in this epic that a
|
||||
> retirement claim has pointed at a guard whose actual contents it did not describe.
|
||||
>
|
||||
> **`lint-vendored-deps.cjs` cannot be "reused as-is."** All four of its checks name `re2js`
|
||||
> literally, as does its `REFRESH_COMMAND`. Vendoring a second package by pasting a second hardcoded
|
||||
> block would violate **§8.3, "one implementation per rule"**, inside the epic that exists to end
|
||||
> that. Phase 4 generalizes it to a table-driven manifest, preserving re2js's four checks unchanged.
|
||||
>
|
||||
> A further wrinkle the roster did not anticipate: js-yaml ships **no type declarations** and
|
||||
> `@types/js-yaml` is not installed, so the re2js precedent's verbatim `.d.cts` copy has no upstream
|
||||
> to copy from. `src/vendor/js-yaml.d.cts` is hand-authored, declaring only `load`, `dump`,
|
||||
> `FAILSAFE_SCHEMA` and `YAMLException` — which also makes anchors, aliases and custom types
|
||||
> unreachable from typed code, a capability gate rather than a shortcut. It is therefore excluded
|
||||
> from the byte-compare and pinned by a test instead.
|
||||
|
||||
86
docs/how-to/vendor-a-dependency.md
Normal file
86
docs/how-to/vendor-a-dependency.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# How to vendor a dependency
|
||||
|
||||
**Goal:** Add a third-party package that `gsd-core/bin/**` needs at runtime, in the vendored form the installer's copy step actually supports, without breaking the lint gate that keeps the vendored copy from silently drifting.
|
||||
|
||||
**Prerequisites:** The package is a devDependency already (`npm install --save-dev <pkg>`), and its build output ships (or can be built into) a self-contained CommonJS/UMD bundle with zero external `require()` calls.
|
||||
|
||||
---
|
||||
|
||||
## Why vendoring exists at all
|
||||
|
||||
`gsd-core/bin/**` is copied by the installer into trees that have **no `node_modules`** (for example `~/.claude/gsd-core/`). Any external, non-relative, non-builtin `require()`/`import` under `gsd-core/bin/**` breaks every command that touches it for every installed user, because the module simply cannot be resolved on disk there — there is no `node_modules` to resolve it from. `eslint-rules/no-external-require-in-bin.cjs` (`local/no-external-require-in-bin`) enforces this at lint time: it fails on any bare-specifier `require`/`import` under `gsd-core/bin/**`, whether or not the target actually exists in this repo's own `node_modules`. Vendoring — copying the package's compiled build artifact in-tree under `gsd-core/bin/lib/vendor/` and importing it with a relative path — is the only way around that constraint; there is no exemption mechanism, and there should not be one.
|
||||
|
||||
## The package MUST stay a devDependency
|
||||
|
||||
The package that gets vendored stays pinned in `package.json` `devDependencies`, never `dependencies`. Promoting it to `dependencies` does not make the vendored copy redundant — the installer never runs `npm install` on your behalf inside a target tree, so a runtime `dependencies` entry buys nothing there — and it actively breaks every already-installed tree's own `npm install`/`npm ci` step, which now expects a package that is not vendored anywhere the installed tree can see. #3496 is the concrete cost of getting this wrong: promoting a vendored package to `dependencies` produced 100 test failures across 8 install-surface suites. `devDependencies` is correct precisely because the vendored copy, not the npm-resolved package, is what ships at runtime; the devDependency exists only so this repo's own build/lint/test tooling has something to byte-compare the vendored copy against.
|
||||
|
||||
## Picking the right upstream artifact
|
||||
|
||||
Not every file the package ships is vendorable. You need a **self-contained CJS or UMD bundle** — one file, loadable with a single `require()`, containing zero `require()` calls of its own to anything outside Node builtins. Do not reach for the package's `exports.require`/`main` entry point (often `index.js`) without checking it first: that entry is frequently a thin loader that `require()`s several sibling files, which is exactly the shape vendoring cannot tolerate (a vendored `index.js` copied alone would throw at runtime looking for siblings that were never copied). Look instead for a `dist/` bundle purpose-built for standalone consumption.
|
||||
|
||||
For js-yaml (ADR-3473 §8.1, #3881) the correct artifact is `dist/js-yaml.js` — the UMD bundle, self-contained, loads under `require()` with zero external `require()` calls, and exposes the symbols this repo needs (`load`, `dump`, `FAILSAFE_SCHEMA`, `YAMLException`). The tempting-looking `index.js` (the `exports.require` entry point) is **not** self-contained and is the wrong choice. Verify your candidate the same way: `require()` it in isolation (outside this repo's `node_modules` resolution, e.g. from a scratch directory with only that one file present) and confirm it loads without reaching for a sibling file.
|
||||
|
||||
## Adding the `VENDORED` manifest row
|
||||
|
||||
`scripts/lint-vendored-deps.cjs` is table-driven over a `VENDORED` array (one row per vendored package) rather than hardcoded to a single package — this is deliberate (ADR-3473 §8.3, "one implementation per rule"): adding a second or third vendored package should never require a second hardcoded check block. Add a row:
|
||||
|
||||
```js
|
||||
{
|
||||
name: 'your-package', // matches package.json devDependencies key
|
||||
upstreamCjs: 'node_modules/your-package/dist/bundle.js', // the self-contained artifact you picked above
|
||||
vendoredCjs: 'gsd-core/bin/lib/vendor/your-package.cjs',
|
||||
upstreamDts: null, // or a path, if the package ships its own .d.ts/.d.cts
|
||||
vendoredDts: null, // or the gsd-core/bin/lib/vendor/ copy of that .d.ts
|
||||
srcTwin: 'src/vendor/your-package.d.cts',
|
||||
twinKind: 'hand-authored', // or 'upstream-verbatim' — see below
|
||||
},
|
||||
```
|
||||
|
||||
Then copy the artifact in:
|
||||
|
||||
```
|
||||
cp node_modules/your-package/dist/bundle.js gsd-core/bin/lib/vendor/your-package.cjs
|
||||
```
|
||||
|
||||
## The two kinds of type twin
|
||||
|
||||
Every vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can resolve types for the relative `./vendor/your-package.cjs` import from `src/**` — module resolution for a `.cts` source is relative to `src/`, not the compiled output directory, so `gsd-core/bin/lib/vendor/your-package.d.cts` alone is not enough. There are two kinds, distinguished by `twinKind`:
|
||||
|
||||
- **`upstream-verbatim`** — the package ships its own `.d.ts`/`.d.cts` upstream. Copy it verbatim to both `gsd-core/bin/lib/vendor/your-package.d.cts` and `src/vendor/your-package.d.cts`. `lint-vendored-deps.cjs` byte-compares both copies against the upstream file and against each other, so any manual edit is caught as drift.
|
||||
- **`hand-authored`** — the package ships no type declarations upstream (js-yaml's case: no bundled `.d.ts`, and `@types/js-yaml` is not installed). Write `src/vendor/your-package.d.cts` by hand, declaring only the symbols this repo actually imports — narrower is safer, since anything not declared is simply unreachable from typed code. This twin is **excluded** from the byte-compare (there is no upstream file to compare it against) and is instead pinned by a test asserting the declared surface matches what the module actually uses.
|
||||
|
||||
Set `upstreamDts`/`vendoredDts` to `null` for a hand-authored twin — `checkRow` in `scripts/lint-vendored-deps.cjs` skips the byte-compare checks entirely when either is `null`.
|
||||
|
||||
## Document it in `gsd-core/bin/lib/vendor/README.md`
|
||||
|
||||
Add an entry alongside the existing ones: which upstream artifact you copied, why it (and not the package's main entry point) is the vendorable one, which symbols it exposes, and the refresh command. This is the first place a future contributor looks when `lint-vendored-deps.cjs` reports drift.
|
||||
|
||||
## The `docs/INVENTORY.md` row
|
||||
|
||||
`gsd-core/bin/lib/vendor/your-package.cjs` is a shipped file under `gsd-core/bin/**`, so it needs a row in `docs/INVENTORY.md` per the inventory-drift rule for anything added under a manifest-scanned directory. Describe it as a vendored third-party artifact (not a GSD module), name the ADR/issue that introduced it, and cross-reference `gsd-core/bin/lib/vendor/README.md`.
|
||||
|
||||
## The ordering trap: build before you regenerate the manifest
|
||||
|
||||
`node scripts/gen-inventory-manifest.cjs --write` derives its manifest from the **compiled** `gsd-core/bin/**` tree, not from `src/**`. If you regenerate the inventory manifest before running `npm run build:lib`, the generator either misses your new vendored file (if `gsd-core/bin/lib/vendor/your-package.cjs` was not yet copied in) or captures a stale prior build's contents. The required order is:
|
||||
|
||||
1. `cp node_modules/your-package/dist/bundle.js gsd-core/bin/lib/vendor/your-package.cjs` (and the type twins, per above)
|
||||
2. `npm run build:lib`
|
||||
3. `node scripts/gen-inventory-manifest.cjs --write`
|
||||
|
||||
Running step 3 before step 1/2 produces a manifest that silently omits or misdescribes the new vendored file, and that drift is exactly what the manifest gate exists to catch on someone else's PR instead of yours.
|
||||
|
||||
## Verifying
|
||||
|
||||
- `node scripts/lint-vendored-deps.cjs` — exits 0 once the vendored copy, its type twins (if `upstream-verbatim`), and the `package.json` devDependency version pin all agree with `node_modules`.
|
||||
- `npx tsc --noEmit -p tsconfig.json` — confirms the `src/vendor/*.d.cts` twin actually resolves for every `.cts` importer.
|
||||
- `npm run lint` — confirms `local/no-external-require-in-bin` still finds zero external requires under `gsd-core/bin/**`.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `gsd-core/bin/lib/vendor/README.md` — the vendored-files README this how-to keeps in step with
|
||||
- `scripts/lint-vendored-deps.cjs` — the table-driven freshness gate (`VENDORED` array)
|
||||
- `eslint-rules/no-external-require-in-bin.cjs` — the rule that makes vendoring necessary in the first place
|
||||
- ADR-3473 §8.1 (#3881) — the js-yaml vendoring this how-to was extracted from
|
||||
- [docs index](../README.md)
|
||||
@@ -4195,7 +4195,7 @@ function runWithTimeout(argv) {
|
||||
// this string and HOST_COMMAND_ROUTERS/SKIP_ROOT_RESOLUTION are three
|
||||
// independently hand-maintained sites and nothing previously caught them
|
||||
// drifting apart when a query command was added to only one or two.
|
||||
const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
|
||||
const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--project-dir <path>] [--ws <name>] [--json-errors]\n' +
|
||||
'Commands: agent, agent-skills, assumption-delta, audit-open, audit-uat, check, check-commit, commit, commit-docs-guard, commit-to-subrepo, pr-subrepo, ' +
|
||||
'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, ' +
|
||||
'context-predicates, current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
|
||||
@@ -4210,6 +4210,7 @@ const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <fiel
|
||||
' --raw Emit raw output without post-processing\n' +
|
||||
' --pick <field> Extract a single field from JSON output (dot/bracket notation)\n' +
|
||||
' --cwd <path> Override working directory for project-root resolution\n' +
|
||||
' --project-dir <path> Explicit project root; skips the ancestor walk-up entirely (must already contain .planning/)\n' +
|
||||
' --ws <name> Override active workstream (or set GSD_WORKSTREAM)\n' +
|
||||
' --json-errors Emit structured JSON error objects on stderr (or set GSD_JSON_ERRORS=1)\n\n' +
|
||||
'For command-specific argument requirements, invoke the command without args ' +
|
||||
@@ -4356,6 +4357,39 @@ async function main() {
|
||||
error(`Invalid --cwd: ${cwd}`, ERROR_REASON.USAGE);
|
||||
}
|
||||
|
||||
// #3881: --project-dir <path> is a documented (docs/CONFIGURATION.md,
|
||||
// "Project-Root Resolution in Multi-Repo Workspaces") explicit override of
|
||||
// the project root. It is idempotent under findProjectRoot's ancestor
|
||||
// walk-up — i.e. it short-circuits the walk-up rather than seeding it —
|
||||
// so it MUST be validated and applied here, before findProjectRoot ever
|
||||
// runs, and its result must skip that call entirely below. A relative
|
||||
// value resolves against process.cwd(), matching --cwd's own resolution.
|
||||
let projectDirExplicit = false;
|
||||
const projectDirEqArg = args.find(arg => arg.startsWith('--project-dir='));
|
||||
const projectDirIdx = args.indexOf('--project-dir');
|
||||
let projectDirValue;
|
||||
if (projectDirEqArg) {
|
||||
projectDirValue = projectDirEqArg.slice('--project-dir='.length).trim();
|
||||
if (!projectDirValue) error('Missing value for --project-dir', ERROR_REASON.USAGE);
|
||||
args.splice(args.indexOf(projectDirEqArg), 1);
|
||||
} else if (projectDirIdx !== -1) {
|
||||
projectDirValue = args[projectDirIdx + 1];
|
||||
if (!projectDirValue || projectDirValue.startsWith('--')) error('Missing value for --project-dir', ERROR_REASON.USAGE);
|
||||
args.splice(projectDirIdx, 2);
|
||||
}
|
||||
if (projectDirValue !== undefined) {
|
||||
const resolvedProjectDir = path.resolve(projectDirValue);
|
||||
if (!fs.existsSync(resolvedProjectDir) || !fs.statSync(resolvedProjectDir).isDirectory()) {
|
||||
error(`Invalid --project-dir: ${resolvedProjectDir} (path does not exist or is not a directory)`, ERROR_REASON.USAGE);
|
||||
}
|
||||
const resolvedProjectDirPlanning = path.join(resolvedProjectDir, '.planning');
|
||||
if (!fs.existsSync(resolvedProjectDirPlanning) || !fs.statSync(resolvedProjectDirPlanning).isDirectory()) {
|
||||
error(`Invalid --project-dir: ${resolvedProjectDir} (no .planning/ directory found — --project-dir must name the project root itself, not an ancestor to walk up from)`, ERROR_REASON.USAGE);
|
||||
}
|
||||
cwd = resolvedProjectDir;
|
||||
projectDirExplicit = true;
|
||||
}
|
||||
|
||||
// Resolve worktree root: in a linked worktree, .planning/ lives in the main worktree.
|
||||
// However, in monorepo worktrees where the subdirectory itself owns .planning/,
|
||||
// skip worktree resolution — the CWD is already the correct project root.
|
||||
@@ -4468,7 +4502,10 @@ async function main() {
|
||||
}
|
||||
}
|
||||
|
||||
if (!SKIP_ROOT_RESOLUTION.has(command)) {
|
||||
// #3881: an explicit --project-dir already IS the resolved project root
|
||||
// (validated above) — findProjectRoot's ancestor walk-up must not run
|
||||
// over it, per docs/CONFIGURATION.md's documented idempotence.
|
||||
if (!projectDirExplicit && !SKIP_ROOT_RESOLUTION.has(command)) {
|
||||
cwd = findProjectRoot(cwd);
|
||||
}
|
||||
|
||||
|
||||
48
gsd-core/bin/lib/vendor/README.md
vendored
48
gsd-core/bin/lib/vendor/README.md
vendored
@@ -21,17 +21,55 @@ in-tree instead of depending on it being installed as an npm package.
|
||||
`gsd-core/bin/lib/pattern.cjs`) for linear-time RE2 pattern compilation.
|
||||
- `re2js.d.cts` — verbatim copy of `node_modules/re2js/build/index.d.cts`,
|
||||
so TypeScript resolves types for the relative import from `src/pattern.cts`.
|
||||
- `js-yaml.cjs` — verbatim copy of `node_modules/js-yaml/dist/js-yaml.js`
|
||||
(upstream package `js-yaml`, pinned version see `package.json`
|
||||
`devDependencies.js-yaml`). ADR-3473 §8.1 (#3881): the single YAML parser
|
||||
this repo standardizes on. The `dist` UMD bundle is the vendorable
|
||||
artifact — js-yaml's `exports.require` entry (`index.js`) is *not*
|
||||
self-contained; `dist/js-yaml.js` loads under `require()`, contains zero
|
||||
`require()` calls of its own, and exposes `load`/`dump`/`FAILSAFE_SCHEMA`/
|
||||
`YAMLException`.
|
||||
|
||||
## Two kinds of type twin
|
||||
|
||||
Each vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can
|
||||
resolve types for a relative `./vendor/<pkg>.cjs` import from `src/**`
|
||||
(module resolution for a `.cts` source is relative to `src/`, not the
|
||||
compiled output dir). There are two kinds:
|
||||
|
||||
- **upstream-verbatim** (`re2js.d.cts`) — a byte-for-byte copy of an
|
||||
upstream `.d.cts`/`.d.ts` that ships with the package. Both the
|
||||
`gsd-core/bin/lib/vendor/` copy and the `src/vendor/` copy are checked by
|
||||
`scripts/lint-vendored-deps.cjs` against `node_modules` and against each
|
||||
other.
|
||||
- **hand-authored** (`js-yaml.d.cts`) — js-yaml ships **no** type
|
||||
declarations upstream and `@types/js-yaml` is not installed, so there is
|
||||
nothing to copy verbatim. `src/vendor/js-yaml.d.cts` is written by hand,
|
||||
declares only the symbols actually used (`load`, `dump`,
|
||||
`FAILSAFE_SCHEMA`, `YAMLException`), and is **excluded** from
|
||||
`lint-vendored-deps.cjs`'s byte-compare — there is no upstream file to
|
||||
compare it against. The narrowness is deliberate: anchors, aliases,
|
||||
custom types and `loadAll` are unreachable from typed code, which is a
|
||||
compile-time enforcement of ADR-3473 §8.1's refusal to expand them.
|
||||
|
||||
## Do not hand-edit
|
||||
|
||||
These files are **verbatim** copies of the upstream build output. Never
|
||||
edit them directly — refresh them from `node_modules` instead:
|
||||
These files are **verbatim** copies of upstream build output. Never edit
|
||||
them directly — refresh them from `node_modules` instead:
|
||||
|
||||
```
|
||||
cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs
|
||||
cp node_modules/re2js/build/index.d.cts gsd-core/bin/lib/vendor/re2js.d.cts
|
||||
cp node_modules/re2js/build/index.d.cts src/vendor/re2js.d.cts
|
||||
|
||||
cp node_modules/js-yaml/dist/js-yaml.js gsd-core/bin/lib/vendor/js-yaml.cjs
|
||||
# js-yaml.d.cts has no upstream counterpart — update src/vendor/js-yaml.d.cts
|
||||
# by hand if the js-yaml API surface this repo depends on changes.
|
||||
```
|
||||
|
||||
`node scripts/lint-vendored-deps.cjs` fails CI if the vendored copy drifts
|
||||
byte-for-byte from `node_modules/re2js/build/` or from the `re2js` version
|
||||
pinned in `package.json` `devDependencies`.
|
||||
`node scripts/lint-vendored-deps.cjs` fails CI if any vendored copy drifts
|
||||
byte-for-byte from its `node_modules` upstream, from its own source-side
|
||||
type twin (upstream-verbatim twins only), or from the version pinned in
|
||||
`package.json` `devDependencies`. It is table-driven (`VENDORED` in that
|
||||
script) — adding a third vendored package means adding a row, not a second
|
||||
hardcoded check block (ADR-3473 §8.3, "one implementation per rule").
|
||||
|
||||
3014
gsd-core/bin/lib/vendor/js-yaml.cjs
vendored
Normal file
3014
gsd-core/bin/lib/vendor/js-yaml.cjs
vendored
Normal file
File diff suppressed because it is too large
Load Diff
@@ -1,11 +1,11 @@
|
||||
---
|
||||
phase: {N}
|
||||
slug: {phase-slug}
|
||||
phase: "{N}"
|
||||
slug: "{phase-slug}"
|
||||
status: draft
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: {date}
|
||||
created: "{date}"
|
||||
---
|
||||
|
||||
# Phase {N} — Security
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
phase: {N}
|
||||
slug: {phase-slug}
|
||||
phase: "{N}"
|
||||
slug: "{phase-slug}"
|
||||
status: draft
|
||||
shadcn_initialized: false
|
||||
preset: none
|
||||
created: {date}
|
||||
created: "{date}"
|
||||
---
|
||||
|
||||
# Phase {N} — UI Design Contract
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
phase: {N}
|
||||
slug: {phase-slug}
|
||||
phase: "{N}"
|
||||
slug: "{phase-slug}"
|
||||
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
|
||||
# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
|
||||
status: draft
|
||||
nyquist_compliant: false
|
||||
wave_0_complete: false
|
||||
created: {date}
|
||||
created: "{date}"
|
||||
---
|
||||
|
||||
# Phase {N} — Validation Strategy
|
||||
|
||||
4
package-lock.json
generated
4
package-lock.json
generated
@@ -10,7 +10,6 @@
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@anthropic-ai/claude-agent-sdk": "^0.2.84",
|
||||
"re2js": "^2.8.6",
|
||||
"ws": "^8.21.0"
|
||||
},
|
||||
"bin": {
|
||||
@@ -31,6 +30,8 @@
|
||||
"fast-check": "^4.8.0",
|
||||
"globals": "^16.5.0",
|
||||
"js-yaml": "^4.3.1",
|
||||
"mutation-testing-metrics": "^3.7.3",
|
||||
"re2js": "^2.8.6",
|
||||
"typescript": "^6.0.3",
|
||||
"typescript-eslint": "^8.60.0"
|
||||
},
|
||||
@@ -4536,6 +4537,7 @@
|
||||
"version": "2.8.6",
|
||||
"resolved": "https://registry.npmjs.org/re2js/-/re2js-2.8.6.tgz",
|
||||
"integrity": "sha512-xLgQil4kIUCrAzVk9fRSkxkFNwmygLFjVxXrLc65aE1F0+Zsb8rxumFBy4XKyvgMCTL6kilDq3EZ0piE2dP/Dg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
|
||||
@@ -75,6 +75,7 @@
|
||||
"fast-check": "^4.8.0",
|
||||
"globals": "^16.5.0",
|
||||
"js-yaml": "^4.3.1",
|
||||
"mutation-testing-metrics": "^3.7.3",
|
||||
"re2js": "^2.8.6",
|
||||
"typescript": "^6.0.3",
|
||||
"typescript-eslint": "^8.60.0"
|
||||
@@ -119,7 +120,7 @@
|
||||
"lint:table-schema-drift": "node scripts/lint-table-schema-drift.cjs",
|
||||
"lint:frontmatter-scalar-broad-grep": "node scripts/lint-frontmatter-scalar-broad-grep.cjs",
|
||||
"lint:removed-but-needed": "node scripts/lint-removed-but-needed.cjs",
|
||||
"lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-emitted-drift-ack.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs",
|
||||
"lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-emitted-drift-ack.cjs && node scripts/lint-portable-timeout.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs",
|
||||
"lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
|
||||
"lint:regression-names": "node scripts/lint-regression-test-names.cjs",
|
||||
"lint:descriptions": "node scripts/lint-descriptions.cjs",
|
||||
|
||||
156
scripts/check-mutation-score-ratchet.cjs
Normal file
156
scripts/check-mutation-score-ratchet.cjs
Normal file
@@ -0,0 +1,156 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* scripts/check-mutation-score-ratchet.cjs
|
||||
*
|
||||
* #3881 follow-up ("one YAML parser" mutation-matrix piece 3): makes each
|
||||
* module's `minScore` floor (scripts/mutation-matrix.cjs COVERED) ratchet
|
||||
* UPWARD instead of sitting wherever it was last hand-set.
|
||||
*
|
||||
* Two halves of "never lowerable without a reasoned marker":
|
||||
* 1. `tests/mutation-matrix-ratchet.test.cjs`'s RATCHET_BASELINE already
|
||||
* enforces the DOWN side: any change to a module's minScore — up or
|
||||
* down — must land in the same diff as a matching RATCHET_BASELINE
|
||||
* edit, making the change visible in code review (mirrors this repo's
|
||||
* other shrink-only baselines, e.g. scripts/lint-unreachable-guard-drift.cjs's
|
||||
* $comment convention: a number cannot move silently).
|
||||
* 2. THIS script enforces the UP side: after a real CI Stryker run, if the
|
||||
* module's ACHIEVED mutation score exceeds its declared floor by more
|
||||
* than RATCHET_SLACK points, that is not "run-to-run variance" (this
|
||||
* file's own header documents variance as 1-2 points; see
|
||||
* scripts/mutation-matrix.cjs's "Floors are measured scores minus 1-2
|
||||
* pts") — it is unclaimed headroom, and the floor should have been
|
||||
* raised. Exits 1 telling the author exactly what to raise it to, so a
|
||||
* module that improves cannot silently keep a stale, low bar forever.
|
||||
*
|
||||
* Consumes Stryker's `json` reporter output (mutation-testing-report-schema
|
||||
* document; stryker.config.mjs's `reporters` includes `'json'`, default path
|
||||
* `reports/mutation/mutation.json`) via `mutation-testing-metrics` — the same
|
||||
* package Stryker itself uses internally to compute a report's score — rather
|
||||
* than re-deriving killed/survived counts by hand.
|
||||
*
|
||||
* Wired into `.github/workflows/mutation.yml`'s `mutate` job as a step AFTER
|
||||
* `npx stryker run`, gated on the shard having passed (a shard that failed
|
||||
* MUTATION_BREAK is a floor problem, not a ratchet problem — Stryker's own
|
||||
* exit code already reports that).
|
||||
*
|
||||
* CLI:
|
||||
* node scripts/check-mutation-score-ratchet.cjs --module <name> [--report <path>] [--matrix <path>]
|
||||
* `--report` defaults to reports/mutation/mutation.json (Stryker's own default).
|
||||
* `--matrix` defaults to this repo's own scripts/mutation-matrix.cjs; it is an injectable seam
|
||||
* so tests can point the CLI at a synthetic COVERED fixture instead of the real, live-ratcheting
|
||||
* config (see tests/mutation-score-ratchet.test.cjs — a test asserting this script's fail/pass
|
||||
* behaviour must never hardcode a real module's numeric floor, because that floor is exactly
|
||||
* what this mechanism exists to move).
|
||||
*/
|
||||
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
// Slack, in mutation-score points, above a module's declared minScore floor before this
|
||||
// ratchet demands the floor be raised. Deliberately larger than the 1-2 point run-to-run
|
||||
// TIMEOUT variance margin scripts/mutation-matrix.cjs's floors are already set with (its own
|
||||
// header: "Floors are measured scores minus 1-2 pts for run-to-run variance") — that smaller
|
||||
// margin is calibrated for the noise BETWEEN two runs of the SAME test list against the SAME
|
||||
// source. RATCHET_SLACK instead has to tolerate the noise this file's own history already
|
||||
// shows for the frontmatter module across genuine measurement events (63.35 -> 66.67 ->
|
||||
// 60.58 -> pending, each a real CI measurement, not pure jitter, spanning >3 points on its
|
||||
// own). 5 points sits comfortably above that observed band without being so wide that a
|
||||
// module sitting well above TARGET_MUTATION_SCORE (80) could coast for years without its
|
||||
// floor ever being asked to move.
|
||||
const RATCHET_SLACK = 5;
|
||||
|
||||
/**
|
||||
* Pure: does `achievedScore` (0-100) exceed `floor` (minScore) by more than `slack`?
|
||||
* Returns `{ shouldRatchet, suggestedFloor }` — `suggestedFloor` follows the SAME formula
|
||||
* scripts/mutation-matrix.cjs's own header documents for setting a floor from a measured
|
||||
* score: `floor(measured) - 1`.
|
||||
*/
|
||||
function evaluateRatchet(achievedScore, floor, slack = RATCHET_SLACK) {
|
||||
const shouldRatchet = achievedScore - floor > slack;
|
||||
return {
|
||||
shouldRatchet,
|
||||
suggestedFloor: shouldRatchet ? Math.floor(achievedScore) - 1 : floor,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract the achieved mutation score from a Stryker `json` reporter document via
|
||||
* `mutation-testing-metrics` (the same library Stryker itself uses to compute scores).
|
||||
* Throws a descriptive error if the document has no scoreable mutants at all (an empty
|
||||
* `files` map, or every file having zero mutants) — that is a wiring bug in the caller
|
||||
* (wrong report path, or the shard mutated nothing), never a score of 0.
|
||||
*/
|
||||
function extractAchievedScore(report) {
|
||||
// Lazy require: this dependency is only needed on the actual score-extraction path, not
|
||||
// when this module is required purely for evaluateRatchet (used by unit tests without the
|
||||
// mutation-testing-metrics package's schema-validation overhead).
|
||||
const { calculateMutationTestMetrics } = require('mutation-testing-metrics');
|
||||
const metrics = calculateMutationTestMetrics(report);
|
||||
const score = metrics && metrics.systemUnderTestMetrics && metrics.systemUnderTestMetrics.metrics
|
||||
? metrics.systemUnderTestMetrics.metrics.mutationScore
|
||||
: undefined;
|
||||
if (typeof score !== 'number' || Number.isNaN(score)) {
|
||||
throw new Error('mutation report produced no scoreable mutants — check --report points at the right shard\'s reports/mutation/mutation.json');
|
||||
}
|
||||
return score;
|
||||
}
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { module: null, report: 'reports/mutation/mutation.json', matrix: null };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const arg = argv[i];
|
||||
if (arg === '--module') {
|
||||
out.module = argv[++i];
|
||||
} else if (arg === '--report') {
|
||||
out.report = argv[++i];
|
||||
} else if (arg === '--matrix') {
|
||||
out.matrix = argv[++i];
|
||||
} else {
|
||||
throw new Error(`unknown argument: ${arg}`);
|
||||
}
|
||||
}
|
||||
if (!out.module) throw new Error('--module <name> is required');
|
||||
return out;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = parseArgs(process.argv.slice(2));
|
||||
const matrixPath = args.matrix ? path.resolve(args.matrix) : path.join(__dirname, 'mutation-matrix.cjs');
|
||||
const { COVERED } = require(matrixPath);
|
||||
const entry = COVERED[args.module];
|
||||
if (!entry) {
|
||||
throw new ExitError(1, `check-mutation-score-ratchet: unknown module '${args.module}' — not in ${args.matrix ? matrixPath : 'scripts/mutation-matrix.cjs'} COVERED`);
|
||||
}
|
||||
|
||||
const reportPath = path.resolve(args.report);
|
||||
if (!fs.existsSync(reportPath)) {
|
||||
throw new ExitError(1, `check-mutation-score-ratchet: report not found at ${reportPath} — run \`npx stryker run\` first (with the 'json' reporter enabled)`);
|
||||
}
|
||||
let report;
|
||||
try {
|
||||
report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
|
||||
} catch (err) {
|
||||
throw new ExitError(1, `check-mutation-score-ratchet: ${reportPath} is not valid JSON: ${err.message}`);
|
||||
}
|
||||
|
||||
const achieved = extractAchievedScore(report);
|
||||
const { shouldRatchet, suggestedFloor } = evaluateRatchet(achieved, entry.minScore);
|
||||
|
||||
if (!shouldRatchet) {
|
||||
console.log(`ok mutation-score-ratchet: ${args.module} achieved ${achieved.toFixed(2)}% against floor ${entry.minScore} (within ${RATCHET_SLACK}-point slack)`);
|
||||
return;
|
||||
}
|
||||
|
||||
console.error(`mutation-score-ratchet: ${args.module} achieved ${achieved.toFixed(2)}%, more than ${RATCHET_SLACK} points above its declared floor (${entry.minScore}).`);
|
||||
console.error(` This is unclaimed headroom, not run-to-run variance — raise the floor.`);
|
||||
console.error(` remedy: in scripts/mutation-matrix.cjs, set COVERED['${args.module}'].minScore = ${suggestedFloor} (floor(achieved) - 1, this file's own convention),`);
|
||||
console.error(` and update the matching entry in tests/mutation-matrix-ratchet.test.cjs's RATCHET_BASELINE in the same diff.`);
|
||||
throw new ExitError(1);
|
||||
}
|
||||
|
||||
module.exports = { RATCHET_SLACK, evaluateRatchet, extractAchievedScore };
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
@@ -7,6 +7,10 @@
|
||||
"path": "src/vendor/re2js.d.cts",
|
||||
"reason": "Vendored third-party type declaration (#3477): a .d.cts carries no executable code, so no ESLint rule is meaningful; the vendored .cjs it describes is globally ignored as verbatim upstream output. Freshness is enforced by scripts/lint-vendored-deps.cjs, not by lint rules."
|
||||
},
|
||||
{
|
||||
"path": "src/vendor/js-yaml.d.cts",
|
||||
"reason": "Vendored third-party type declaration (ADR-3473 §8.1, #3881): a .d.cts carries no executable code, so no ESLint rule is meaningful; the vendored js-yaml .cjs it describes is globally ignored as verbatim upstream output (gsd-core/bin/lib/vendor/**). Freshness is enforced by scripts/lint-vendored-deps.cjs, not by lint rules — same precedent as src/vendor/re2js.d.cts above."
|
||||
},
|
||||
{
|
||||
"path": "tests/fixtures/brand-typing/bad-calibrated-as-sample-basis.cts",
|
||||
"reason": "Deliberate MUST-NOT-COMPILE type-error fixture (#3059): type-aware linting would fail by design; it exists to prove the compiler rejects it."
|
||||
|
||||
86
scripts/lint-mutation-test-derivation-drift.cjs
Normal file
86
scripts/lint-mutation-test-derivation-drift.cjs
Normal file
@@ -0,0 +1,86 @@
|
||||
#!/usr/bin/env node
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* scripts/lint-mutation-test-derivation-drift.cjs
|
||||
*
|
||||
* #3881 follow-up ("one YAML parser" mutation-matrix piece 2): guards the
|
||||
* derivation engine in scripts/mutation-matrix.cjs against the exact drift
|
||||
* class PR #3888 shipped — a test file added on a branch that directly
|
||||
* `require()`s a covered module's built artifact AND names itself after that
|
||||
* module (`<module>.test.cjs` / `<module>.property.test.cjs` /
|
||||
* `<module>-anything.test.cjs`), yet is never wired into that module's
|
||||
* mutation shard.
|
||||
*
|
||||
* `scripts/mutation-matrix.cjs`'s `computeModuleTests` already derives most of
|
||||
* a module's `tests` array automatically from exactly that (require + naming)
|
||||
* signal, so a NEWLY drifting file of that shape is normally impossible — it
|
||||
* would be auto-included the moment it exists. What this guard catches is the
|
||||
* one case the derivation cannot self-correct: a file matching BOTH signals
|
||||
* that the module's own `excludeTests` withholds. `excludeTests` entries are
|
||||
* a deliberate, reasoned decision (see mutation-matrix.cjs's per-module
|
||||
* comments) — this guard does not second-guess that decision, but it DOES
|
||||
* verify every such file is EITHER accounted for in `tests` (auto-derived or
|
||||
* `extraTests`) OR named in `excludeTests`. A file satisfying both signals
|
||||
* that is in NEITHER list is exactly the drift #3888 shipped: nobody made a
|
||||
* decision about it at all.
|
||||
*
|
||||
* Pure core (`findDrift`) so tests can drive it against a synthetic COVERED +
|
||||
* requiring-files map without touching the real tests/ tree; `main()` wires
|
||||
* it to the real repo for `npm run lint:ci`.
|
||||
*/
|
||||
|
||||
const path = require('node:path');
|
||||
const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
/**
|
||||
* Pure: for every module in `covered`, every file in `requiringFiles[module]`
|
||||
* that ALSO matches the module's naming rule must be present in either
|
||||
* `covered[module].tests` (already `tests/`-prefixed, as computeModuleTests
|
||||
* emits it) or `covered[module].excludeTests` (bare basenames). Anything
|
||||
* matching both signals but present in neither is reported as drift.
|
||||
*
|
||||
* @param {object} covered - mutation-matrix.cjs's COVERED (post `computeModuleTests`)
|
||||
* @param {(moduleName: string) => string[]} findRequiringTestFiles - basenames requiring the module's artifact
|
||||
* @param {(moduleName: string, file: string) => boolean} matchesModuleNamingRule
|
||||
* @returns {{module: string, file: string}[]}
|
||||
*/
|
||||
function findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule) {
|
||||
const drift = [];
|
||||
for (const [moduleName, entry] of Object.entries(covered)) {
|
||||
const testsSet = new Set((entry.tests || []).map((t) => path.basename(t)));
|
||||
const excludeSet = new Set(entry.excludeTests || []);
|
||||
for (const file of findRequiringTestFiles(moduleName)) {
|
||||
if (!matchesModuleNamingRule(moduleName, file)) continue;
|
||||
if (testsSet.has(file) || excludeSet.has(file)) continue;
|
||||
drift.push({ module: moduleName, file });
|
||||
}
|
||||
}
|
||||
return drift;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const {
|
||||
COVERED,
|
||||
findRequiringTestFiles,
|
||||
matchesModuleNamingRule,
|
||||
} = require('./mutation-matrix.cjs');
|
||||
|
||||
const drift = findDrift(COVERED, findRequiringTestFiles, matchesModuleNamingRule);
|
||||
|
||||
if (drift.length === 0) {
|
||||
console.log(`ok mutation-test-derivation-drift: every module-named test file requiring a covered module has an explicit disposition (${Object.keys(COVERED).length} modules checked)`);
|
||||
return;
|
||||
}
|
||||
|
||||
console.error('mutation-test-derivation-drift: test file(s) require a covered module and match its naming rule, but have no disposition in scripts/mutation-matrix.cjs (neither auto-derived/extraTests nor excludeTests):');
|
||||
for (const d of drift) {
|
||||
console.error(` [${d.module}] tests/${d.file}`);
|
||||
}
|
||||
console.error('\n remedy: in scripts/mutation-matrix.cjs, either let it auto-derive (do nothing further if it already appears in COVERED[<module>].tests), or add it to extraTests, or add a REASONED excludeTests entry explaining why it is deliberately withheld from the mutation shard.');
|
||||
throw new ExitError(1);
|
||||
}
|
||||
|
||||
module.exports = { findDrift };
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
@@ -32,12 +32,14 @@
|
||||
"frontmatter": {
|
||||
"files": [
|
||||
"frontmatter-cli.test.cjs",
|
||||
"frontmatter-golden-parity.test.cjs",
|
||||
"frontmatter-roundtrip.property.test.cjs",
|
||||
"frontmatter.property.test.cjs",
|
||||
"frontmatter.test.cjs",
|
||||
"frontmatter.unit.test.cjs"
|
||||
],
|
||||
"issue": "3227",
|
||||
"justification": "Grandfathered by #3227 when the testEffectivePrefix() dot/hyphen bucketing fix first made this pre-existing over-cap cluster visible to the gate; not new test sprawl."
|
||||
"issue": "3881",
|
||||
"justification": "Grandfathered by #3227 for the original 4-file cluster (pre-existing over-cap, not new sprawl). #3881 (ADR-3473 §8.1, the js-yaml parser migration) adds two more: frontmatter-golden-parity.test.cjs (D-series golden-corpus diff against the legacy parser, ~900 real documents — cannot be folded into an existing file without losing its independent-of-current-parser provenance) and frontmatter-roundtrip.property.test.cjs (fast-check property coverage the migration's bijective-contract rule requires). Both are migration-specific, not incidental sprawl."
|
||||
},
|
||||
"graphify": {
|
||||
"files": [
|
||||
|
||||
@@ -7,26 +7,49 @@
|
||||
* #3477 follow-up: gsd-core/bin/** is copied by the installer into trees
|
||||
* that have NO node_modules, so it must carry zero external requires
|
||||
* (local/no-external-require-in-bin, eslint-rules/no-external-require-in-bin.cjs).
|
||||
* `re2js` (src/pattern.cts's RE2 engine) is vendored verbatim under
|
||||
* gsd-core/bin/lib/vendor/ instead — see gsd-core/bin/lib/vendor/README.md.
|
||||
* Third-party packages that gsd-core/bin/** needs at runtime are instead
|
||||
* vendored verbatim under gsd-core/bin/lib/vendor/ — see
|
||||
* gsd-core/bin/lib/vendor/README.md.
|
||||
*
|
||||
* A vendored artifact that silently drifts from its upstream package is
|
||||
* just as dangerous as never vendoring it in the first place (a stale
|
||||
* copy ships a different engine than the one actually reviewed/audited).
|
||||
* This guard fails CI when:
|
||||
* 1. gsd-core/bin/lib/vendor/re2js.cjs no longer matches
|
||||
* node_modules/re2js/build/index.cjs byte-for-byte.
|
||||
* 2. gsd-core/bin/lib/vendor/re2js.d.cts no longer matches
|
||||
* node_modules/re2js/build/index.d.cts byte-for-byte.
|
||||
* 3. src/vendor/re2js.d.cts (the source-side twin tsc needs to resolve
|
||||
* types for src/pattern.cts's relative './vendor/re2js.cjs' import —
|
||||
* module resolution for a .cts source is relative to src/, not the
|
||||
* output dir) no longer matches gsd-core/bin/lib/vendor/re2js.d.cts.
|
||||
* 4. The `re2js` version pinned in package.json `devDependencies` no
|
||||
* #3881: this used to be a single hand-rolled check hardcoded to `re2js`.
|
||||
* It is now table-driven (VENDORED below), so adding a second vendored
|
||||
* package (js-yaml, #3881) does not require a second hardcoded block —
|
||||
* that would violate ADR-3473 §8.3, "one implementation per rule."
|
||||
*
|
||||
* For each row in VENDORED, this guard fails CI when:
|
||||
* 1. The vendored `.cjs` no longer matches its upstream `node_modules`
|
||||
* build output byte-for-byte.
|
||||
* 2. (upstream-verbatim twins only) The vendored `.d.cts` under
|
||||
* gsd-core/bin/lib/vendor/ no longer matches its upstream
|
||||
* `node_modules` `.d.cts` byte-for-byte.
|
||||
* 3. (upstream-verbatim twins only) The source-side twin under
|
||||
* src/vendor/ (which tsc needs to resolve types for a relative
|
||||
* `./vendor/<pkg>.cjs` import — module resolution for a .cts source
|
||||
* is relative to src/, not the output dir) no longer matches the
|
||||
* vendored `.d.cts` under gsd-core/bin/lib/vendor/.
|
||||
* 4. The package's version pinned in package.json `devDependencies` no
|
||||
* longer matches the version actually installed at
|
||||
* node_modules/re2js/package.json (read there, per the dispatch
|
||||
* `node_modules/<pkg>/package.json` (read there, per the dispatch
|
||||
* brief, rather than duplicating a second pin).
|
||||
*
|
||||
* Hand-authored twins (js-yaml.d.cts, #3881: js-yaml ships no type
|
||||
* declarations upstream, so there is nothing to byte-compare) skip checks
|
||||
* 2 and 3 (the byte-compares) — there is no upstream/bin-side counterpart
|
||||
* to compare against, and that is deliberate rather than a gap in coverage.
|
||||
* They get a DIFFERENT check instead (#3881 review, finding 4): every
|
||||
* value-level export the twin DECLARES (`export function`/`export const`,
|
||||
* not a type/interface) must be an actual own property of the vendored
|
||||
* runtime module. `srcTwin` was previously read only inside the
|
||||
* upstream-verbatim branch — for a hand-authored row it was declared and
|
||||
* never consulted by anything, so a stale claim in the twin (a declared
|
||||
* export that no longer exists at runtime, or the reverse) could drift
|
||||
* silently. This is how a hand-authored twin's docblock/type surface could
|
||||
* make a false claim about the runtime (ADR-3473 §8.1, finding 2) without
|
||||
* this gate — or any other — ever catching it.
|
||||
*
|
||||
* Usage: node scripts/lint-vendored-deps.cjs
|
||||
* Exit 0 when every vendored copy is fresh; 1 otherwise.
|
||||
*/
|
||||
@@ -37,10 +60,82 @@ const { ExitError, runMain } = require('./lib/cli-exit.cjs');
|
||||
|
||||
const ROOT = path.join(__dirname, '..');
|
||||
|
||||
const REFRESH_COMMAND =
|
||||
'cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs && '
|
||||
+ 'cp node_modules/re2js/build/index.d.cts gsd-core/bin/lib/vendor/re2js.d.cts && '
|
||||
+ 'cp node_modules/re2js/build/index.d.cts src/vendor/re2js.d.cts';
|
||||
/**
|
||||
* Resolve a path that may be either repo-relative (the shape every VENDORED
|
||||
* row and CLI usage actually passes) or already absolute (the shape a test
|
||||
* exercising drift against a scratch file outside the repo passes). Joining
|
||||
* an absolute path onto ROOT via `path.join(ROOT, abs)` silently produces a
|
||||
* nonsense path (Windows: crossing drive letters is not even representable
|
||||
* as a relative join; POSIX: an absolute second segment wins but the result
|
||||
* is coincidental, not correct) — this makes "absolute in, absolute out"
|
||||
* explicit instead of relying on that coincidence.
|
||||
* @param {string} p
|
||||
* @returns {string}
|
||||
*/
|
||||
function resolvePath(p) {
|
||||
return path.isAbsolute(p) ? p : path.join(ROOT, p);
|
||||
}
|
||||
|
||||
/**
|
||||
* One row per vendored third-party package.
|
||||
*
|
||||
* @typedef {object} VendoredPackage
|
||||
* @property {string} name npm package name, matches package.json devDependencies key
|
||||
* @property {string} upstreamCjs path under node_modules/ to the upstream build artifact
|
||||
* @property {string} vendoredCjs path under gsd-core/bin/lib/vendor/ to the vendored copy
|
||||
* @property {string|null} upstreamDts path under node_modules/ to the upstream .d.cts/.d.ts, or
|
||||
* null when upstream ships no types (forces hand-authored)
|
||||
* @property {string|null} vendoredDts path under gsd-core/bin/lib/vendor/ to the vendored .d.cts,
|
||||
* or null when there is no bin-side type twin
|
||||
* @property {string|null} srcTwin path under src/vendor/ to the source-side type twin tsc
|
||||
* resolves for a relative import from src/**, or null
|
||||
* @property {'upstream-verbatim'|'hand-authored'} twinKind
|
||||
* 'upstream-verbatim': srcTwin/vendoredDts are byte-compared
|
||||
* against upstream and each other.
|
||||
* 'hand-authored': no upstream counterpart exists, so the
|
||||
* twin is excluded from the byte-compare (checks 2 and 3
|
||||
* above are skipped for this row).
|
||||
*/
|
||||
|
||||
/** @type {VendoredPackage[]} */
|
||||
const VENDORED = [
|
||||
{
|
||||
name: 're2js',
|
||||
upstreamCjs: 'node_modules/re2js/build/index.cjs',
|
||||
vendoredCjs: 'gsd-core/bin/lib/vendor/re2js.cjs',
|
||||
upstreamDts: 'node_modules/re2js/build/index.d.cts',
|
||||
vendoredDts: 'gsd-core/bin/lib/vendor/re2js.d.cts',
|
||||
srcTwin: 'src/vendor/re2js.d.cts',
|
||||
twinKind: 'upstream-verbatim',
|
||||
},
|
||||
{
|
||||
name: 'js-yaml',
|
||||
upstreamCjs: 'node_modules/js-yaml/dist/js-yaml.js',
|
||||
vendoredCjs: 'gsd-core/bin/lib/vendor/js-yaml.cjs',
|
||||
upstreamDts: null,
|
||||
vendoredDts: null,
|
||||
srcTwin: 'src/vendor/js-yaml.d.cts',
|
||||
twinKind: 'hand-authored',
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* Build the `cp` refresh command for one vendored package. Hand-authored
|
||||
* twins have no upstream .d.ts to cp, so only the .cjs line is emitted for
|
||||
* them; the twin itself must be refreshed by hand against the new API.
|
||||
* @param {VendoredPackage} row
|
||||
* @returns {string}
|
||||
*/
|
||||
function buildRefreshCommand(row) {
|
||||
const parts = [`cp ${row.upstreamCjs} ${row.vendoredCjs}`];
|
||||
if (row.twinKind === 'upstream-verbatim' && row.upstreamDts) {
|
||||
if (row.vendoredDts) parts.push(`cp ${row.upstreamDts} ${row.vendoredDts}`);
|
||||
if (row.srcTwin) parts.push(`cp ${row.upstreamDts} ${row.srcTwin}`);
|
||||
}
|
||||
return parts.join(' && ');
|
||||
}
|
||||
|
||||
const REFRESH_COMMAND = VENDORED.map(buildRefreshCommand).join(' && ');
|
||||
|
||||
/**
|
||||
* Compare two files byte-for-byte. Returns null when equal, or a short
|
||||
@@ -50,8 +145,8 @@ const REFRESH_COMMAND =
|
||||
* @returns {string | null}
|
||||
*/
|
||||
function compareFiles(relA, relB) {
|
||||
const absA = path.join(ROOT, relA);
|
||||
const absB = path.join(ROOT, relB);
|
||||
const absA = resolvePath(relA);
|
||||
const absB = resolvePath(relB);
|
||||
if (!fs.existsSync(absA)) return `${relA} does not exist`;
|
||||
if (!fs.existsSync(absB)) return `${relB} does not exist`;
|
||||
const a = fs.readFileSync(absA);
|
||||
@@ -70,44 +165,112 @@ function stripRangeOperator(spec) {
|
||||
return String(spec || '').trim().replace(/^[\^~]|^>=|^<=|^>|^<|^=/, '').trim();
|
||||
}
|
||||
|
||||
function main() {
|
||||
/**
|
||||
* Extract every value-level export name (`export function foo` / `export const
|
||||
* foo`) declared in a hand-authored `.d.cts` twin. Deliberately excludes
|
||||
* `export type`/`export interface` — those have no runtime existence to check
|
||||
* against, so including them would only ever produce false failures.
|
||||
* @param {string} dctsSource
|
||||
* @returns {string[]}
|
||||
*/
|
||||
function declaredValueExports(dctsSource) {
|
||||
const names = [];
|
||||
const re = /^export\s+(?:function|const|class)\s+([A-Za-z_$][\w$]*)/gm;
|
||||
let m;
|
||||
while ((m = re.exec(dctsSource)) !== null) names.push(m[1]);
|
||||
return names;
|
||||
}
|
||||
|
||||
/**
|
||||
* #3881 review, finding 4: for a `hand-authored` twin, verify every value-level
|
||||
* export it DECLARES is an actual own property of the vendored runtime module —
|
||||
* the check `srcTwin` previously had no consumer for. Returns findings (empty
|
||||
* when the twin's declared surface matches runtime reality).
|
||||
* @param {VendoredPackage} row
|
||||
* @returns {string[]}
|
||||
*/
|
||||
function checkHandAuthoredTwin(row) {
|
||||
if (!row.srcTwin) return [`${row.name}: twinKind 'hand-authored' but srcTwin is null`];
|
||||
const twinPath = resolvePath(row.srcTwin);
|
||||
if (!fs.existsSync(twinPath)) return [`${row.srcTwin} does not exist`];
|
||||
|
||||
const declared = declaredValueExports(fs.readFileSync(twinPath, 'utf8'));
|
||||
if (declared.length === 0) {
|
||||
return [`${row.srcTwin} declares zero value-level exports — nothing for this twin to gate`];
|
||||
}
|
||||
|
||||
const runtimeModule = require(resolvePath(row.vendoredCjs));
|
||||
const findings = [];
|
||||
for (const name of declared) {
|
||||
if (!Object.prototype.hasOwnProperty.call(runtimeModule, name)) {
|
||||
findings.push(
|
||||
`${row.srcTwin} declares export "${name}" — not an own property of ${row.vendoredCjs} at runtime`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return findings;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run all applicable freshness checks for one vendored package row.
|
||||
* @param {VendoredPackage} row
|
||||
* @returns {string[]} findings (empty when the row is fresh)
|
||||
*/
|
||||
function checkRow(row) {
|
||||
const findings = [];
|
||||
|
||||
const cjsDrift = compareFiles('gsd-core/bin/lib/vendor/re2js.cjs', 'node_modules/re2js/build/index.cjs');
|
||||
const cjsDrift = compareFiles(row.vendoredCjs, row.upstreamCjs);
|
||||
if (cjsDrift) findings.push(cjsDrift);
|
||||
|
||||
const dctsDrift = compareFiles('gsd-core/bin/lib/vendor/re2js.d.cts', 'node_modules/re2js/build/index.d.cts');
|
||||
if (dctsDrift) findings.push(dctsDrift);
|
||||
|
||||
const srcTwinDrift = compareFiles('src/vendor/re2js.d.cts', 'gsd-core/bin/lib/vendor/re2js.d.cts');
|
||||
if (srcTwinDrift) findings.push(srcTwinDrift);
|
||||
if (row.twinKind === 'upstream-verbatim') {
|
||||
if (row.upstreamDts && row.vendoredDts) {
|
||||
const dctsDrift = compareFiles(row.vendoredDts, row.upstreamDts);
|
||||
if (dctsDrift) findings.push(dctsDrift);
|
||||
}
|
||||
if (row.srcTwin && row.vendoredDts) {
|
||||
const srcTwinDrift = compareFiles(row.srcTwin, row.vendoredDts);
|
||||
if (srcTwinDrift) findings.push(srcTwinDrift);
|
||||
}
|
||||
} else if (row.twinKind === 'hand-authored') {
|
||||
findings.push(...checkHandAuthoredTwin(row));
|
||||
}
|
||||
|
||||
const pkgPath = path.join(ROOT, 'package.json');
|
||||
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
|
||||
const pinnedSpec = pkg.devDependencies && pkg.devDependencies.re2js;
|
||||
const pinnedSpec = pkg.devDependencies && pkg.devDependencies[row.name];
|
||||
if (!pinnedSpec) {
|
||||
findings.push('package.json devDependencies.re2js is missing');
|
||||
findings.push(`package.json devDependencies.${row.name} is missing`);
|
||||
} else {
|
||||
const installedPkgPath = path.join(ROOT, 'node_modules', 're2js', 'package.json');
|
||||
const installedPkgPath = path.join(ROOT, 'node_modules', row.name, 'package.json');
|
||||
if (!fs.existsSync(installedPkgPath)) {
|
||||
findings.push('node_modules/re2js/package.json does not exist (run npm install)');
|
||||
findings.push(`node_modules/${row.name}/package.json does not exist (run npm install)`);
|
||||
} else {
|
||||
const installed = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8'));
|
||||
const pinned = stripRangeOperator(pinnedSpec);
|
||||
if (pinned !== installed.version) {
|
||||
findings.push(
|
||||
`package.json devDependencies.re2js ("${pinnedSpec}" -> "${pinned}") != `
|
||||
+ `node_modules/re2js/package.json version ("${installed.version}")`,
|
||||
`package.json devDependencies.${row.name} ("${pinnedSpec}" -> "${pinned}") != `
|
||||
+ `node_modules/${row.name}/package.json version ("${installed.version}")`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return findings;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const findings = [];
|
||||
for (const row of VENDORED) {
|
||||
findings.push(...checkRow(row));
|
||||
}
|
||||
|
||||
if (findings.length > 0) {
|
||||
const detail = findings.map((f) => ` ${f}`).join('\n');
|
||||
const names = VENDORED.map((row) => row.name).join(', ');
|
||||
throw new ExitError(
|
||||
1,
|
||||
'lint-vendored-deps: gsd-core/bin/lib/vendor/re2js.* has drifted from its\n'
|
||||
`lint-vendored-deps: gsd-core/bin/lib/vendor/{${names}} has drifted from its\n`
|
||||
+ 'upstream package (or its version pin). Refresh with:\n'
|
||||
+ ` ${REFRESH_COMMAND}\n`
|
||||
+ 'Findings:\n'
|
||||
@@ -115,10 +278,20 @@ function main() {
|
||||
);
|
||||
}
|
||||
|
||||
process.stdout.write('ok lint-vendored-deps: gsd-core/bin/lib/vendor/re2js.* matches node_modules/re2js and its pinned version\n');
|
||||
const names = VENDORED.map((row) => row.name).join(', ');
|
||||
process.stdout.write(`ok lint-vendored-deps: gsd-core/bin/lib/vendor/{${names}} match node_modules and their pinned versions\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
|
||||
module.exports = { compareFiles, stripRangeOperator };
|
||||
module.exports = {
|
||||
compareFiles,
|
||||
stripRangeOperator,
|
||||
VENDORED,
|
||||
buildRefreshCommand,
|
||||
checkRow,
|
||||
declaredValueExports,
|
||||
checkHandAuthoredTwin,
|
||||
resolvePath,
|
||||
};
|
||||
|
||||
@@ -106,8 +106,171 @@ function readStdinSync() {
|
||||
/** Long-run target for all modules (ADR-456). */
|
||||
const TARGET_MUTATION_SCORE = 80;
|
||||
|
||||
// ── Derived test-list engine (#3881 follow-up, "one YAML parser" mutation-matrix
|
||||
// piece 2) ─────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// PROBLEM THIS REPLACES: `tests: [...]` used to be a hand-maintained array per
|
||||
// module, and `stryker.config.mjs`'s DEFAULT_TEST_CMD hand-duplicated the union
|
||||
// of every such array in a second literal. The two drifted independently — PR
|
||||
// #3888 shipped four new frontmatter test files that were never added to either
|
||||
// list, so their mutants had zero constraining coverage and the shard's score
|
||||
// silently fell (see the frontmatter entry's own PR #3888 note below, kept for
|
||||
// history). A hand list can be forgotten; a derivation cannot forget a file that
|
||||
// exists on disk.
|
||||
//
|
||||
// SIGNAL: a test file that directly `require()`s a covered module's built
|
||||
// artifact (`gsd-core/bin/lib/<name>.cjs`) is declaring, by that require, that
|
||||
// it constrains that module. That signal alone is far too broad to feed a
|
||||
// per-mutant re-run budget: measured directly (no filter) against this tree,
|
||||
// config-schema alone picks up 22 files most of this repo's spawn-heavy
|
||||
// integration suites require incidentally for fixture setup — including a file
|
||||
// literally named `graphify-auto-update.slow.test.cjs`. Stryker's command
|
||||
// runner re-runs the WHOLE test command once per mutant, so an incidental
|
||||
// integration require would multiply that module's shard cost by 10-20x for
|
||||
// zero mutation-killing benefit (those suites do not assert on config-schema's
|
||||
// internals; they merely load it as a dependency of something else under test).
|
||||
//
|
||||
// NARROWING RULE: a file is auto-derived into a module's shard only when BOTH
|
||||
// hold:
|
||||
// 1. it directly requires that module's `gsd-core/bin/lib/<name>.cjs`, and
|
||||
// 2. its own filename starts with the module's name followed by `.` or `-`
|
||||
// (i.e. `<name>.test.cjs`, `<name>.unit.test.cjs`, `<name>.property.test.cjs`,
|
||||
// `<name>-anything.test.cjs`) — the file DECLARES itself, by its own name,
|
||||
// to be that module's dedicated test surface. This is the exact naming
|
||||
// shape every entry in this registry already used before this change
|
||||
// (`*.property.test.cjs` / `*.unit.test.cjs`, or `<name>.test.cjs`), now
|
||||
// made load-bearing instead of merely conventional.
|
||||
// Measured effect of narrowing config-schema this way: 22 candidates -> 1
|
||||
// (config-schema.property.test.cjs, the file already in the shard) — the
|
||||
// naming filter is what keeps the derivation from silently tripling that
|
||||
// shard's cost, per the piece-2 "watch the cost consequence" requirement.
|
||||
//
|
||||
// ESCAPE HATCHES (both REQUIRED to be explicit, reasoned per-module entries —
|
||||
// never a silent list):
|
||||
// - `extraTests`: files that constrain this module (genuinely, by writing
|
||||
// assertions against its behaviour) but do not match the naming rule
|
||||
// above — either because the module was extracted from another file's
|
||||
// tests (context-composer) or because the file's own name follows a
|
||||
// different, still-legible convention (feat-3881-yaml-parser-consequences.test.cjs).
|
||||
// - `excludeTests`: files that DO match the naming + require signal above
|
||||
// (so the derivation would otherwise auto-include them) but are
|
||||
// deliberately withheld from the per-mutant shard for a measured,
|
||||
// documented reason (almost always: they are integration-shaped and
|
||||
// spawn a subprocess per case, so Stryker's per-mutant re-run of the
|
||||
// whole file cannot finish inside the shard's timeout — the exact #2790
|
||||
// planning-inspect.test.cjs precedent this file already documented before
|
||||
// this change; the derivation engine now enforces that precedent by
|
||||
// construction instead of leaving it to reviewer memory).
|
||||
// `computeModuleTests` combines all three into the final `tests` array; the
|
||||
// guard `scripts/lint-mutation-test-derivation-drift.cjs` independently
|
||||
// verifies every SIGNAL-matching file (require + naming rule, unfiltered by
|
||||
// this module's own excludeTests) has an explicit disposition — auto-derived,
|
||||
// named in extraTests, or named in excludeTests — so a file that newly starts
|
||||
// matching the naming rule (like #3888's four files would have, had they been
|
||||
// named `frontmatter*`) cannot silently fall through the cracks again.
|
||||
const TESTS_DIR = require('node:path').join(__dirname, '..', 'tests');
|
||||
let _testRequireCache = null;
|
||||
|
||||
/**
|
||||
* Scan every `tests/*.test.cjs` file once and cache, per covered module name,
|
||||
* which files directly `require('gsd-core/bin/lib/<name>.cjs')` (or a relative
|
||||
* equivalent — `../gsd-core/bin/lib/<name>` etc. — the require path always
|
||||
* ends in the literal segment matched below). Pure w.r.t. process lifetime;
|
||||
* the tests/ directory does not change while this process runs.
|
||||
*
|
||||
* @returns {Map<string, Set<string>>} module name -> Set of basenames (e.g. 'frontmatter.test.cjs')
|
||||
*/
|
||||
function scanTestRequires() {
|
||||
if (_testRequireCache) return _testRequireCache;
|
||||
const REQUIRE_RE = /require\(\s*['"](?:[./]*)?gsd-core\/bin\/lib\/([a-zA-Z0-9_-]+)(?:\.cjs)?['"]\s*\)/g;
|
||||
const cache = new Map();
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(TESTS_DIR).filter((f) => f.endsWith('.test.cjs'));
|
||||
} catch {
|
||||
entries = [];
|
||||
}
|
||||
for (const file of entries) {
|
||||
const text = fs.readFileSync(require('node:path').join(TESTS_DIR, file), 'utf8');
|
||||
let m;
|
||||
REQUIRE_RE.lastIndex = 0;
|
||||
while ((m = REQUIRE_RE.exec(text))) {
|
||||
const mod = m[1];
|
||||
if (!cache.has(mod)) cache.set(mod, new Set());
|
||||
cache.get(mod).add(file);
|
||||
}
|
||||
}
|
||||
_testRequireCache = cache;
|
||||
return cache;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every test file that directly requires `<moduleName>`'s built artifact —
|
||||
* the FULL, unfiltered signal set (used by the derivation-drift guard, which
|
||||
* must see every candidate regardless of naming, so it can demand an explicit
|
||||
* disposition for each one).
|
||||
*
|
||||
* @param {string} moduleName
|
||||
* @returns {string[]} sorted basenames
|
||||
*/
|
||||
function findRequiringTestFiles(moduleName) {
|
||||
const set = scanTestRequires().get(moduleName);
|
||||
return set ? [...set].sort() : [];
|
||||
}
|
||||
|
||||
/** True when `file`'s own name declares it a dedicated test surface for `moduleName`
|
||||
* (`<moduleName>.test.cjs`, or starts with `<moduleName>.` / `<moduleName>-`). */
|
||||
function matchesModuleNamingRule(moduleName, file) {
|
||||
return file === `${moduleName}.test.cjs`
|
||||
|| file.startsWith(`${moduleName}.`)
|
||||
|| file.startsWith(`${moduleName}-`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Auto-derived candidates for `moduleName`: requires the module's artifact AND
|
||||
* matches the naming rule. Does NOT apply that module's own `excludeTests` —
|
||||
* callers combine that separately (`computeModuleTests` for the real shard,
|
||||
* the guard for candidate enumeration).
|
||||
*/
|
||||
function deriveNamedTests(moduleName) {
|
||||
return findRequiringTestFiles(moduleName).filter((f) => matchesModuleNamingRule(moduleName, f));
|
||||
}
|
||||
|
||||
/**
|
||||
* Final `tests` array for a COVERED entry: auto-derived (require + naming
|
||||
* rule) UNION `extraTests` MINUS `excludeTests`, sorted, each prefixed
|
||||
* `tests/`. Throws if `excludeTests` names a file that isn't actually a
|
||||
* derived candidate (an exclusion of nothing is a stale/typo'd entry, not a
|
||||
* real decision) or if `extraTests` names a file already auto-derived (that
|
||||
* would silently mask which mechanism is responsible for its presence).
|
||||
*/
|
||||
function computeModuleTests(moduleName, entry) {
|
||||
const derived = new Set(deriveNamedTests(moduleName));
|
||||
const extra = entry.extraTests || [];
|
||||
const exclude = entry.excludeTests || [];
|
||||
for (const f of extra) {
|
||||
if (derived.has(f)) {
|
||||
throw new Error(`mutation-matrix: COVERED['${moduleName}'].extraTests names '${f}', which is already auto-derived — remove it from extraTests (it is redundant and hides which mechanism includes it)`);
|
||||
}
|
||||
}
|
||||
for (const f of exclude) {
|
||||
if (!derived.has(f)) {
|
||||
throw new Error(`mutation-matrix: COVERED['${moduleName}'].excludeTests names '${f}', which is not an auto-derived candidate for this module — remove the stale exclusion`);
|
||||
}
|
||||
}
|
||||
const excludeSet = new Set(exclude);
|
||||
const final = new Set();
|
||||
for (const f of derived) if (!excludeSet.has(f)) final.add(f);
|
||||
for (const f of extra) final.add(f);
|
||||
return [...final].sort().map((f) => `tests/${f}`);
|
||||
}
|
||||
|
||||
// ── Single source of truth: covered modules ───────────────────────────────────
|
||||
// Each entry: { cjs: '<built artifact>', tests: ['tests/...', ...], minScore: N }
|
||||
// Each entry: { cjs: '<built artifact>', extraTests: [...], excludeTests: [...], minScore: N }
|
||||
// `tests` is no longer hand-written — computeModuleTests() derives it below
|
||||
// from direct `require()`s of the module's artifact (see the derivation-engine
|
||||
// header above). extraTests/excludeTests are the two REQUIRED, reasoned escape
|
||||
// hatches; leave both `[]` (omit the key) when a module needs neither.
|
||||
//
|
||||
// minScore is the CI break threshold for this module's shard.
|
||||
// Floors are measured scores minus 1–2 pts for run-to-run variance.
|
||||
@@ -132,6 +295,15 @@ const TARGET_MUTATION_SCORE = 80;
|
||||
// RATCHET_BASELINE — which lives in tests/mutation-matrix-ratchet.test.cjs, not here — is
|
||||
// updated in the same diff as that procedure requires.
|
||||
//
|
||||
// PR #3888 (#3881 follow-up): the frontmatter shard's new tests were never registered here
|
||||
// (only the pre-existing frontmatter.property/unit + unusable-input ran), so Stryker's
|
||||
// mutants in the new vendored-parser adapter code had nothing constraining them. Score fell
|
||||
// to 55.8% against the 65 floor (748 killed / 593 survived / 17 timeout) and the shard also
|
||||
// blew the 15-minute cap. Fixed by registering the branch's four new/changed frontmatter
|
||||
// test files in the tests array above (see that entry's inline comment for which files and
|
||||
// why) and giving the shard a measured 180-minute budget via timeoutMinutes. minScore left
|
||||
// at 65 pending a fresh CI measurement with the corrected test list.
|
||||
//
|
||||
// LESSON: floors MUST be calibrated from CI mutation runs (CI runs with
|
||||
// timeout≈0, deterministic). Local runs count timeouts as kills and
|
||||
// inflate scores significantly (prompt-budget: 99.6% local vs 68.3% CI;
|
||||
@@ -140,80 +312,147 @@ const TARGET_MUTATION_SCORE = 80;
|
||||
const COVERED = {
|
||||
'context-utilization': {
|
||||
cjs: 'gsd-core/bin/lib/context-utilization.cjs',
|
||||
tests: [
|
||||
'tests/context-utilization.property.test.cjs',
|
||||
],
|
||||
// Derived: context-utilization.property.test.cjs (pre-existing) +
|
||||
// context-utilization.test.cjs (piece-2 derivation find: it directly requires and
|
||||
// matches the naming rule, but was never hand-added to the old literal list —
|
||||
// exactly the #3888 drift class this derivation exists to stop. Measured cost:
|
||||
// +50ms over the property-only baseline (58ms -> 108ms, in-process, 0 subprocess
|
||||
// spawns) — negligible for a shard whose floor is already at TARGET.
|
||||
// After mutation-killer assertions added in #1187: measured 92.31% (2026-06-14).
|
||||
// 3 survivors are __esModule boilerplate (genuinely equivalent CJS interop mutants).
|
||||
// minScore raised to TARGET (80) — module now meets ADR-456 goal.
|
||||
minScore: 80,
|
||||
// minScore raised to TARGET (80) — module now meets ADR-456 goal. Not yet
|
||||
// re-measured against the wider (derived) test list; the added file only adds
|
||||
// assertions, never removes any, so the floor cannot have fallen.
|
||||
// CI run 33012034388 (2026-08-25, #3881 ratchet): measured 92.31% (unchanged from
|
||||
// the #1187 measurement above — same test list, re-confirmed by the mutation
|
||||
// ratchet's own audit). Floor = floor(92.31) - 1 = 91.
|
||||
minScore: 91,
|
||||
},
|
||||
// context-composer: extracted from prompt-budget by #2929. Needs its own entry because
|
||||
// mutation coverage does not migrate with relocated code — scoring only prompt-budget.cjs
|
||||
// would leave the extracted ladder unmeasured.
|
||||
// would leave the extracted ladder unmeasured. Its own filename never matches the
|
||||
// "context-composer*" naming rule for prompt-budget-parity.test.cjs / prompt-budget.unit.test.cjs
|
||||
// — both genuinely constrain context-composer.cjs (the ladder was relocated INTO it), so
|
||||
// both are declared via extraTests rather than silently missing from the derivation.
|
||||
'context-composer': {
|
||||
cjs: 'gsd-core/bin/lib/context-composer.cjs',
|
||||
tests: [
|
||||
'tests/prompt-budget-parity.test.cjs',
|
||||
'tests/prompt-budget.unit.test.cjs',
|
||||
'tests/context-composer.test.cjs',
|
||||
'tests/context-composer.property.test.cjs',
|
||||
extraTests: [
|
||||
'prompt-budget-parity.test.cjs',
|
||||
'prompt-budget.unit.test.cjs',
|
||||
],
|
||||
minScore: 66,
|
||||
// CI run 33012034388 (2026-08-25, #3881 ratchet): measured 79.92%. Floor =
|
||||
// floor(79.92) - 1 = 78.
|
||||
minScore: 78,
|
||||
},
|
||||
'prompt-budget': {
|
||||
cjs: 'gsd-core/bin/lib/prompt-budget.cjs',
|
||||
tests: [
|
||||
'tests/prompt-budget.property.test.cjs',
|
||||
'tests/prompt-budget.unit.test.cjs',
|
||||
],
|
||||
// Derived: property + unit (pre-existing) plus two piece-2 derivation finds that
|
||||
// directly require prompt-budget.cjs and match the naming rule but were never in the
|
||||
// old hand list — prompt-budget-parity.test.cjs and prompt-budget.test.cjs. Measured
|
||||
// cost: 475ms (2-file) -> 527ms (4-file), in-process, 0 subprocess spawns; +52ms is
|
||||
// negligible next to this module's own mutant count.
|
||||
// CI 68.33% timeout-free (164 killed / 1 timeout / 240 total) 2026-06-14;
|
||||
// local was 99.6% — timeout inflation. Floor = 68 - 2 margin.
|
||||
minScore: 66,
|
||||
// local was 99.6% — timeout inflation. Floor = 68 - 2 margin. Not yet re-measured
|
||||
// against the wider (derived) test list; both added files only add assertions, never
|
||||
// remove any, so the floor cannot have fallen.
|
||||
// CI run 33012034388 (2026-08-25, #3881 ratchet): re-measured against the wider
|
||||
// (derived) test list at 88.95%. Floor = floor(88.95) - 1 = 87.
|
||||
minScore: 87,
|
||||
},
|
||||
frontmatter: {
|
||||
cjs: 'gsd-core/bin/lib/frontmatter.cjs',
|
||||
tests: [
|
||||
'tests/frontmatter.property.test.cjs',
|
||||
'tests/frontmatter.unit.test.cjs',
|
||||
// #1882 added the unterminated-fence detection to frontmatter.cjs, and the tests that
|
||||
// constrain it live here. Without this entry the mutants in that branch are covered by
|
||||
// no test in the shard, so the module's score drops even though the behaviour is tested.
|
||||
'tests/unusable-input.test.cjs',
|
||||
// extraTests: files that genuinely constrain frontmatter.cjs but do not match the
|
||||
// "frontmatter*" naming rule, so the derivation cannot find them on its own —
|
||||
// each earns its slot on evidence, not blanket inclusion (verified no two duplicate
|
||||
// the same constraining assertion):
|
||||
// - unusable-input.test.cjs: #1882 added the unterminated-fence detection to
|
||||
// frontmatter.cjs, and the tests that constrain it live here. Without this entry
|
||||
// the mutants in that branch are covered by no test in the shard.
|
||||
// - feat-3881-yaml-parser-consequences.test.cjs: consequence/boundary matrix for the
|
||||
// #3881 parser swap (state-transition interop, unusable-input counters, and — as of
|
||||
// the piece-1 mutation-matrix fix below — the relocated anchor-alias-bomb + B1/B2
|
||||
// block-scalar assertions). Nothing else in the shard drives
|
||||
// extractFrontmatter/reconstructFrontmatter through those seams.
|
||||
extraTests: [
|
||||
'unusable-input.test.cjs',
|
||||
'feat-3881-yaml-parser-consequences.test.cjs',
|
||||
],
|
||||
// excludeTests: files the derivation WOULD auto-include (require frontmatter.cjs
|
||||
// directly AND match the "frontmatter*" naming rule) but are deliberately withheld:
|
||||
// - frontmatter-cli.test.cjs: 778-line CLI-integration file, 39 subprocess-spawn
|
||||
// references (spawnSync/execFileSync/runGsdTools) — the same #2790
|
||||
// planning-inspect.test.cjs shape (a `node --test <file>` invocation Stryker's
|
||||
// command runner re-runs whole, once per mutant, at whatever its slowest spawn
|
||||
// case costs). Never measured in a shard; excluded up front on the same evidence
|
||||
// class rather than discovered by a timeout.
|
||||
// - frontmatter.test.cjs: mutation-matrix piece 1 (#3881 follow-up). This
|
||||
// 2932-line integration file cost 3132ms of the shard's ~4800ms per-run
|
||||
// (measured via node:test's run() API — node --test is hard-blocked locally,
|
||||
// this is the sanctioned substitute), which at ~1850 mutants (source grew 1.8x
|
||||
// for #3881) projected to ~96 of the shard's 140-minute total. Its two
|
||||
// genuinely-unique assertion classes — anchor-alias-bomb refusal (billion-laughs
|
||||
// -style anchor/alias expansion must be rejected, not expanded) and the B1/B2
|
||||
// block-scalar assertions (parsing commands/gsd/add-tests.md must not invent a
|
||||
// phantom "Example" key) — were relocated verbatim into
|
||||
// feat-3881-yaml-parser-consequences.test.cjs (already in this shard via
|
||||
// extraTests above) rather than deleted, so the mutants they kill stay killed.
|
||||
// frontmatter.test.cjs itself is UNCHANGED and keeps running in the normal
|
||||
// (non-mutation) suite — only the mutation shard drops it.
|
||||
excludeTests: [
|
||||
'frontmatter-cli.test.cjs',
|
||||
'frontmatter.test.cjs',
|
||||
],
|
||||
minScore: 65,
|
||||
// Wall-time projection, re-derived after piece 1 (dropping frontmatter.test.cjs) using
|
||||
// this file's own documented method. Mutant-count factor is unchanged: source grew 1.8x
|
||||
// for #3881 (1030 -> ~1850 mutants; see the #3888-era note this superseded for that
|
||||
// derivation). Per-run test-command cost is re-measured on the CURRENT 6-file derived
|
||||
// set (frontmatter.property/.unit/-golden-parity/-roundtrip.property + unusable-input +
|
||||
// feat-3881-yaml-parser-consequences — the shard minus frontmatter.test.cjs and minus
|
||||
// frontmatter-cli.test.cjs, neither of which was ever in a measured baseline): 1520ms,
|
||||
// vs the documented OLD 3-file baseline of 593ms — a 2.56x per-run cost increase (down
|
||||
// from the pre-piece-1 8x, since the file responsible for 3132ms of the old 4669ms
|
||||
// 7-file run is gone). Applying both factors the same way the prior note did: 586s
|
||||
// (documented 3-file/1030-mutant CI baseline) * 1.8 (mutants) * 2.56 (test cost) ~=
|
||||
// 2700s (~45 minutes). Set to 60 minutes for margin above that projection (the same
|
||||
// ~1.3x margin ratio the prior 180-minute budget used over its own 140-minute
|
||||
// projection), well under GitHub Actions' 360-minute job ceiling and a 3x cut from the
|
||||
// previous 180. Scoped to this shard only via timeoutMinutes below — every other shard
|
||||
// keeps the 15-minute default.
|
||||
timeoutMinutes: 60,
|
||||
// isolation: intentionally NOT set (defaults to 'process' below) — unchanged from the
|
||||
// prior audit: 'none' showed no reliable win once the test set grew past 3 files
|
||||
// (overlapping distributions), and dropping frontmatter.test.cjs only shrinks the set
|
||||
// further, so there is no new basis to revisit that call.
|
||||
},
|
||||
// adr-parser / config-schema / active-workstream-store / core-utils: derivation reproduces
|
||||
// their prior hand lists exactly (every constraining file's own name already matched the
|
||||
// "<module>*" rule) — no extraTests/excludeTests needed. Note config-schema in particular:
|
||||
// an UNFILTERED require-scan finds 22 files that require config-schema.cjs, but only
|
||||
// config-schema.property.test.cjs matches the naming rule — the naming filter is what
|
||||
// keeps this shard from silently ballooning to include spawn-heavy integration suites
|
||||
// (e.g. graphify-auto-update.slow.test.cjs) that merely load config-schema as a fixture
|
||||
// dependency of something else under test.
|
||||
'adr-parser': {
|
||||
cjs: 'gsd-core/bin/lib/adr-parser.cjs',
|
||||
tests: [
|
||||
'tests/adr-parser.property.test.cjs',
|
||||
'tests/adr-parser.test.cjs',
|
||||
'tests/adr-parser.unit.test.cjs',
|
||||
],
|
||||
minScore: 68,
|
||||
},
|
||||
'config-schema': {
|
||||
cjs: 'gsd-core/bin/lib/config-schema.cjs',
|
||||
tests: [
|
||||
'tests/config-schema.property.test.cjs',
|
||||
],
|
||||
// CI 54.55% timeout-free (18 killed / 0 timeout / 33 total) 2026-06-14;
|
||||
// local was 69.7% — timeout inflation. Floor = 54 - 2 margin.
|
||||
minScore: 52,
|
||||
// CI run 33012034388 (2026-08-25, #3881 ratchet): measured 75.51%. Floor =
|
||||
// floor(75.51) - 1 = 74.
|
||||
minScore: 74,
|
||||
},
|
||||
'active-workstream-store': {
|
||||
cjs: 'gsd-core/bin/lib/active-workstream-store.cjs',
|
||||
tests: [
|
||||
'tests/active-workstream-store.test.cjs',
|
||||
'tests/active-workstream-store.unit.test.cjs',
|
||||
],
|
||||
minScore: 80,
|
||||
// CI run 33012034388 (2026-08-25, #3881 ratchet): measured 87.42%. Floor =
|
||||
// floor(87.42) - 1 = 86.
|
||||
minScore: 86,
|
||||
},
|
||||
'core-utils': {
|
||||
cjs: 'gsd-core/bin/lib/core-utils.cjs',
|
||||
tests: [
|
||||
'tests/core-utils.test.cjs',
|
||||
],
|
||||
minScore: 75, // measured 77.52% (2026-06-14, issue #1187); floor = 77 - 2
|
||||
},
|
||||
// planning-inspect / plan-document / planning-command-router: net-new modules
|
||||
@@ -256,25 +495,29 @@ const COVERED = {
|
||||
// mutant, so 640 mutants x 20s could not finish inside the 15-minute shard
|
||||
// cap. The integration suite is unaffected by this change: it keeps running
|
||||
// in full in the normal (non-mutation) test job.
|
||||
// planning-inspect's own name matches "planning-inspect.unit.test.cjs" via the naming
|
||||
// rule, so that file is auto-derived. planning-inspect.test.cjs (the excluded integration
|
||||
// file the comment above names) ALSO matches the naming rule and directly requires the
|
||||
// module, so it must be an explicit excludeTests entry now — the derivation would
|
||||
// otherwise auto-include it and reproduce the exact 15-minute-cap cancellation the
|
||||
// comment above documents.
|
||||
'planning-inspect': {
|
||||
cjs: 'gsd-core/bin/lib/planning-inspect.cjs',
|
||||
tests: [
|
||||
'tests/planning-inspect.unit.test.cjs',
|
||||
],
|
||||
excludeTests: ['planning-inspect.test.cjs'],
|
||||
minScore: 56,
|
||||
},
|
||||
// plan-document / planning-command-router: their own names never appear in any test
|
||||
// filename (the shared dedicated unit file is named after planning-inspect, the module
|
||||
// #2790 extracted them alongside), so the naming-rule derivation finds nothing — same
|
||||
// cross-cutting shape as context-composer above. Declared via extraTests.
|
||||
'plan-document': {
|
||||
cjs: 'gsd-core/bin/lib/plan-document.cjs',
|
||||
tests: [
|
||||
'tests/planning-inspect.unit.test.cjs',
|
||||
],
|
||||
extraTests: ['planning-inspect.unit.test.cjs'],
|
||||
minScore: 75,
|
||||
},
|
||||
'planning-command-router': {
|
||||
cjs: 'gsd-core/bin/lib/planning-command-router.cjs',
|
||||
tests: [
|
||||
'tests/planning-inspect.unit.test.cjs',
|
||||
],
|
||||
extraTests: ['planning-inspect.unit.test.cjs'],
|
||||
minScore: 94,
|
||||
},
|
||||
// model-catalog: net-new registration by #3007. The module was entirely
|
||||
@@ -303,9 +546,13 @@ const COVERED = {
|
||||
// unit-file design above worked: the #2790 precedent's 15-minute shard-cap
|
||||
// cancellations do not apply here, and for comparison the `frontmatter`
|
||||
// shard in the same run took 9m46s.
|
||||
// model-catalog: derivation finds two files never in the old hand list —
|
||||
// model-catalog-runtime-defaults.test.cjs and model-catalog-valid-tiers.test.cjs — both
|
||||
// directly require model-catalog.cjs and match the "model-catalog*" naming rule. Measured
|
||||
// cost: 50ms (1-file) -> 196ms (3-file), in-process, 0 subprocess spawns; still far under
|
||||
// the 57s the shard already measured for the single-file set.
|
||||
'model-catalog': {
|
||||
cjs: 'gsd-core/bin/lib/model-catalog.cjs',
|
||||
tests: ['tests/model-catalog.unit.test.cjs'],
|
||||
minScore: 58,
|
||||
},
|
||||
// state-contract: net-new module from #3227. Without this entry the
|
||||
@@ -336,13 +583,23 @@ const COVERED = {
|
||||
// timeouts as kills and inflate scores badly (this file already records
|
||||
// prompt-budget 99.6% local vs 68.33% CI, and config-schema 69.7% local vs
|
||||
// 54.55% CI).
|
||||
// state-contract.test.cjs matches the naming rule and directly requires state-contract.cjs
|
||||
// but is the same spawn-heavy integration shape as planning-inspect.test.cjs (446 lines,
|
||||
// 16 subprocess-spawn references) — excluded explicitly rather than left to fall through.
|
||||
'state-contract': {
|
||||
cjs: 'gsd-core/bin/lib/state-contract.cjs',
|
||||
tests: ['tests/state-contract.unit.test.cjs'],
|
||||
excludeTests: ['state-contract.test.cjs'],
|
||||
minScore: 65,
|
||||
},
|
||||
};
|
||||
|
||||
// Compute the final, derived `tests` array for every COVERED entry. Done once, after the
|
||||
// full COVERED literal above is built, so every entry's extraTests/excludeTests declarations
|
||||
// are visible to computeModuleTests regardless of source order.
|
||||
for (const [moduleName, entry] of Object.entries(COVERED)) {
|
||||
entry.tests = computeModuleTests(moduleName, entry);
|
||||
}
|
||||
|
||||
// ── Files that, when changed, invalidate ALL modules ─────────────────────────
|
||||
// Changes to the Stryker config, this script itself, or any covered test file
|
||||
// affect all mutation scores and must force a full re-run.
|
||||
@@ -439,6 +696,15 @@ function buildResult(moduleNames) {
|
||||
mutate: COVERED[name].cjs,
|
||||
tests: COVERED[name].tests.join(' '),
|
||||
minScore: COVERED[name].minScore,
|
||||
// node:test's default per-file process isolation; only modules that document a
|
||||
// measured, audited need for 'none' opt out.
|
||||
isolation: COVERED[name].isolation || 'process',
|
||||
// Per-shard CI job timeout in minutes. Defaults to 15 (the shared per-shard budget);
|
||||
// only a module that documents a measured need for more (see the frontmatter entry
|
||||
// above) sets a higher value. Threaded through mutation.yml's job-level
|
||||
// `timeout-minutes: ${{ matrix.timeoutMinutes }}` the same way `isolation` is threaded
|
||||
// through the test-runner env.
|
||||
timeoutMinutes: COVERED[name].timeoutMinutes || 15,
|
||||
}));
|
||||
|
||||
return {
|
||||
@@ -458,6 +724,8 @@ function printHuman(result, changedFiles) {
|
||||
console.log(` mutate: ${shard.mutate}`);
|
||||
console.log(` tests: ${shard.tests}`);
|
||||
console.log(` minScore: ${shard.minScore}`);
|
||||
console.log(` isolation:${shard.isolation}`);
|
||||
console.log(` timeoutMinutes:${shard.timeoutMinutes}`);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -520,6 +788,17 @@ function resolveMutationBreak(raw) {
|
||||
|
||||
// Export internals for programmatic use (tests/mutation-matrix-ratchet.test.cjs).
|
||||
// The require.main guard prevents main() from running when this file is require()d.
|
||||
module.exports = { COVERED, TARGET_MUTATION_SCORE, resolveMutationBreak, readStdinSync };
|
||||
module.exports = {
|
||||
COVERED,
|
||||
TARGET_MUTATION_SCORE,
|
||||
resolveMutationBreak,
|
||||
readStdinSync,
|
||||
// Derivation-engine internals — exported for tests/mutation-test-derivation-drift.test.cjs
|
||||
// and scripts/lint-mutation-test-derivation-drift.cjs.
|
||||
findRequiringTestFiles,
|
||||
matchesModuleNamingRule,
|
||||
deriveNamedTests,
|
||||
computeModuleTests,
|
||||
};
|
||||
|
||||
if (require.main === module) runMain(main);
|
||||
|
||||
@@ -52,7 +52,7 @@ import planningWorkspace = require('./planning-workspace.cjs');
|
||||
const { planningDir, planningPaths } = planningWorkspace;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import frontmatter = require('./frontmatter.cjs');
|
||||
const { extractFrontmatter, agentScalarNeedsDoubleQuoting, escapeDoubleQuoted } = frontmatter;
|
||||
const { extractFrontmatter, agentScalarNeedsDoubleQuoting, escapeDoubleQuotedScalar } = frontmatter;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import modelProfiles = require('./model-profiles.cjs');
|
||||
const { MODEL_PROFILES, VALID_PHASE_TYPES } = modelProfiles;
|
||||
@@ -757,9 +757,9 @@ function setFrontmatterKeyLine(content: string, key: string, value: string): str
|
||||
// Both writers of these frontmatter keys — this sync path and the
|
||||
// install-side `frontmatterScalar` in runtime-artifact-conversion.cts —
|
||||
// now share one escaping rule: quote via `agentScalarNeedsDoubleQuoting` +
|
||||
// `escapeDoubleQuoted` (both from frontmatter.cts) rather than each
|
||||
// `escapeDoubleQuotedScalar` (both from frontmatter.cts) rather than each
|
||||
// interpolating `value` raw/differently.
|
||||
const renderedValue = agentScalarNeedsDoubleQuoting(value) ? `"${escapeDoubleQuoted(value)}"` : value;
|
||||
const renderedValue = agentScalarNeedsDoubleQuoting(value) ? `"${escapeDoubleQuotedScalar(value)}"` : value;
|
||||
// EOL comes from the MATCHED BLOCK, not the start of the file. With a
|
||||
// preamble the two can disagree, and on a CRLF document that misaligns every
|
||||
// offset below by one byte and mangles the opening fence.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -328,14 +328,23 @@ export function applyCalibration(rawTokens: RawTokens, factor: number): Calibrat
|
||||
* Extract a two-space-indented scalar block (`estimate:` / `actuals:`) out of a
|
||||
* document's leading YAML frontmatter.
|
||||
*
|
||||
* Hand-rolled because gsd-core ships no external dependencies (CONTRIBUTING.md
|
||||
* "No external dependencies in core") — js-yaml is a devDependency and is not
|
||||
* available at runtime. Scope is deliberately narrow: the leading `---` block
|
||||
* only, so a `estimate:` line inside a fenced code block in the body cannot be
|
||||
* mistaken for frontmatter (the DEFECT.FRONTMATTER-SCALAR-BROAD-GREP class).
|
||||
*
|
||||
* Numeric-looking values are returned as numbers so parseEstimate/parseActuals
|
||||
* see the types they validate; everything else stays a string.
|
||||
* Hand-rolled for its TYPE CONTRACT, not for dependency availability — js-yaml
|
||||
* is vendored and available at runtime as of ADR-3473 §8.1 (#3881), which
|
||||
* migrated `src/frontmatter.cts`'s `extractFrontmatter` onto it. That parser
|
||||
* runs under js-yaml's FAILSAFE_SCHEMA, which resolves every scalar as a
|
||||
* string, whereas this function deliberately returns numbers for
|
||||
* numeric-looking values (`out[m[1]] = asNumber : rawValue`) so
|
||||
* `parseEstimate`/`parseActuals` see the types they validate. A naive swap
|
||||
* onto `extractFrontmatter` would turn `tokens: 5000` into `"5000"` and make
|
||||
* `isPositiveInt` reject every estimate. Scope is deliberately narrow: the
|
||||
* leading `---` block only, so an `estimate:` line inside a fenced code
|
||||
* block in the body cannot be mistaken for frontmatter (the
|
||||
* DEFECT.FRONTMATTER-SCALAR-BROAD-GREP class). Migrating this function onto
|
||||
* the shared parser (with a typed coercion layer over its string-only
|
||||
* output) is tracked as follow-on work under ADR-3473 §8.1, not done here —
|
||||
* this module is calibration-critical and has a history of subtle numeric
|
||||
* defects shipping past a large green suite (#2631 factor², #2632
|
||||
* self-defeating loop).
|
||||
*/
|
||||
export function extractFrontmatterBlock(text: unknown, key: string): Record<string, unknown> | null {
|
||||
if (typeof text !== 'string') return null;
|
||||
|
||||
@@ -1845,7 +1845,7 @@ function neutralizeAgentReferences(content, instructionFile) {
|
||||
*/
|
||||
function frontmatterScalar(key: string, value: string): string {
|
||||
return frontmatterModule.agentScalarNeedsDoubleQuoting(value)
|
||||
? `${key} "${frontmatterModule.escapeDoubleQuoted(value)}"`
|
||||
? `${key} "${frontmatterModule.escapeDoubleQuotedScalar(value)}"`
|
||||
: `${key} ${value}`;
|
||||
}
|
||||
|
||||
|
||||
@@ -27,7 +27,76 @@ import stateMdSchemaMod = require('./state-md-schema.cjs');
|
||||
const { STATE_FIELD_SCHEMA } = stateMdSchemaMod;
|
||||
type StateFieldSchema = stateMdSchemaMod.StateFieldSchema;
|
||||
|
||||
const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter } = frontmatter;
|
||||
const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter, FRONTMATTER_UNPARSEABLE } = frontmatter;
|
||||
|
||||
/**
|
||||
* ADR-3473 §8.1 (#3881, consequence 2 wiring): does `existingFm` carry the
|
||||
* `FRONTMATTER_UNPARSEABLE` marker `extractFrontmatter` sets when a
|
||||
* frontmatter-fenced region exists but failed to parse (malformed YAML, or a
|
||||
* refused anchor/alias/merge key)? A plain `Object.keys(existingFm).length >
|
||||
* 0` check cannot distinguish that case from "no frontmatter block at all" —
|
||||
* both parse to `{}` — so every `hasFrontmatter`-gated reassemble below would
|
||||
* silently drop the raw frontmatter block on the next write. The marker is a
|
||||
* non-enumerable-to-Object.keys Symbol key, so this check is additive and
|
||||
* never fires for the genuinely-empty case.
|
||||
*/
|
||||
function isUnparseableFrontmatter(existingFm: Record<string, unknown>): boolean {
|
||||
return (existingFm as unknown as Record<symbol, unknown>)[FRONTMATTER_UNPARSEABLE] === true;
|
||||
}
|
||||
|
||||
/**
|
||||
* ADR-3473 §8.1 (#3881): the exact bytes `stripFrontmatter` removed from the
|
||||
* front of `content` to produce `strippedBody` — i.e. `content`'s raw
|
||||
* frontmatter-fenced prefix, verbatim, whether or not it parsed. Reassembling
|
||||
* with this prefix (instead of dropping it under `hasFrontmatter === false`)
|
||||
* is what preserves an UNPARSEABLE frontmatter block across a write; it is a
|
||||
* no-op difference from `content` itself when `strippedBody === content`
|
||||
* (nothing was stripped).
|
||||
*/
|
||||
function rawFrontmatterPrefix(content: string, strippedBody: string): string {
|
||||
return content.slice(0, content.length - strippedBody.length);
|
||||
}
|
||||
|
||||
/**
|
||||
* Shared frontmatter-strip-and-reassemble preamble (#3881 review, finding 5): the
|
||||
* `existingFm` / `hasFrontmatter` / `stripFrontmatter` / `fmPrefix` / `unparseableFm` /
|
||||
* `reassemble` block above was copy-pasted at every `*Core` transition below (and, before
|
||||
* this change, hand-inlined a sixth time in `state.cts`'s `cmdStateCompletePhase` instead of
|
||||
* importing `isUnparseableFrontmatter`/`rawFrontmatterPrefix`). One helper, one place to fix
|
||||
* the frontmatter-preservation contract. `reassemble` is parameterized on the (possibly
|
||||
* further-mutated) body rather than closing over it, matching every call site's existing
|
||||
* usage — several reassign `body` after this preamble runs and reassemble the FINAL body,
|
||||
* not the one captured here.
|
||||
*/
|
||||
export type FrontmatterReassembly = {
|
||||
existingFm: Record<string, unknown>;
|
||||
hasFrontmatter: boolean;
|
||||
body: string;
|
||||
fmPrefix: string;
|
||||
unparseableFm: boolean;
|
||||
reassemble: (b: string) => string;
|
||||
};
|
||||
|
||||
export function beginFrontmatterReassembly(
|
||||
content: string,
|
||||
sourcePath?: string,
|
||||
): FrontmatterReassembly {
|
||||
const existingFm = extractFrontmatter(content, sourcePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
const body = stripFrontmatter(content);
|
||||
// ADR-3473 §8.1 (#3881): computed from the ORIGINAL content/body pair, before any caller
|
||||
// reassigns `body` further — the captured prefix is always the exact bytes stripped from
|
||||
// the ORIGINAL content, regardless of what the caller does with `body` afterward.
|
||||
const fmPrefix = rawFrontmatterPrefix(content, body);
|
||||
const unparseableFm = isUnparseableFrontmatter(existingFm);
|
||||
const reassemble = (b: string): string =>
|
||||
hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}`
|
||||
: unparseableFm
|
||||
? `${fmPrefix}${b}`
|
||||
: b;
|
||||
return { existingFm, hasFrontmatter, body, fmPrefix, unparseableFm, reassemble };
|
||||
}
|
||||
|
||||
// Stop predicate for section-body slicing: a level-2+ heading ends the section.
|
||||
const STOP_H2_PLUS = (lv: number): boolean => lv >= 2;
|
||||
@@ -958,15 +1027,15 @@ function beginPhaseCore(
|
||||
// #1255: body-field replacements operate on body only (frontmatter stripped),
|
||||
// not on the full content. The YAML `status:` key matches `^Status:\s*`
|
||||
// before the body pipe-table row if full content is passed.
|
||||
const existingFm = extractFrontmatter(content, deps.sourcePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
const { reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
|
||||
// #3881 review, finding 5: `body` is deliberately a LITERAL `stripFrontmatter(content)`
|
||||
// assignment here rather than the helper's own `body` (which the destructure above skips) —
|
||||
// scripts/lint-state-write-path-drift.cjs's Axis 3 backward scan is a single-hop textual
|
||||
// pattern match, not real dataflow, and only recognizes `body = stripFrontmatter(...)` written
|
||||
// out at the call site. `stripFrontmatter` is pure and idempotent, so computing it here (in
|
||||
// addition to the helper's own internal call) changes nothing observable.
|
||||
let body = stripFrontmatter(content);
|
||||
|
||||
const reassemble = (b: string): string =>
|
||||
hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}`
|
||||
: b;
|
||||
|
||||
const today = deps.clock.localToday();
|
||||
|
||||
// Consult the field-classification table for the frontmatter keys this
|
||||
@@ -1310,13 +1379,8 @@ function advancePlanCore(content: string, deps: StateTransitionDeps): StateTrans
|
||||
// not on the full content. The YAML `status:` key matches `^Status:\s*`
|
||||
// before the body field if full content is passed (codex Phase 2 review:
|
||||
// HIGH blocking finding — same pattern beginPhaseCore already handles).
|
||||
const existingFm = extractFrontmatter(content, deps.sourcePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
let body = stripFrontmatter(content);
|
||||
const reassemble = (b: string): string =>
|
||||
hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}`
|
||||
: b;
|
||||
const { body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
|
||||
let body = initialBody;
|
||||
|
||||
// Parse plan number — legacy first, then compound.
|
||||
const legacyPlan = stateExtractField(content, 'Current Plan');
|
||||
@@ -1458,13 +1522,8 @@ function completePhaseCore(
|
||||
|
||||
// #1255: body-field replacements operate on body only (frontmatter stripped),
|
||||
// so the YAML `status:` / `current_phase:` keys cannot shadow the body fields.
|
||||
const existingFm = extractFrontmatter(content, deps.sourcePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
let body = stripFrontmatter(content);
|
||||
const reassemble = (b: string): string =>
|
||||
hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}`
|
||||
: b;
|
||||
const { body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
|
||||
let body = initialBody;
|
||||
|
||||
// Current Phase — preserve the existing `of <total>` shape and the phase name
|
||||
// in parens (mirrors phase.cts:1675-1697 byte-for-behaviour).
|
||||
@@ -1655,13 +1714,8 @@ function plannedPhaseCore(
|
||||
}
|
||||
|
||||
// #1255: body-field replacements operate on body only.
|
||||
const existingFm = extractFrontmatter(content, deps.sourcePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
let body = stripFrontmatter(content);
|
||||
const reassemble = (b: string): string =>
|
||||
hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}`
|
||||
: b;
|
||||
const { existingFm, hasFrontmatter, body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
|
||||
let body = initialBody;
|
||||
|
||||
const statusDefaults = KNOWN_TEMPLATE_DEFAULTS['Status'];
|
||||
const lastActivityDefaults = KNOWN_TEMPLATE_DEFAULTS['Last Activity'];
|
||||
@@ -1940,13 +1994,8 @@ function milestoneCompleteCore(
|
||||
}
|
||||
|
||||
// #1255: body-field replacements operate on body only.
|
||||
const existingFm = extractFrontmatter(content, deps.sourcePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
let body = stripFrontmatter(content);
|
||||
const reassemble = (b: string): string =>
|
||||
hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}`
|
||||
: b;
|
||||
const { body: initialBody, reassemble } = beginFrontmatterReassembly(content, deps.sourcePath);
|
||||
let body = initialBody;
|
||||
|
||||
// Status — `<version> milestone complete`.
|
||||
const statusAfter = stateReplaceFieldWithFallback(body, 'Status', null, `${version} milestone complete`);
|
||||
@@ -2071,8 +2120,10 @@ function patchCore(
|
||||
content: string,
|
||||
intent: { kind: 'patch'; patches: Record<string, string> },
|
||||
): StateTransitionResult {
|
||||
const existingFm = extractFrontmatter(content) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
const { existingFm, hasFrontmatter, fmPrefix, unparseableFm } = beginFrontmatterReassembly(content);
|
||||
// #3881 review, finding 5: see beginPhaseCore's identical comment above — `body` stays a
|
||||
// literal `stripFrontmatter(content)` assignment here for scripts/lint-state-write-path-drift.cjs's
|
||||
// Axis 3 single-hop backward scan.
|
||||
let body = stripFrontmatter(content);
|
||||
const fm: Record<string, unknown> = { ...existingFm };
|
||||
|
||||
@@ -2124,7 +2175,9 @@ function patchCore(
|
||||
|
||||
const result = hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(fm as unknown as Frontmatter)}\n---\n\n${body}`
|
||||
: body;
|
||||
: unparseableFm
|
||||
? `${fmPrefix}${body}`
|
||||
: body;
|
||||
|
||||
return { content: result, updated, data: { updated, failed } };
|
||||
}
|
||||
@@ -2145,8 +2198,10 @@ function updateCore(
|
||||
content: string,
|
||||
intent: { kind: 'update'; field: string; value: string },
|
||||
): StateTransitionResult {
|
||||
const existingFm = extractFrontmatter(content) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
const { existingFm, hasFrontmatter, reassemble } = beginFrontmatterReassembly(content);
|
||||
// #3881 review, finding 5: see beginPhaseCore's identical comment above — `body` stays a
|
||||
// literal `stripFrontmatter(content)` assignment here for scripts/lint-state-write-path-drift.cjs's
|
||||
// Axis 3 single-hop backward scan.
|
||||
const body = stripFrontmatter(content);
|
||||
// #3699 review: session-scoped fields are written through the session-scoped
|
||||
// writer. A whole-body `stateReplaceField` matches the FIRST occurrence
|
||||
@@ -2213,9 +2268,7 @@ function updateCore(
|
||||
}
|
||||
return { content, updated: [], data: { updated: false } };
|
||||
}
|
||||
const reassembled = hasFrontmatter
|
||||
? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${result}`
|
||||
: result;
|
||||
const reassembled = reassemble(result);
|
||||
return { content: reassembled, updated: [intent.field], data: { updated: true } };
|
||||
}
|
||||
|
||||
|
||||
106
src/state.cts
106
src/state.cts
@@ -39,7 +39,19 @@ const { planningDir, planningPaths } = planningWorkspace;
|
||||
import { realClock } from './clock.cjs';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import frontmatter = require('./frontmatter.cjs');
|
||||
const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter, propagateCommentChannel } = frontmatter;
|
||||
const { extractFrontmatter, reconstructFrontmatter, stripFrontmatter, propagateCommentChannel, FRONTMATTER_UNPARSEABLE } = frontmatter;
|
||||
|
||||
/**
|
||||
* ADR-3473 §8.1 (#3881, consequence 2 wiring): does `existingFm` carry the
|
||||
* `FRONTMATTER_UNPARSEABLE` marker `extractFrontmatter` sets when a frontmatter-fenced region
|
||||
* exists but failed to parse (malformed YAML, or a refused anchor/alias/merge key)? Mirrors
|
||||
* `state-transition.cts`'s private helper of the same name/shape — kept local rather than
|
||||
* exported+imported because the two modules' `existingFm` values come from independent
|
||||
* `extractFrontmatter` calls and this predicate is a two-line symbol read, not shared state.
|
||||
*/
|
||||
function isUnparseableFrontmatter(existingFm: Record<string, unknown>): boolean {
|
||||
return (existingFm as unknown as Record<symbol, unknown>)[FRONTMATTER_UNPARSEABLE] === true;
|
||||
}
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import scanPhasePlans = require('./plan-scan.cjs');
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
@@ -2833,6 +2845,30 @@ function syncStateFrontmatter(
|
||||
content,
|
||||
cwd ? planningPaths(cwd).state : undefined,
|
||||
) as Record<string, unknown>;
|
||||
|
||||
// #3881 review, second round: an UNPARSEABLE frontmatter block (malformed YAML, a git
|
||||
// merge-conflict marker, a refused anchor) must never be silently REPLACED by a freshly
|
||||
// re-derived one — that destroys the only copy of what the block actually contained, with
|
||||
// no signal to the human that their document was in conflict. `beginFrontmatterReassembly`
|
||||
// (state-transition.cts) already preserves the raw fmPrefix through the pure transform
|
||||
// layer for every `transitionCore` kind; this was the gap — this function re-parses the
|
||||
// ALREADY-preserved `content` and, finding {} + the marker, rebuilt a fresh block anyway,
|
||||
// discarding the raw prefix the transform layer had just protected. Confirmed by execution
|
||||
// against `state complete-phase`/`update`/`patch`/`begin-phase`: each returned success with
|
||||
// the conflict markers gone and a freshly-derived, well-formed frontmatter block in their
|
||||
// place (re-derivation, not deletion — the document never lost its frontmatter FENCE).
|
||||
//
|
||||
// `sanctionedPermanentEmptyFallback` is threaded ONLY from `writeStateMd`, itself consumed
|
||||
// ONLY by `cmdStateSync` (#905) and `/gsd-health --repair`'s `REGENERATE_STATE` — ADR-3408
|
||||
// §8.3's CLOSED list of commands whose documented contract is "body wins, re-derive
|
||||
// unconditionally" (a factory reset / explicit resync). Those two are untouched here: this
|
||||
// guard fires only on the OTHER call path (`syncAndPreserveStateMd`, i.e. every
|
||||
// `readModifyWriteStateMd`-based command), where re-deriving over unparseable content was
|
||||
// never the intended contract in the first place — it was an unhandled gap, not a decision.
|
||||
if (!sanctionedPermanentEmptyFallback && isUnparseableFrontmatter(existingFm)) {
|
||||
return content;
|
||||
}
|
||||
|
||||
const body = stripFrontmatter(content);
|
||||
// #3017: pass the stored milestone from the existing frontmatter so
|
||||
// buildStateFrontmatter scopes its disk scan to the correct milestone
|
||||
@@ -3031,7 +3067,7 @@ function syncStateFrontmatter(
|
||||
// #3257: propagate full-line frontmatter comments from the extracted source onto the
|
||||
// rebuilt derivedFm (buildStateFrontmatter + the Object.keys carry-forward above both
|
||||
// skip the Symbol-keyed channel, so without this the comments would be lost here even
|
||||
// though parseYamlRegion/reconstructFrontmatter preserve them in isolation).
|
||||
// though parseGuardedYamlRegion/reconstructFrontmatter preserve them in isolation).
|
||||
propagateCommentChannel(existingFm as unknown as Frontmatter, derivedFm as unknown as Frontmatter);
|
||||
|
||||
const yamlStr = reconstructFrontmatter(derivedFm as unknown as Frontmatter);
|
||||
@@ -3385,8 +3421,26 @@ function applyPostSyncPreservation(
|
||||
// above (null when resync:true) — these are independent snapshots.
|
||||
// Strip frontmatter before calling stateExtractField so the YAML `status:`
|
||||
// key in the frontmatter block cannot shadow the body field we are tracking.
|
||||
const preBody = stripFrontmatter(originalContent);
|
||||
const preFmSnapshot = extractFrontmatter(originalContent, statePath) as Record<string, unknown>;
|
||||
|
||||
// #3881 review, second round: `syncStateFrontmatter` above already declines to re-derive
|
||||
// over an UNPARSEABLE original frontmatter block (its own matching guard), so `syncedContent`
|
||||
// here is `transformedContent` verbatim. But this function's own downstream preservation
|
||||
// machinery (`applyStatePreservation` + the `authoritativeFm` reassertion below) reads
|
||||
// `postFm = extractFrontmatter(syncedContent, ...)` — {} + the marker, since the block still
|
||||
// doesn't parse — restores curated fields from `transaction.snapshot`, and reconstructs a
|
||||
// FRESH frontmatter block from the result, destroying the raw block a second time even
|
||||
// though `syncStateFrontmatter` just finished protecting it. `applyPostSyncPreservation` is
|
||||
// reached ONLY via the non-sanctioned path (`syncAndPreserveStateMd`; `writeStateMd`'s two
|
||||
// ADR-3408 §8.3 closed-list callers — `cmdStateSync` #905 and `/gsd-health --repair`'s
|
||||
// `REGENERATE_STATE` — never call it at all), so this guard needs no extra parameter to stay
|
||||
// scoped off that list. Confirmed by execution: `state begin-phase` on a conflict-marked
|
||||
// STATE.md reached exactly this second clobber even after the `syncStateFrontmatter` fix.
|
||||
if (isUnparseableFrontmatter(preFmSnapshot)) {
|
||||
return transformedContent;
|
||||
}
|
||||
|
||||
const preBody = stripFrontmatter(originalContent);
|
||||
const preBodyStatus = stateExtractField(preBody, 'Status');
|
||||
// Bug #1230 / Change B: scope stopped_at delta to the ## Session section,
|
||||
// mirroring buildStateFrontmatter's sessionBodyScope logic.
|
||||
@@ -5113,6 +5167,19 @@ function cmdStateSync(cwd: string, options: StateSyncOptions | undefined, raw: b
|
||||
|
||||
const verify = options && options.verify;
|
||||
const content = fs.readFileSync(statePath, 'utf-8');
|
||||
// ADR-3473 §8.5 (#3881): `state sync` is on ADR-3408 §8.3's closed
|
||||
// sanctioned-regenerate list — "the body wins" — and `syncStateFrontmatter`
|
||||
// (below, via `writeStateMd`'s `sanctionedPermanentEmptyFallback`) is
|
||||
// therefore CORRECT to overwrite even an unparseable existing frontmatter
|
||||
// block (git merge-conflict markers, malformed YAML). What was missing was
|
||||
// disclosure: a derived conclusion (`synced: true`) must not be reported as
|
||||
// authoritative when the derivation dropped input it could not resolve
|
||||
// (§8.5) — silently destroying the only copy of an unreadable block with no
|
||||
// signal is "failure is a value" (§8.4) violated. Computed once, up front,
|
||||
// from the pre-write snapshot so both the `--verify` (dry-run) and the real
|
||||
// write branch can surface it identically.
|
||||
const existingSyncFm = extractFrontmatter(content, statePath) as Record<string, unknown>;
|
||||
const syncFrontmatterWasUnparseable = isUnparseableFrontmatter(existingSyncFm);
|
||||
const changes: string[] = [];
|
||||
let modified = content;
|
||||
|
||||
@@ -5269,12 +5336,27 @@ function cmdStateSync(cwd: string, options: StateSyncOptions | undefined, raw: b
|
||||
const coreChanges = (syncResult.data as { changes?: string[] } | undefined)?.changes ?? [];
|
||||
changes.push(...coreChanges);
|
||||
|
||||
// #3881 (ADR-3473 §8.5): only warn when a write will actually regenerate the
|
||||
// frontmatter — if nothing changed this run, the unparseable block (if any)
|
||||
// was never touched, so there is nothing to disclose. Mirrors the exact
|
||||
// condition the write branch below uses to decide whether to write at all.
|
||||
const syncWillWrite = changes.length > 0 || modified !== content;
|
||||
if (syncWillWrite && syncFrontmatterWasUnparseable) {
|
||||
const unparseableWarning =
|
||||
`gsd: warning — STATE.md's existing frontmatter could not be parsed (malformed YAML, or ` +
|
||||
`unresolved content such as git merge-conflict markers) and was regenerated from the body; ` +
|
||||
`any content in the old frontmatter block — including merge-conflict markers — has been ` +
|
||||
`replaced. (#3881)`;
|
||||
process.stderr.write(`${unparseableWarning}\n`);
|
||||
changes.push(unparseableWarning);
|
||||
}
|
||||
|
||||
if (verify) {
|
||||
output({ synced: false, changes, dry_run: true }, raw, undefined);
|
||||
return;
|
||||
}
|
||||
|
||||
if (changes.length > 0 || modified !== content) {
|
||||
if (syncWillWrite) {
|
||||
// ADR-3473 §8.6: `rebuild()` is the typed expression of #905's contract —
|
||||
// `state sync` exists to let the body win, so preservation must NOT run,
|
||||
// and the snapshot is carried anyway because §8.7's reporting needs it.
|
||||
@@ -5689,17 +5771,21 @@ function cmdStateCompletePhase(cwd: string, raw: boolean, overridePhase?: string
|
||||
|
||||
// Bug #1255: operate on body only so the YAML frontmatter `status:` key
|
||||
// cannot shadow the body Status field (pipe-table or inline).
|
||||
const existingFm = extractFrontmatter(content, statePath) as Record<string, unknown>;
|
||||
const hasFrontmatter = Object.keys(existingFm).length > 0;
|
||||
let body = stripFrontmatter(content);
|
||||
//
|
||||
// ADR-3473 §8.1 (#3881 review, finding 5): previously this block hand-reimplemented
|
||||
// the isUnparseableFrontmatter/rawFrontmatterPrefix shape inline instead of using the
|
||||
// canonical helper — the sixth copy of a block already duplicated 5x in
|
||||
// state-transition.cts. Routed through the shared `beginFrontmatterReassembly` so this
|
||||
// module can never drift from the frontmatter-preservation contract state-transition.cts
|
||||
// enforces everywhere else.
|
||||
const { existingFm, body: initialBody, reassemble } =
|
||||
stateTransitionMod.beginFrontmatterReassembly(content, statePath);
|
||||
let body = initialBody;
|
||||
const curatedPhaseName = existingFm['current_phase_name'];
|
||||
if (typeof curatedPhaseName === 'string' && curatedPhaseName.trim().length > 0) {
|
||||
rmwOptions.authoritativeFm = { current_phase_name: curatedPhaseName };
|
||||
}
|
||||
|
||||
const reassemble = (b: string) =>
|
||||
hasFrontmatter ? `---\n${reconstructFrontmatter(existingFm as unknown as Frontmatter)}\n---\n\n${b}` : b;
|
||||
|
||||
// Update Status field (body only — #1255)
|
||||
const statusValue = `Phase ${currentPhase} complete`;
|
||||
let result = stateReplaceField(body, 'Status', statusValue);
|
||||
|
||||
89
src/vendor/js-yaml.d.cts
vendored
Normal file
89
src/vendor/js-yaml.d.cts
vendored
Normal file
@@ -0,0 +1,89 @@
|
||||
// Hand-authored type twin for gsd-core/bin/lib/vendor/js-yaml.cjs.
|
||||
//
|
||||
// js-yaml ships no type declarations of its own (`@types/js-yaml` is not
|
||||
// installed either), so unlike src/vendor/re2js.d.cts this file has no
|
||||
// upstream .d.ts to copy verbatim — it is written by hand and therefore
|
||||
// EXCLUDED from lint-vendored-deps.cjs's byte-compare (there is nothing
|
||||
// upstream to compare it against).
|
||||
//
|
||||
// The declared surface is DELIBERATELY NARROW: only `load`, `dump`,
|
||||
// `FAILSAFE_SCHEMA` and `YAMLException` (plus `load`'s `listener` callback,
|
||||
// used only to detect an anchor/alias BEFORE it is acted on) are declared.
|
||||
// This is a capability gate, not laziness — `loadAll` and any custom
|
||||
// (non-FAILSAFE) schema are genuinely unreachable from typed code that only
|
||||
// ever imports through this twin, so a caller cannot accidentally widen
|
||||
// parsing beyond what ADR-3473 §8.1 reviewed.
|
||||
//
|
||||
// CORRECTED (post-#3881-review): an earlier version of this comment claimed
|
||||
// anchors and aliases were themselves "simply UNREACHABLE" through this
|
||||
// twin. That was false — anchor/alias resolution is document-level `load`
|
||||
// mechanics, not a separate export gated by the type surface, and is
|
||||
// reachable through exactly the declared `load` + `FAILSAFE_SCHEMA` +
|
||||
// `json: true` combination this twin exposes. Anchor/alias refusal is NOT
|
||||
// enforced by narrowing this type surface; it is enforced at RUNTIME, in
|
||||
// `refuseAnchorsAndAliases` (src/frontmatter.cts), which uses `load`'s
|
||||
// `listener` callback to detect `state.anchor` and abort the parse before
|
||||
// any alias expansion happens. Do not widen this twin's surface (`loadAll`,
|
||||
// a non-FAILSAFE schema) without a matching change to the security posture
|
||||
// in ADR-3473 §8.1, and do not restate the "unreachable by type" claim for
|
||||
// anchors/aliases — it is runtime-enforced, not type-enforced.
|
||||
|
||||
/**
|
||||
* The subset of js-yaml's internal parser `State` this twin exposes to a `listener`
|
||||
* callback: just enough to detect that the CURRENT parse event belongs to an anchored
|
||||
* node. `anchor` is the anchor name (non-null/non-undefined) while js-yaml is
|
||||
* defining OR resolving an alias to it; `null`/`undefined` otherwise.
|
||||
*/
|
||||
export interface LoadListenerState {
|
||||
readonly anchor?: string | null;
|
||||
}
|
||||
|
||||
export interface LoadOptions {
|
||||
/** Overrides the schema used for parsing. Only FAILSAFE_SCHEMA is supported by this twin. */
|
||||
schema?: SchemaType;
|
||||
/**
|
||||
* When true, duplicate keys overwrite (last-wins) instead of throwing.
|
||||
* See ADR-3473 §8.1 §3.3 — required to keep the documented "last value
|
||||
* wins" invariant for `duplicate-keys.md` without a naive catch.
|
||||
*/
|
||||
json?: boolean;
|
||||
/**
|
||||
* Invoked once per parse event with the parser's internal state. Declared solely so
|
||||
* `refuseAnchorsAndAliases` (src/frontmatter.cts) can inspect `state.anchor` and abort
|
||||
* the parse — by throwing from inside the callback — before any anchor/alias is
|
||||
* expanded. Not a general-purpose parse-event hook: no other consumer should add a
|
||||
* second `listener` use without reviewing ADR-3473 §8.1's security posture.
|
||||
*/
|
||||
listener?: (event: string, state: LoadListenerState) => void;
|
||||
}
|
||||
|
||||
export interface DumpOptions {
|
||||
schema?: SchemaType;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/** Opaque marker for the vendored schema constants; not constructible from typed code. */
|
||||
export interface SchemaType {
|
||||
readonly __jsYamlSchemaBrand: unique symbol;
|
||||
}
|
||||
|
||||
/** The failsafe schema: every scalar resolves to a string; no anchors/aliases/custom types. */
|
||||
export const FAILSAFE_SCHEMA: SchemaType;
|
||||
|
||||
export function load(src: string, opts?: LoadOptions): unknown;
|
||||
|
||||
export function dump(obj: unknown, opts?: DumpOptions): string;
|
||||
|
||||
export interface YAMLExceptionMark {
|
||||
readonly line: number;
|
||||
readonly column: number;
|
||||
readonly position: number;
|
||||
}
|
||||
|
||||
export class YAMLException extends Error {
|
||||
readonly message: string;
|
||||
/** Present at runtime (verified: js-yaml assigns `this.mark` in its constructor). */
|
||||
readonly mark?: YAMLExceptionMark;
|
||||
}
|
||||
|
||||
export {};
|
||||
@@ -25,7 +25,12 @@ import { createRequire } from 'node:module';
|
||||
const _require = createRequire(import.meta.url);
|
||||
// resolveMutationBreak: fail-closed resolver for MUTATION_BREAK env var.
|
||||
// undefined → 60 (local backstop); set-but-empty or non-numeric → throws.
|
||||
const { resolveMutationBreak } = _require('./scripts/mutation-matrix.cjs');
|
||||
// COVERED: the same derived-tests registry CI's per-shard MUTATION_TEST_CMD is built from
|
||||
// (mutation.yml's `matrix.tests`) — DEFAULT_TEST_CMD below derives from it too, rather than
|
||||
// hand-duplicating the union in a second literal (#3881 follow-up, mutation-matrix piece 2:
|
||||
// this exact split — six modules' tests missing from the old hand-written DEFAULT_TEST_CMD,
|
||||
// plus two entries belonging to no module — is what this derivation removes).
|
||||
const { resolveMutationBreak, COVERED } = _require('./scripts/mutation-matrix.cjs');
|
||||
|
||||
// ADR-457: bin/lib/*.cjs are gitignored build artifacts (compiled from
|
||||
// src/*.cts by `npm run build:lib`, which the mutation CI job runs via `npm ci`
|
||||
@@ -59,10 +64,18 @@ const UNMUTATED = [
|
||||
'!gsd-core/bin/lib/gsd2-import.cjs',
|
||||
];
|
||||
|
||||
// Full test command used by local runs and as the fallback when CI does not
|
||||
// inject a per-shard command via MUTATION_TEST_CMD.
|
||||
// Keep this list in sync with the tests arrays in scripts/mutation-matrix.cjs COVERED.
|
||||
const DEFAULT_TEST_CMD = 'node --test tests/context-utilization.property.test.cjs tests/prompt-budget.property.test.cjs tests/frontmatter.property.test.cjs tests/adr-parser.property.test.cjs tests/config-schema.property.test.cjs tests/adr-parser.test.cjs tests/active-workstream-store.test.cjs tests/active-workstream-store.unit.test.cjs tests/prompt-budget.unit.test.cjs tests/adr-parser.unit.test.cjs tests/frontmatter.unit.test.cjs tests/unusable-input.test.cjs tests/core-utils.test.cjs tests/broken-windows.test.cjs tests/complexity-trigger.test.cjs';
|
||||
// Full test command used by local runs and as the fallback when CI does not inject a
|
||||
// per-shard command via MUTATION_TEST_CMD. DERIVED — never hand-edit this list; it is the
|
||||
// sorted union of every COVERED module's `tests` array (itself derived by
|
||||
// scripts/mutation-matrix.cjs's computeModuleTests from direct `require()`s of each
|
||||
// module's built artifact — see that file's derivation-engine header). A previous
|
||||
// hand-maintained literal here drifted independently of COVERED's own hand-written `tests`
|
||||
// arrays: six modules' tests were missing from it, plus two entries (broken-windows.test.cjs,
|
||||
// complexity-trigger.test.cjs) belonging to no COVERED module at all. Deriving both from the
|
||||
// same COVERED object makes that class of drift structurally impossible.
|
||||
const DEFAULT_TEST_CMD = `node --test ${
|
||||
[...new Set(Object.values(COVERED).flatMap((mod) => mod.tests))].sort().join(' ')
|
||||
}`;
|
||||
|
||||
/** @type {import('@stryker-mutator/core').PartialStrykerOptions} */
|
||||
export default {
|
||||
@@ -109,7 +122,12 @@ export default {
|
||||
incrementalFile: '.stryker-incremental.json',
|
||||
|
||||
// ── Reporters ────────────────────────────────────────────────────────────────
|
||||
reporters: ['html', 'clear-text', 'progress'],
|
||||
// 'json' (default path reports/mutation/mutation.json) is the machine-readable score
|
||||
// source for scripts/check-mutation-score-ratchet.cjs (#3881 follow-up, mutation-matrix
|
||||
// piece 3) — mutation.yml's `mutate` job reads it after `npx stryker run` to detect a
|
||||
// module whose achieved score has drifted above its floor by more than the documented
|
||||
// slack, so a stale-but-passing floor gets a loud CI failure instead of sitting forever.
|
||||
reporters: ['html', 'json', 'clear-text', 'progress'],
|
||||
htmlReporter: {
|
||||
fileName: 'reports/mutation/mutation.html',
|
||||
},
|
||||
|
||||
@@ -165,6 +165,115 @@ describe('dispatcher error paths', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// ─── --project-dir (#3881) ────────────────────────────────────────────────────
|
||||
//
|
||||
// docs/CONFIGURATION.md's "Project-Root Resolution in Multi-Repo Workspaces"
|
||||
// section documents an explicit `--project-dir /path/to/workspace` flag that
|
||||
// is "idempotent under this resolution" — i.e. it names the project root
|
||||
// directly and skips findProjectRoot's ancestor walk-up entirely. Before this
|
||||
// fix the flag was documented but wired nowhere: `state json --project-dir
|
||||
// <abs>` run from an unrelated cwd silently resolved from cwd instead and
|
||||
// returned `{"error":"STATE.md not found"}`.
|
||||
|
||||
const MARKER_3881 = 'PROJECT-B-MARKER-3881';
|
||||
|
||||
function writeMarkedState3881(projectDir, marker) {
|
||||
fs.writeFileSync(
|
||||
path.join(projectDir, '.planning', 'STATE.md'),
|
||||
`---
|
||||
gsd_state_version: 1.0
|
||||
current_phase: 01
|
||||
status: paused
|
||||
stopped_at: ${marker}
|
||||
---
|
||||
|
||||
# Project State
|
||||
|
||||
**Current Phase:** 01
|
||||
**Status:** Paused
|
||||
`
|
||||
);
|
||||
}
|
||||
|
||||
describe('#3881: --project-dir honors the documented explicit override', () => {
|
||||
test('absolute --project-dir from an unrelated cwd operates on the named project', () => {
|
||||
const projectA = createTempProject('fix-3881-a-'); // unrelated cwd; no STATE.md
|
||||
const projectB = createTempProject('fix-3881-b-');
|
||||
writeMarkedState3881(projectB, MARKER_3881);
|
||||
|
||||
try {
|
||||
const result = runGsdTools(['state', 'json', '--project-dir', projectB], projectA);
|
||||
assert.ok(result.success, `expected success, got: ${result.error || result.output}`);
|
||||
const output = JSON.parse(result.output);
|
||||
assert.strictEqual(
|
||||
output.stopped_at,
|
||||
MARKER_3881,
|
||||
"must read STATE.md from --project-dir's project, not from cwd (projectA has no STATE.md at all)"
|
||||
);
|
||||
} finally {
|
||||
cleanup(projectA);
|
||||
cleanup(projectB);
|
||||
}
|
||||
});
|
||||
|
||||
test('relative --project-dir resolves against cwd', () => {
|
||||
const projectA = createTempProject('fix-3881-a-');
|
||||
// createTempProject mkdtemps under os.tmpdir(), so projectA and projectB
|
||||
// are siblings — a relative path from A to B is well-formed.
|
||||
const projectB = createTempProject('fix-3881-b-');
|
||||
writeMarkedState3881(projectB, MARKER_3881);
|
||||
|
||||
try {
|
||||
const relative = path.relative(projectA, projectB);
|
||||
const result = runGsdTools(['state', 'json', '--project-dir', relative], projectA);
|
||||
assert.ok(result.success, `expected success, got: ${result.error || result.output}`);
|
||||
const output = JSON.parse(result.output);
|
||||
assert.strictEqual(output.stopped_at, MARKER_3881, 'relative --project-dir must resolve against cwd (projectA)');
|
||||
} finally {
|
||||
cleanup(projectA);
|
||||
cleanup(projectB);
|
||||
}
|
||||
});
|
||||
|
||||
test('nonexistent --project-dir path errors with non-zero exit', () => {
|
||||
const projectA = createTempProject('fix-3881-a-');
|
||||
try {
|
||||
const nonexistent = path.join(projectA, 'does-not-exist-3881');
|
||||
const result = runGsdTools(['state', 'json', '--project-dir', nonexistent], projectA);
|
||||
assert.strictEqual(result.success, false, 'a nonexistent --project-dir must be a non-zero exit, not a silent fallback');
|
||||
assert.match(result.error || '', /Invalid --project-dir/, 'error must name the invalid flag/path');
|
||||
} finally {
|
||||
cleanup(projectA);
|
||||
}
|
||||
});
|
||||
|
||||
test('--project-dir path with no .planning/ errors with non-zero exit', () => {
|
||||
const projectA = createTempProject('fix-3881-a-');
|
||||
const bareDir = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'fix-3881-bare-'));
|
||||
try {
|
||||
const result = runGsdTools(['state', 'json', '--project-dir', bareDir], projectA);
|
||||
assert.strictEqual(result.success, false, 'a --project-dir with no .planning/ must be a non-zero exit, not a silent wrong-project resolve');
|
||||
assert.match(result.error || '', /Invalid --project-dir/, 'error must name the invalid flag/path');
|
||||
} finally {
|
||||
cleanup(projectA);
|
||||
cleanup(bareDir);
|
||||
}
|
||||
});
|
||||
|
||||
test('without --project-dir, behavior is unchanged (cwd-relative resolution still applies)', () => {
|
||||
const projectB = createTempProject('fix-3881-b-');
|
||||
writeMarkedState3881(projectB, MARKER_3881);
|
||||
try {
|
||||
const result = runGsdTools(['state', 'json'], projectB);
|
||||
assert.ok(result.success, `expected success, got: ${result.error || result.output}`);
|
||||
const output = JSON.parse(result.output);
|
||||
assert.strictEqual(output.stopped_at, MARKER_3881, 'no-flag invocation must still resolve from cwd exactly as before');
|
||||
} finally {
|
||||
cleanup(projectB);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ─── Dispatcher Routing Branches ─────────────────────────────────────────────
|
||||
|
||||
describe('dispatcher routing branches', () => {
|
||||
|
||||
883
tests/feat-3881-yaml-parser-consequences.test.cjs
Normal file
883
tests/feat-3881-yaml-parser-consequences.test.cjs
Normal file
@@ -0,0 +1,883 @@
|
||||
// ADR-3473 §8.1 (#3881) — consequence and boundary coverage for the js-yaml migration.
|
||||
// See .gsd/phase/feat-3881-one-yaml-parser/50-test-matrix.md sections A and F. Each row
|
||||
// pins a consequence of swapping the hand-rolled line scanner for the vendored js-yaml
|
||||
// (§40-design.md §0.2) that is otherwise invisible to the existing suite.
|
||||
'use strict';
|
||||
|
||||
const { describe, test } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
|
||||
const {
|
||||
extractFrontmatter,
|
||||
reconstructFrontmatter,
|
||||
spliceFrontmatter,
|
||||
UNTERMINATED_KEY_THRESHOLD,
|
||||
FRONTMATTER_UNPARSEABLE,
|
||||
} = require('../gsd-core/bin/lib/frontmatter.cjs');
|
||||
const { transitionCore } = require('../gsd-core/bin/lib/state-transition.cjs');
|
||||
const {
|
||||
_resetUnusableInputWarningsForTests,
|
||||
_unusableInputEmissionCountForTests,
|
||||
} = require('../gsd-core/bin/lib/unusable-input.cjs');
|
||||
const { createTempDir, cleanup, runGsdTools, createTempProject } = require('./helpers.cjs');
|
||||
const { runNode } = require('./helpers/process-seam.cjs');
|
||||
const { throwIfFailed } = require('./helpers/git-fixture.cjs');
|
||||
const { PROBE_TIMEOUT_MS } = require('./helpers/timeouts.cjs');
|
||||
const TOOLS_PATH = path.join(__dirname, '..', 'gsd-core', 'bin', 'gsd-tools.cjs');
|
||||
|
||||
const fixedClock = Object.freeze({
|
||||
today: () => '2026-06-27',
|
||||
localToday: () => '2026-06-27',
|
||||
nowIso: () => '2026-06-27T12:00:00.000Z',
|
||||
});
|
||||
|
||||
function withTempDir(fn) {
|
||||
const dir = createTempDir('feat-3881-consequences-');
|
||||
try {
|
||||
return fn(dir);
|
||||
} finally {
|
||||
cleanup(dir);
|
||||
}
|
||||
}
|
||||
|
||||
// ─── A. Consequences ────────────────────────────────────────────────────────
|
||||
|
||||
describe('A1 emptyValuedKeySurvivesAWrite', () => {
|
||||
test('a key with no value round-trips through parse -> reconstruct -> re-parse with the key still present', () => {
|
||||
const doc = '---\nphase: 3\nprogress:\n---\n\nbody\n';
|
||||
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.ok(
|
||||
Object.prototype.hasOwnProperty.call(parsed, 'progress'),
|
||||
'an empty-valued key must survive the initial parse'
|
||||
);
|
||||
|
||||
// reconstructFrontmatter omits null-valued keys (frontmatter.cjs: `if (value === null ...) continue`),
|
||||
// so the empty-value contract only survives a write if extractFrontmatter never hands one back —
|
||||
// this is what pins that guarantee rather than reconstructFrontmatter's own omission logic.
|
||||
const reconstructed = reconstructFrontmatter(parsed);
|
||||
const rewritten = `---\n${reconstructed}\n---\n\nbody\n`;
|
||||
const reparsed = extractFrontmatter(rewritten);
|
||||
|
||||
assert.ok(
|
||||
Object.prototype.hasOwnProperty.call(reparsed, 'progress'),
|
||||
`progress must survive a write; reconstructed frontmatter was ${JSON.stringify(reconstructed)}`
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('A2 unparseableDocumentKeepsItsFrontmatterBlock', () => {
|
||||
test('a STATE.md with a git merge-conflict marker in its frontmatter keeps the block through beginPhase', () => {
|
||||
const fmBlock = [
|
||||
'---',
|
||||
'<<<<<<< HEAD',
|
||||
'status: foo',
|
||||
'=======',
|
||||
'status: bar',
|
||||
'>>>>>>> feature',
|
||||
'---',
|
||||
'',
|
||||
].join('\n');
|
||||
const body = [
|
||||
'# Project State',
|
||||
'',
|
||||
'**Status:** Planning',
|
||||
'',
|
||||
'## Current Position',
|
||||
'',
|
||||
'Phase: 2 — DONE',
|
||||
'Plan: —',
|
||||
'Status: Planning',
|
||||
'',
|
||||
].join('\n');
|
||||
const content = fmBlock + body;
|
||||
|
||||
// Verify reachability first: the conflicted region parses to zero keys with the
|
||||
// unparseable marker set, exercising the exact branch beginPhaseCore relies on.
|
||||
const fm = extractFrontmatter(content);
|
||||
assert.equal(Object.keys(fm).length, 0);
|
||||
assert.equal(fm[FRONTMATTER_UNPARSEABLE], true);
|
||||
|
||||
const result = transitionCore(
|
||||
content,
|
||||
{ kind: 'beginPhase', phaseNumber: 3, phaseName: 'Test Phase', planCount: 5 },
|
||||
{ clock: fixedClock }
|
||||
);
|
||||
|
||||
assert.ok(
|
||||
result.content.includes('<<<<<<< HEAD') &&
|
||||
result.content.includes('=======') &&
|
||||
result.content.includes('>>>>>>> feature'),
|
||||
`frontmatter conflict markers must survive the write; got ${JSON.stringify(result.content)}`
|
||||
);
|
||||
});
|
||||
|
||||
// Post-#3881-review, finding 7: this describe block exercised only ONE of the 8 call sites
|
||||
// that route through `beginFrontmatterReassembly` (frontmatter.cts's docblock names all 8:
|
||||
// 7 `*Core` functions in state-transition.cts, dispatched by `transitionCore`, plus 1 more
|
||||
// hand-verified separately in `state.cts`'s `cmdStateCompletePhase`). Table-driven over the
|
||||
// remaining 6 `transitionCore` kinds that share the same preservation contract.
|
||||
const OTHER_TRANSITION_KINDS = [
|
||||
['advancePlan', { kind: 'advancePlan' }],
|
||||
['completePhase', { kind: 'completePhase', phaseNum: '2', nextPhaseNum: '3', nextPhaseName: 'Next Phase', isLastPhase: false, planCount: 1, summaryCount: 1 }],
|
||||
['plannedPhase', { kind: 'plannedPhase', phaseNumber: 3, phaseName: 'Test Phase', planCount: 5 }],
|
||||
['milestoneComplete', { kind: 'milestoneComplete', version: 'v1.0', nextMilestoneCommand: '/gsd:new-milestone' }],
|
||||
['patch', { kind: 'patch', patches: { Status: 'Paused' } }],
|
||||
['update', { kind: 'update', field: 'Status', value: 'Paused' }],
|
||||
];
|
||||
|
||||
const fmBlock = [
|
||||
'---',
|
||||
'<<<<<<< HEAD',
|
||||
'status: foo',
|
||||
'=======',
|
||||
'status: bar',
|
||||
'>>>>>>> feature',
|
||||
'---',
|
||||
'',
|
||||
].join('\n');
|
||||
const body = [
|
||||
'# Project State',
|
||||
'',
|
||||
'**Status:** Planning',
|
||||
'',
|
||||
'## Current Position',
|
||||
'',
|
||||
'Phase: 2 — DONE',
|
||||
'Plan: —',
|
||||
'Status: Planning',
|
||||
'',
|
||||
].join('\n');
|
||||
const content = fmBlock + body;
|
||||
|
||||
for (const [label, intent] of OTHER_TRANSITION_KINDS) {
|
||||
test(`a git merge-conflict marker in the frontmatter keeps the block through ${label}`, () => {
|
||||
const result = transitionCore(content, intent, { clock: fixedClock, roadmapProvider: () => null });
|
||||
assert.ok(
|
||||
result.content.includes('<<<<<<< HEAD')
|
||||
&& result.content.includes('=======')
|
||||
&& result.content.includes('>>>>>>> feature'),
|
||||
`${label}: frontmatter conflict markers must survive the write; got ${JSON.stringify(result.content)}`
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
});
|
||||
|
||||
// ─── A2b. The 8th reassemble site — the real CLI path, not just the pure transform ─────────
|
||||
//
|
||||
// Post-#3881-review, second round: the 7 `transitionCore` kinds above preserve an unparseable
|
||||
// block at the PURE-TRANSFORM layer, but `state.cts`'s CLI adapters wrap every transform in
|
||||
// `readModifyWriteStateMd` -> `syncAndPreserveStateMd`, which reruns `extractFrontmatter` on
|
||||
// the (already-preserved) result and — before this fix — unconditionally re-derived a FRESH
|
||||
// frontmatter block, discarding the raw one a second time. Confirmed by execution: BEFORE the
|
||||
// fix, `state complete-phase` on a conflict-marker STATE.md returned success with the markers
|
||||
// GONE, replaced by a freshly-derived well-formed block (re-derivation, not fence deletion —
|
||||
// case (b), not (a)). Table-driven over the CLI verbs found to share the same
|
||||
// `readModifyWriteStateMd` path, plus a control proving the ADR-3408 §8.3 CLOSED-list "body
|
||||
// wins" contract (`state sync`) is untouched.
|
||||
describe('A2b unparseableFrontmatterSurvivesTheRealCliPath', () => {
|
||||
const CONFLICT_FM_BLOCK = [
|
||||
'---',
|
||||
'<<<<<<< HEAD',
|
||||
'status: foo',
|
||||
'=======',
|
||||
'status: bar',
|
||||
'>>>>>>> feature',
|
||||
'---',
|
||||
'',
|
||||
].join('\n');
|
||||
const CONFLICT_BODY = [
|
||||
'# Project State',
|
||||
'',
|
||||
'## Current Position',
|
||||
'',
|
||||
'Phase: 1 — Foundation',
|
||||
'Plan: 1 of 1',
|
||||
'Status: Executing Phase 1',
|
||||
'Last activity: 2026-07-01 — mid-flight',
|
||||
'',
|
||||
].join('\n');
|
||||
|
||||
function writeConflictFixture(tmpDir) {
|
||||
const planningDir = path.join(tmpDir, '.planning');
|
||||
fs.mkdirSync(path.join(planningDir, 'phases', '01-foundation'), { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(planningDir, 'ROADMAP.md'),
|
||||
['# Roadmap', '', '### Phase 1: Foundation', '**Goal:** Setup', ''].join('\n'),
|
||||
);
|
||||
const statePath = path.join(planningDir, 'STATE.md');
|
||||
fs.writeFileSync(statePath, CONFLICT_FM_BLOCK + CONFLICT_BODY);
|
||||
return statePath;
|
||||
}
|
||||
|
||||
const NON_SANCTIONED_VERBS = [
|
||||
['state complete-phase', ['state', 'complete-phase']],
|
||||
['state update', ['state', 'update', 'Last Activity', '2026-08-26']],
|
||||
['query state.patch', ['query', 'state.patch', JSON.stringify({ Status: 'Paused for review' })]],
|
||||
['state begin-phase', ['state', 'begin-phase', '--phase', '2', '--name', 'Next Phase']],
|
||||
];
|
||||
|
||||
for (const [label, args] of NON_SANCTIONED_VERBS) {
|
||||
test(`${label}: a git merge-conflict-marked frontmatter block survives the real CLI write`, () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const statePath = writeConflictFixture(tmpDir);
|
||||
const result = runGsdTools(args, tmpDir);
|
||||
assert.ok(result.success, `${label} failed: ${result.error}`);
|
||||
const after = fs.readFileSync(statePath, 'utf-8');
|
||||
assert.ok(
|
||||
after.includes('<<<<<<< HEAD') && after.includes('=======') && after.includes('>>>>>>> feature'),
|
||||
`${label}: conflict markers must survive; got:\n${after}`,
|
||||
);
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
test('control: state sync (ADR-3408 §8.3 CLOSED list — body wins) still overwrites unparseable frontmatter, unchanged', () => {
|
||||
// The one command that MUST keep clobbering it — a regression here would mean the fix
|
||||
// widened the closed list, which the review explicitly forbids.
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const statePath = writeConflictFixture(tmpDir);
|
||||
const result = runGsdTools(['state', 'sync'], tmpDir);
|
||||
assert.ok(result.success, `state sync failed: ${result.error}`);
|
||||
const after = fs.readFileSync(statePath, 'utf-8');
|
||||
assert.ok(
|
||||
!after.includes('<<<<<<< HEAD'),
|
||||
'state sync must still re-derive frontmatter from the body (its documented contract) — conflict markers must NOT survive',
|
||||
);
|
||||
assert.ok(/^---\r?\n/.test(after), 'state sync must still produce a well-formed frontmatter block');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// #3881 ADR-3473 §8.5: `state sync`'s "body wins" regeneration over an unparseable
|
||||
// frontmatter block (control test above, A2b) is correct and must not change — but it was
|
||||
// SILENT: `synced: true`, exit 0, no signal that the existing block (including any
|
||||
// merge-conflict markers) was unreadable and destroyed. §8.5: "a derived conclusion may not
|
||||
// be reported as authoritative when the derivation dropped input it could not resolve."
|
||||
// Table-driven per the dispatch brief's instruction to check sibling verbs on the same
|
||||
// ADR-3408 §8.3 sanctioned-regenerate list: `REGENERATE_STATE` (`/gsd-health --repair`) is
|
||||
// on that list too, but is DESTRUCTIVE-risk and unconditionally REFUSED by `applyRepairs`'s
|
||||
// dispatcher (src/health-diagnostic.cts) before `runRepairAction` is ever invoked — so
|
||||
// `state sync` is the only LIVE verb on the sanctioned path today. No table needed; a single
|
||||
// verb, driven through the real CLI, is the whole live surface.
|
||||
describe('A2c stateSyncWarnsOnUnparseableFrontmatterRegeneration', () => {
|
||||
const CONFLICT_FM_BLOCK = [
|
||||
'---',
|
||||
'<<<<<<< HEAD',
|
||||
'status: foo',
|
||||
'=======',
|
||||
'status: bar',
|
||||
'>>>>>>> feature',
|
||||
'---',
|
||||
'',
|
||||
].join('\n');
|
||||
const CONFLICT_BODY = [
|
||||
'# Project State',
|
||||
'',
|
||||
'## Current Position',
|
||||
'',
|
||||
'Phase: 1 — Foundation',
|
||||
'Plan: 1 of 1',
|
||||
'Status: Executing Phase 1',
|
||||
'Last activity: 2026-07-01 — mid-flight',
|
||||
'',
|
||||
].join('\n');
|
||||
|
||||
function seedPhaseDirs(tmpDir) {
|
||||
const planningDir = path.join(tmpDir, '.planning');
|
||||
fs.mkdirSync(path.join(planningDir, 'phases', '01-foundation'), { recursive: true });
|
||||
fs.mkdirSync(path.join(planningDir, 'phases', '02-next-phase'), { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(planningDir, 'ROADMAP.md'),
|
||||
['# Roadmap', '', '### Phase 1: Foundation', '**Goal:** Setup', '', '### Phase 2: Next', '**Goal:** More', ''].join('\n'),
|
||||
);
|
||||
}
|
||||
|
||||
function writeConflictState(tmpDir) {
|
||||
const statePath = path.join(tmpDir, '.planning', 'STATE.md');
|
||||
fs.writeFileSync(statePath, CONFLICT_FM_BLOCK + CONFLICT_BODY);
|
||||
return statePath;
|
||||
}
|
||||
|
||||
function writeValidState(tmpDir) {
|
||||
const statePath = path.join(tmpDir, '.planning', 'STATE.md');
|
||||
const validFm = [
|
||||
'---',
|
||||
'gsd_state_version: \'1.0\'',
|
||||
'status: executing',
|
||||
'current_phase: 1',
|
||||
'---',
|
||||
'',
|
||||
].join('\n');
|
||||
fs.writeFileSync(statePath, validFm + CONFLICT_BODY);
|
||||
return statePath;
|
||||
}
|
||||
|
||||
test('RED (pre-fix) proof: unparseable frontmatter — stderr carries the gsd: warning line and the JSON result surfaces it in `changes`', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
seedPhaseDirs(tmpDir);
|
||||
const statePath = writeConflictState(tmpDir);
|
||||
const r = runNode([TOOLS_PATH, 'state', 'sync', '--raw'], { cwd: tmpDir, timeoutMs: PROBE_TIMEOUT_MS });
|
||||
throwIfFailed(r, 'gsd-tools state sync --raw');
|
||||
|
||||
// Regeneration still happened (unchanged contract — the control test above pins this
|
||||
// for the general case; re-asserted here on the same fixture this warning covers).
|
||||
const after = fs.readFileSync(statePath, 'utf-8');
|
||||
assert.ok(!after.includes('<<<<<<< HEAD'), 'state sync must still regenerate over the unparseable block');
|
||||
|
||||
// Human channel: matches the existing `gsd: warning — ... (#NNNN)` precedent (#3573).
|
||||
assert.match(
|
||||
r.stderr,
|
||||
/gsd: warning — .*frontmatter.*could not be parsed.*regenerated.*\(#3881\)/s,
|
||||
`expected a gsd: warning on stderr naming the unparseable frontmatter; got stderr:\n${r.stderr}\nstdout:\n${r.stdout}`,
|
||||
);
|
||||
|
||||
// Machine channel: the JSON result's existing `changes` array (the mechanism this
|
||||
// codebase already uses to surface sync-time signals — see the "Progress: skipped —
|
||||
// ..." entries in src/state.cts) must carry the same disclosure.
|
||||
const parsed = JSON.parse(r.stdout);
|
||||
assert.ok(Array.isArray(parsed.changes), `expected a changes array in JSON result; got ${r.stdout}`);
|
||||
assert.ok(
|
||||
parsed.changes.some((c) => typeof c === 'string' && c.includes('could not be parsed') && c.includes('#3881')),
|
||||
`expected 'changes' to include the unparseable-frontmatter warning; got ${JSON.stringify(parsed.changes)}`,
|
||||
);
|
||||
assert.strictEqual(parsed.synced, true, 'exit-0/synced:true stays correct — sync did what its contract says');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
test('control (cannot pass vacuously): valid, parseable frontmatter emits NO such warning', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
seedPhaseDirs(tmpDir);
|
||||
const statePath = writeValidState(tmpDir);
|
||||
const r = runNode([TOOLS_PATH, 'state', 'sync', '--raw'], { cwd: tmpDir, timeoutMs: PROBE_TIMEOUT_MS });
|
||||
throwIfFailed(r, 'gsd-tools state sync --raw');
|
||||
|
||||
assert.doesNotMatch(
|
||||
r.stderr,
|
||||
/#3881/,
|
||||
`valid frontmatter must not trigger the unparseable-frontmatter warning; got stderr:\n${r.stderr}`,
|
||||
);
|
||||
const parsed = JSON.parse(r.stdout);
|
||||
assert.ok(
|
||||
!parsed.changes.some((c) => typeof c === 'string' && c.includes('#3881')),
|
||||
`expected no #3881 warning in changes for valid frontmatter; got ${JSON.stringify(parsed.changes)}`,
|
||||
);
|
||||
void statePath;
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('A3 unparseableIsDistinguishableFromEmpty', () => {
|
||||
test('both an empty and an unparseable block yield zero keys, but only the unparseable one carries the marker', () => {
|
||||
const empty = extractFrontmatter('---\n---\n\nbody\n');
|
||||
const unparseable = extractFrontmatter('---\nfoo: [unclosed\n---\n\nbody\n');
|
||||
|
||||
assert.equal(Object.keys(empty).length, 0);
|
||||
assert.equal(Object.keys(unparseable).length, 0);
|
||||
|
||||
assert.notEqual(
|
||||
empty[FRONTMATTER_UNPARSEABLE],
|
||||
true,
|
||||
'a genuinely empty frontmatter block must not carry the unparseable marker'
|
||||
);
|
||||
assert.equal(
|
||||
unparseable[FRONTMATTER_UNPARSEABLE],
|
||||
true,
|
||||
'a malformed frontmatter block must carry the unparseable marker'
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('A4 nonScalarValuesCanonicalize', () => {
|
||||
test('the four spellings of an object-list scalar canonicalize to one value', () => {
|
||||
const spellings = [
|
||||
'- test: "a b"',
|
||||
'- test: a b',
|
||||
"- test: 'a b'",
|
||||
'- {test: a b}',
|
||||
];
|
||||
const CANONICAL = ['test: a b'];
|
||||
|
||||
for (const spelling of spellings) {
|
||||
const doc = `---\nkey:\n${spelling}\n---\n\nbody\n`;
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.deepEqual(
|
||||
parsed.key,
|
||||
CANONICAL,
|
||||
`spelling ${JSON.stringify(spelling)} must canonicalize to ${JSON.stringify(CANONICAL)}; got ${JSON.stringify(parsed.key)}`
|
||||
);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('A5 truncationProbeStillFiresOnAnOpenFence', () => {
|
||||
test('fires on the dominant real truncation shape: opening fence, well-formed keys, then nothing', () => {
|
||||
_resetUnusableInputWarningsForTests();
|
||||
const truncated = '---\nphase: 3\nplan: 2\n';
|
||||
extractFrontmatter(truncated);
|
||||
assert.equal(
|
||||
_unusableInputEmissionCountForTests(),
|
||||
1,
|
||||
'the #1882 probe must fire on a well-formed-but-unterminated frontmatter region'
|
||||
);
|
||||
});
|
||||
|
||||
test('does NOT fire on the documented false-positive shape: a rule followed by ordinary prose', () => {
|
||||
_resetUnusableInputWarningsForTests();
|
||||
const rule = '---\nNote: this is a paragraph.\n\nJust ordinary prose after a thematic break.\n';
|
||||
extractFrontmatter(rule);
|
||||
assert.equal(
|
||||
_unusableInputEmissionCountForTests(),
|
||||
0,
|
||||
'a document that merely opens with a thematic break above prose must not be flagged as truncated'
|
||||
);
|
||||
});
|
||||
|
||||
// Post-#3881-review, finding 5: the trivially-parseable dominant shape above was the ONLY
|
||||
// shape this row exercised — vacuous for the risk it names, since it never touched
|
||||
// `countKeysBeforeTruncation`'s failure/recovery path at all (that whole-region text is
|
||||
// valid YAML; the probe fires purely from a successful parse). Table-driven over every real
|
||||
// truncation shape confirmed regressed by execution during review: an unquoted colon inside
|
||||
// a value, an open (unterminated) flow collection, a mis-indented sibling key, and an
|
||||
// anchor/alias whose refusal throws a mark-less exception. Each must still fire the #1882
|
||||
// diagnostic exactly once.
|
||||
const REGRESSED_TRUNCATION_SHAPES = [
|
||||
['unquoted colon in a value', '---\nphase: 3\ntitle: a: b\n'],
|
||||
['open (unterminated) flow collection', '---\nphase: 3\nlist: [a, b\n'],
|
||||
['mis-indented sibling key', '---\nphase: 3\n plan: 2\n'],
|
||||
['anchor/alias — refusal throws a mark-less exception', '---\nphase: 3\nfoo: &a bar\n'],
|
||||
];
|
||||
|
||||
for (const [label, doc] of REGRESSED_TRUNCATION_SHAPES) {
|
||||
test(`fires on a real truncation shape the mark-based recovery regressed on: ${label}`, () => {
|
||||
_resetUnusableInputWarningsForTests();
|
||||
extractFrontmatter(doc);
|
||||
assert.equal(
|
||||
_unusableInputEmissionCountForTests(),
|
||||
1,
|
||||
`the #1882 probe must fire on an unterminated region shaped like: ${label}; doc=${JSON.stringify(doc)}`
|
||||
);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
describe('A6 commentsStayOnTheirOwnKey', () => {
|
||||
test('a column-0 comment above a Unicode key attaches to that key and survives a round-trip', () => {
|
||||
const doc = '---\nfoo: bar\n# note\n相: baz\n---\n\nbody\n';
|
||||
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.deepEqual(Object.keys(parsed), ['foo', '相']);
|
||||
assert.equal(parsed['相'], 'baz');
|
||||
|
||||
const reconstructed = reconstructFrontmatter(parsed);
|
||||
const commentLine = reconstructed.split('\n').find((l) => l.startsWith('#'));
|
||||
const keyLine = reconstructed.split('\n').find((l) => l.startsWith('相:'));
|
||||
assert.ok(commentLine, `reconstructed frontmatter must carry the comment; got ${JSON.stringify(reconstructed)}`);
|
||||
const commentIdx = reconstructed.split('\n').indexOf(commentLine);
|
||||
const keyIdx = reconstructed.split('\n').indexOf(keyLine);
|
||||
assert.equal(keyIdx, commentIdx + 1, 'the comment must sit immediately above the 相 key, not the following one');
|
||||
|
||||
// Round-trip: reparsing the reconstructed block and reconstructing again is byte-identical.
|
||||
const rewritten = `---\n${reconstructed}\n---\n\nbody\n`;
|
||||
const reparsed = extractFrontmatter(rewritten);
|
||||
assert.equal(reconstructFrontmatter(reparsed), reconstructed);
|
||||
});
|
||||
});
|
||||
|
||||
describe('A7 anchorsAndAliasesAreRefused', () => {
|
||||
// #3881 review, finding 1: the original refusal was a raw-line regex matching only the
|
||||
// bare-key spelling (`key: &x`). A quoted key, a flow mapping and a flow sequence all
|
||||
// define/use the SAME anchor mechanics while never matching that line shape — table-driven
|
||||
// over every spelling that was confirmed bypassable, plus the original passing case, so a
|
||||
// future regression in any one spelling fails loudly rather than hiding behind the others.
|
||||
const SPELLINGS = [
|
||||
['plain', '---\nfoo: &a bar\nbaz: *a\n---\n\nbody\n'],
|
||||
['quoted key', '---\n"foo": &a bar\n"baz": *a\n---\n\nbody\n'],
|
||||
['flow mapping', '---\na: {b: &a 1, c: *a}\n---\n\nbody\n'],
|
||||
['flow sequence', '---\na: [&a "q", *a]\n---\n\nbody\n'],
|
||||
['merge key (<<:) with an alias', '---\nbase: &b\n x: "1"\nfoo:\n <<: *b\n y: "2"\n---\n\nbody\n'],
|
||||
];
|
||||
|
||||
for (const [label, doc] of SPELLINGS) {
|
||||
test(`${label}: refused rather than expanded`, () => {
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.equal(Object.keys(parsed).length, 0, `${label} must parse to zero keys`);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true, `${label} must carry the unparseable marker`);
|
||||
});
|
||||
}
|
||||
|
||||
test('a bare merge key with NO alias is not itself refused (no anchor, no expansion risk)', () => {
|
||||
// Under FAILSAFE_SCHEMA (no !!merge type resolution) this never actually merges — it
|
||||
// parses as an ordinary, non-expanding literal "<<" string key. Documented behavior
|
||||
// change from the pre-review regex (which refused every `<<:`-shaped line regardless of
|
||||
// whether an alias was present) — see frontmatter.cts refuseAnchorsAndAliases docblock.
|
||||
const doc = '---\na:\n <<: {b: 1}\n c: 2\n---\n\nbody\n';
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.notEqual(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
assert.deepEqual(parsed.a, { '<<': { b: '1' }, c: '2' });
|
||||
});
|
||||
});
|
||||
|
||||
describe('A8 aliasExpansionCannotExhaustMemory', () => {
|
||||
test('a billion-laughs frontmatter is refused, bounded on the RESULT, never on elapsed time', () => {
|
||||
const bomb = [
|
||||
'a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol"]',
|
||||
'b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a]',
|
||||
'c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b]',
|
||||
'd: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c]',
|
||||
'e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d]',
|
||||
'f: &f [*e,*e,*e,*e,*e,*e,*e,*e,*e]',
|
||||
'g: [*f,*f,*f,*f,*f,*f,*f,*f,*f]',
|
||||
].join('\n');
|
||||
const doc = `---\n${bomb}\n---\n\nbody\n`;
|
||||
|
||||
const parsed = extractFrontmatter(doc);
|
||||
|
||||
// Assertions are on the RESULT SHAPE (zero keys, bounded serialized size), never on
|
||||
// wall-clock elapsed time — this repo forbids elapsed-time assertions in tests.
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
const serializedSize = Buffer.byteLength(JSON.stringify(parsed), 'utf8');
|
||||
assert.ok(
|
||||
serializedSize < 1024,
|
||||
`a refused parse must stay tiny (would be ~22.8MB if expanded); got ${serializedSize} bytes`
|
||||
);
|
||||
});
|
||||
|
||||
test('the same billion-laughs bomb, quoted-key-spelled, is ALSO refused (#3881 review, finding 1)', () => {
|
||||
// The exact bypass the review found: the pre-fix raw-text regex matched only bare
|
||||
// (unquoted) keys, so this 303-byte quoted-key spelling of the identical bomb went
|
||||
// straight through unrefused and expanded to ~35.8MB. Pinned here on the RESULT shape.
|
||||
const bomb = [
|
||||
'"a": &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol"]',
|
||||
'"b": &b [*a,*a,*a,*a,*a,*a,*a,*a,*a]',
|
||||
'"c": &c [*b,*b,*b,*b,*b,*b,*b,*b,*b]',
|
||||
'"d": &d [*c,*c,*c,*c,*c,*c,*c,*c,*c]',
|
||||
'"e": &e [*d,*d,*d,*d,*d,*d,*d,*d,*d]',
|
||||
'"f": &f [*e,*e,*e,*e,*e,*e,*e,*e,*e]',
|
||||
'"g": [*f,*f,*f,*f,*f,*f,*f,*f,*f]',
|
||||
].join('\n');
|
||||
const doc = `---\n${bomb}\n---\n\nbody\n`;
|
||||
|
||||
const parsed = extractFrontmatter(doc);
|
||||
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
const serializedSize = Buffer.byteLength(JSON.stringify(parsed), 'utf8');
|
||||
assert.ok(
|
||||
serializedSize < 1024,
|
||||
`a refused parse must stay tiny (would be ~35.8MB if expanded); got ${serializedSize} bytes`
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// A9: fix #3881/#3881-followup-2 (regression pinned by tests/smart-entry.unit.test.cjs:867,
|
||||
// tests/smart-entry.property.test.cjs). `repairAmbiguousColonValues`'s only real dependent is
|
||||
// hand-edited STATE.md content that never lives in this repo's own tracked `*.md` files — a
|
||||
// tracked-document sweep will always show zero dependents for this function, which is exactly
|
||||
// the wrong signal to delete it on (see `loadWithAmbiguousColonRepair`'s docblock in
|
||||
// src/frontmatter.cts). This row pins the dependency at the frontmatter layer itself, so the
|
||||
// next document sweep sees it here too, not only three modules away in smart-entry.
|
||||
describe('A9 ambiguousColonRepairSurvivesHandEditedStateMd (#2571/#2570)', () => {
|
||||
test('a colon-separated date+description value parses to the full string after the first colon', () => {
|
||||
const doc = '---\nlast_activity: 2026-06-08: reviewed the PR queue\n---\n\nbody\n';
|
||||
|
||||
const parsed = extractFrontmatter(doc);
|
||||
|
||||
assert.equal(
|
||||
parsed.last_activity,
|
||||
'2026-06-08: reviewed the PR queue',
|
||||
'the ambiguous colon must be repaired rather than the whole region going unparseable'
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('finding 3: null-byte sentinel round-trip is injective', () => {
|
||||
const E000 = String.fromCharCode(0xE000);
|
||||
|
||||
test('a real NUL is preserved exactly when no pre-existing U+E000 is present', () => {
|
||||
const doc = '---\nfoo: "has null"\n---\n\nbody\n';
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.equal(parsed.foo, 'has null');
|
||||
});
|
||||
|
||||
test('a document containing a literal U+E000 (the sentinel itself) is refused, not silently corrupted', () => {
|
||||
// Before the fix, restoreNullBytesDeep rewrote EVERY U+E000 in the parsed tree back to
|
||||
// U+0000 unconditionally — including one the document author legitimately wrote — so this
|
||||
// document's own U+E000 silently became a NUL. It must now be refused instead.
|
||||
const doc = `---\nfoo: "pre${E000}existing"\n---\n\nbody\n`;
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
});
|
||||
|
||||
test('a literal U+E000 alongside a real NUL is refused rather than merging the two into one byte', () => {
|
||||
// The exact corruption case from the review: escaping the real NUL to U+E000 makes it
|
||||
// indistinguishable from the pre-existing U+E000, and restoring converts BOTH back to NUL.
|
||||
const doc = `---\nfoo: "has null"\nbar: "pre${E000}existing"\n---\n\nbody\n`;
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── F. Boundaries ──────────────────────────────────────────────────────────
|
||||
|
||||
describe('F1 UNTERMINATED_KEY_THRESHOLD boundary', () => {
|
||||
function unterminatedRegionWithKeys(n) {
|
||||
const lines = [];
|
||||
for (let i = 0; i < n; i++) lines.push(`k${i}: v${i}`);
|
||||
return `---\n${lines.join('\n')}\n`;
|
||||
}
|
||||
|
||||
test('threshold-1 keys: no diagnostic', () => {
|
||||
_resetUnusableInputWarningsForTests();
|
||||
extractFrontmatter(unterminatedRegionWithKeys(UNTERMINATED_KEY_THRESHOLD - 1));
|
||||
assert.equal(_unusableInputEmissionCountForTests(), 0);
|
||||
});
|
||||
|
||||
test('threshold keys: fires', () => {
|
||||
_resetUnusableInputWarningsForTests();
|
||||
extractFrontmatter(unterminatedRegionWithKeys(UNTERMINATED_KEY_THRESHOLD));
|
||||
assert.equal(_unusableInputEmissionCountForTests(), 1);
|
||||
});
|
||||
|
||||
test('threshold+1 keys: fires', () => {
|
||||
_resetUnusableInputWarningsForTests();
|
||||
extractFrontmatter(unterminatedRegionWithKeys(UNTERMINATED_KEY_THRESHOLD + 1));
|
||||
assert.equal(_unusableInputEmissionCountForTests(), 1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('F2 alias/nesting refusal bound', () => {
|
||||
// refuseAnchorsAndAliases (frontmatter.cjs) is a raw-text pre-scan that refuses on ANY
|
||||
// line carrying an anchor/alias/merge-key marker — there is no numeric count threshold
|
||||
// in this implementation. The real boundary it exercises is therefore an occurrence
|
||||
// COUNT: 0 (below the refusal trigger) parses; 1 (the trigger) is refused; 2 (over) stays
|
||||
// refused, proving the refusal is not a first-occurrence artifact that a second alias
|
||||
// could slip past.
|
||||
test('0 anchor/alias lines: parses normally', () => {
|
||||
const doc = '---\nfoo: bar\nbaz: qux\n---\n\nbody\n';
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.deepEqual(parsed, { foo: 'bar', baz: 'qux' });
|
||||
});
|
||||
|
||||
test('1 anchor/alias line: refused', () => {
|
||||
const doc = '---\nfoo: &a bar\nbaz: qux\n---\n\nbody\n';
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
});
|
||||
|
||||
test('2 anchor/alias lines: still refused', () => {
|
||||
const doc = '---\nfoo: &a bar\nbaz: *a\n---\n\nbody\n';
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('F3 frontmatter size boundary', () => {
|
||||
const FIXTURE_PATH = path.join(__dirname, 'fixtures', 'adversarial', 'frontmatter', 'huge-bounded.md');
|
||||
|
||||
test('~30KB fixture (huge-bounded.md) completes with a typed result', () => {
|
||||
const content = fs.readFileSync(FIXTURE_PATH, 'utf8');
|
||||
const parsed = extractFrontmatter(content, FIXTURE_PATH);
|
||||
assert.equal(typeof parsed, 'object');
|
||||
assert.ok(Array.isArray(parsed.plans));
|
||||
assert.ok(parsed.plans.length > 0);
|
||||
});
|
||||
|
||||
test('a larger (~640KB) frontmatter block also completes with a typed result', () => {
|
||||
withTempDir((dir) => {
|
||||
const lines = ['---', 'phase: "06"', 'plans:'];
|
||||
// ~640KB of array items — an order of magnitude above the committed ~30KB fixture,
|
||||
// isolated in a per-test temp file rather than a new committed fixture.
|
||||
for (let i = 0; i < 40000; i++) {
|
||||
lines.push(` - item-${String(i).padStart(5, '0')}`);
|
||||
}
|
||||
lines.push('---', '', 'Body.', '');
|
||||
const content = lines.join('\n');
|
||||
assert.ok(Buffer.byteLength(content, 'utf8') > 500 * 1024, 'fixture must exceed the committed one by an order of magnitude');
|
||||
|
||||
const filePath = path.join(dir, 'huge-bounded-larger.md');
|
||||
fs.writeFileSync(filePath, content, 'utf8');
|
||||
const readBack = fs.readFileSync(filePath, 'utf8');
|
||||
|
||||
const parsed = extractFrontmatter(readBack, filePath);
|
||||
assert.equal(typeof parsed, 'object');
|
||||
assert.ok(Array.isArray(parsed.plans));
|
||||
assert.equal(parsed.plans.length, 40000);
|
||||
assert.equal(parsed.plans[0], 'item-00000');
|
||||
assert.equal(parsed.plans[39999], 'item-39999');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// Relocated from tests/frontmatter.test.cjs (mutation-matrix piece 1, #3881 follow-up): the
|
||||
// mutation shard dropped tests/frontmatter.test.cjs (2932 lines, 3132ms of the shard's 4800ms
|
||||
// per-run cost, ~96 minutes of the frontmatter shard's 180-minute budget for that one file) to
|
||||
// stay inside CI's time budget, but that file was the ONLY place two assertion classes lived —
|
||||
// the anchor-alias-bomb refusal (ADR-3473 §8.1 consequence 6, row A8) and the B1/B2 block-scalar
|
||||
// assertions. Both are relocated here verbatim (not re-derived) so the mutants they kill stay
|
||||
// killed after frontmatter.test.cjs leaves the shard's `tests` list. frontmatter.test.cjs itself
|
||||
// keeps these exact assertions too (not deleted there) — it still runs in the normal (non-mutation)
|
||||
// suite, so this is a second, mutation-scoped copy, not a move.
|
||||
describe('anchor-alias-bomb refusal (relocated from tests/frontmatter.test.cjs for mutation-matrix piece 1)', () => {
|
||||
const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'adversarial', 'frontmatter');
|
||||
function readFixture(name) {
|
||||
return fs.readFileSync(path.join(FIXTURE_DIR, name), 'utf8');
|
||||
}
|
||||
|
||||
test('anchor-alias-bomb.md: refused rather than expanded (ADR-3473 §8.1 consequence 6, row A8)', () => {
|
||||
const parsed = extractFrontmatter(readFixture('anchor-alias-bomb.md'), 'anchor-alias-bomb.md');
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
assert.ok(Buffer.byteLength(JSON.stringify(parsed), 'utf8') < 1024);
|
||||
});
|
||||
|
||||
test('anchor-alias-bomb-quoted.md: refused identically, even quoted-key-spelled (#3881 review, finding 1)', () => {
|
||||
const parsed = extractFrontmatter(readFixture('anchor-alias-bomb-quoted.md'), 'anchor-alias-bomb-quoted.md');
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
assert.ok(Buffer.byteLength(JSON.stringify(parsed), 'utf8') < 1024);
|
||||
});
|
||||
});
|
||||
|
||||
describe('B1/B2 block-scalar assertions (relocated from tests/frontmatter.test.cjs for mutation-matrix piece 1)', () => {
|
||||
const ADD_TESTS_PATH = path.join(__dirname, '..', 'commands', 'gsd', 'add-tests.md');
|
||||
|
||||
test('B1 blockScalarValueIsNotTheBlockIndicator: argument-instructions is the instruction text, not "|"', () => {
|
||||
const content = fs.readFileSync(ADD_TESTS_PATH, 'utf8');
|
||||
const parsed = extractFrontmatter(content, ADD_TESTS_PATH);
|
||||
const value = parsed['argument-instructions'];
|
||||
assert.equal(typeof value, 'string');
|
||||
assert.notEqual(value, '|');
|
||||
assert.ok(value.length > 1, 'block scalar value must be the multi-line instruction body');
|
||||
assert.ok(value.includes('Parse the argument as a phase number'), 'block scalar value must retain the source instruction text');
|
||||
});
|
||||
|
||||
test('B2 blockScalarDoesNotInventATopLevelKey: parsing add-tests.md produces no phantom "Example" key', () => {
|
||||
const content = fs.readFileSync(ADD_TESTS_PATH, 'utf8');
|
||||
const parsed = extractFrontmatter(content, ADD_TESTS_PATH);
|
||||
assert.ok(!Object.prototype.hasOwnProperty.call(parsed, 'Example'), 'parser must not scrape a top-level "Example" key out of the block scalar body');
|
||||
});
|
||||
});
|
||||
|
||||
// Frontmatter mutation-gap closure (#3881 follow-up, CI run 33012034388): the frontmatter
|
||||
// shard measured 63.03% against its 65 floor. These tests close the gap by constraining real
|
||||
// behavior in the four highest-value survivor clusters — canonical flattening's no-op guard
|
||||
// (frontmatterDeepEqual, gates spliceFrontmatter's whole-document identity check), the writer's
|
||||
// double-quoting decision (scalarNeedsDoubleQuoting), the reader's ambiguous-colon repair
|
||||
// (repairAmbiguousColonValues), and the null-byte round-trip (escapeNullBytesForParse). Each
|
||||
// case below is paired with a documented near-miss so a mutant that weakens the real condition
|
||||
// (not just a syntactically different one) is observably wrong, not merely re-typed.
|
||||
|
||||
describe('frontmatterDeepEqual (via spliceFrontmatter no-op detection)', () => {
|
||||
test('key order is insignificant for objects: a same-value, reordered-keys write is a byte-exact no-op', () => {
|
||||
const doc = '---\na: 1\nb: 2\n---\n\nbody\n';
|
||||
assert.equal(spliceFrontmatter(doc, { b: '2', a: '1' }), doc);
|
||||
});
|
||||
|
||||
test('array order IS significant: same elements in a different order is NOT a no-op', () => {
|
||||
// Near-miss for the .every -> .some mutant: index 0 matches ("x"==="x") but index 1 does
|
||||
// not ("y" !== "z"). The real .every-based comparison must see this as unequal (regenerate);
|
||||
// a .some-based mutant would short-circuit true on the matching index-0 element alone and
|
||||
// wrongly report a no-op.
|
||||
const doc = '---\ntags:\n - x\n - y\n---\n\nbody\n';
|
||||
const result = spliceFrontmatter(doc, { tags: ['x', 'z'] });
|
||||
assert.notEqual(result, doc, 'a value-changed array must not be treated as a no-op write');
|
||||
});
|
||||
|
||||
test('a new array value that differs only in length is NOT a no-op', () => {
|
||||
const doc = '---\ntags:\n - x\n---\n\nbody\n';
|
||||
assert.notEqual(spliceFrontmatter(doc, { tags: ['x', 'y'] }), doc);
|
||||
});
|
||||
|
||||
test('two empty arrays of matching (zero) length ARE a no-op', () => {
|
||||
const doc = '---\ntags: []\n---\n\nbody\n';
|
||||
assert.equal(spliceFrontmatter(doc, { tags: [] }), doc);
|
||||
});
|
||||
|
||||
test('an array-valued field replaced with a same-text scalar is NOT a no-op (array vs non-array must never compare equal)', () => {
|
||||
const doc = '---\ntags:\n - x\n---\n\nbody\n';
|
||||
assert.notEqual(spliceFrontmatter(doc, { tags: 'x' }), doc);
|
||||
});
|
||||
|
||||
test('nested-object key order is insignificant: a same-value, reordered-keys nested object is a no-op', () => {
|
||||
const doc = '---\nmeta:\n a: "1"\n b: "2"\n---\n\nbody\n';
|
||||
assert.equal(spliceFrontmatter(doc, { meta: { b: '2', a: '1' } }), doc);
|
||||
});
|
||||
|
||||
test('a nested object with a genuinely different key set is NOT a no-op', () => {
|
||||
const doc = '---\nmeta:\n a: "1"\n b: "2"\n---\n\nbody\n';
|
||||
assert.notEqual(spliceFrontmatter(doc, { meta: { a: '1', c: '2' } }), doc);
|
||||
});
|
||||
});
|
||||
|
||||
describe('scalarNeedsDoubleQuoting (via reconstructFrontmatter double-quoting decisions)', () => {
|
||||
test('a value with internal (non-leading, non-trailing) whitespace is NOT quoted', () => {
|
||||
// Near-miss for the /^\s|\s$/ -> /^\s|\s/ mutant (dropped end-anchor): a mutant that tests
|
||||
// for whitespace ANYWHERE rather than only leading/trailing would wrongly quote this.
|
||||
assert.equal(reconstructFrontmatter({ key: 'mid dle' }), 'key: mid dle');
|
||||
});
|
||||
|
||||
test('trailing whitespace alone (no leading whitespace) IS quoted', () => {
|
||||
assert.equal(reconstructFrontmatter({ key: 'trailing ' }), 'key: "trailing "');
|
||||
});
|
||||
|
||||
test('a leading dash followed by a space IS quoted (reads as a YAML list indicator)', () => {
|
||||
assert.equal(reconstructFrontmatter({ key: '- item' }), 'key: "- item"');
|
||||
});
|
||||
|
||||
test('a leading dash with NO following space is NOT quoted (near-miss control for the above)', () => {
|
||||
assert.equal(reconstructFrontmatter({ key: '-item' }), 'key: -item');
|
||||
});
|
||||
|
||||
test('a lone UTF-16 surrogate is quoted (bare emission is invalid YAML and would not re-parse)', () => {
|
||||
const reconstructed = reconstructFrontmatter({ key: '\uD800' });
|
||||
assert.equal(reconstructed, 'key: "\\uD800"');
|
||||
});
|
||||
});
|
||||
|
||||
// `repairAmbiguousColonValues` (and its sibling `repairMalformedInlineArrays` +
|
||||
// `splitLegacyInlineArrayItems`) was deleted (#3881 follow-up): a sweep of every tracked
|
||||
// `*.md` file with a frontmatter fence (910 files) found ZERO documents whose parse result
|
||||
// changed with the repair disabled — it was hand-rolled YAML leniency kept alive on a fallback
|
||||
// path, the exact thing ADR-3473 §8.1 exists to remove. `extractFrontmatter` now surfaces
|
||||
// `unparseableResult()` (via `FRONTMATTER_UNPARSEABLE`) for the ambiguous-colon shapes this
|
||||
// block used to pin instead of silently repairing them.
|
||||
|
||||
describe('escapeNullBytesForParse (null-byte round-trip through the sentinel swap)', () => {
|
||||
test('a NUL byte inside a key survives extractFrontmatter byte-for-byte, including at region offset 1', () => {
|
||||
// Region offset 1 specifically distinguishes the `indexOf(...) === -1` -> `=== +1` mutant:
|
||||
// for THIS input the mutant's condition is true (index really is 1), so it takes the
|
||||
// "no substitution needed" branch and hands js-yaml a raw, unescaped NUL — which js-yaml
|
||||
// rejects outright under every schema, collapsing the whole parse to {}. The same input
|
||||
// also kills the sentinel StringLiteral "" mutant (deletes the byte instead of escaping it):
|
||||
// that mutant would parse successfully but produce key "x" instead of "x ".
|
||||
const NUL = ' ';
|
||||
const doc = `---\nx${NUL}: y\n---\n\nbody\n`;
|
||||
const parsed = extractFrontmatter(doc);
|
||||
assert.ok(
|
||||
Object.prototype.hasOwnProperty.call(parsed, `x${NUL}`),
|
||||
`NUL byte must survive as part of the key, not be dropped or crash the parse; got keys ${JSON.stringify(Object.keys(parsed))}`
|
||||
);
|
||||
assert.equal(parsed[`x${NUL}`], 'y');
|
||||
});
|
||||
});
|
||||
@@ -29,3 +29,12 @@ Categories present:
|
||||
- `huge-bounded.md` — a deliberately-large but bounded frontmatter
|
||||
block (~64KB of array items). Parser must complete in reasonable
|
||||
time with a typed result, not OOM or hang.
|
||||
- `anchor-alias-bomb.md` — a 7-line "billion laughs" frontmatter of
|
||||
nested YAML anchors/aliases. Parser must refuse it (zero keys,
|
||||
`FRONTMATTER_UNPARSEABLE` set) rather than expand it — ADR-3473
|
||||
§8.1 consequence 6.
|
||||
- `anchor-alias-bomb-quoted.md` — the same "billion laughs" bomb, spelled with
|
||||
quoted keys (`"a": &a [...]`) instead of bare keys. Added after #3881
|
||||
review found the original raw-text anchor/alias refusal regex matched only
|
||||
the bare-key line shape and was bypassable by this (and other) spellings.
|
||||
Must refuse identically to `anchor-alias-bomb.md`.
|
||||
|
||||
11
tests/fixtures/adversarial/frontmatter/anchor-alias-bomb-quoted.md
vendored
Normal file
11
tests/fixtures/adversarial/frontmatter/anchor-alias-bomb-quoted.md
vendored
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
"a": &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol"]
|
||||
"b": &b [*a,*a,*a,*a,*a,*a,*a,*a,*a]
|
||||
"c": &c [*b,*b,*b,*b,*b,*b,*b,*b,*b]
|
||||
"d": &d [*c,*c,*c,*c,*c,*c,*c,*c,*c]
|
||||
"e": &e [*d,*d,*d,*d,*d,*d,*d,*d,*d]
|
||||
"f": &f [*e,*e,*e,*e,*e,*e,*e,*e,*e]
|
||||
"g": [*f,*f,*f,*f,*f,*f,*f,*f,*f]
|
||||
---
|
||||
|
||||
Body.
|
||||
11
tests/fixtures/adversarial/frontmatter/anchor-alias-bomb.md
vendored
Normal file
11
tests/fixtures/adversarial/frontmatter/anchor-alias-bomb.md
vendored
Normal file
@@ -0,0 +1,11 @@
|
||||
---
|
||||
a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol"]
|
||||
b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a]
|
||||
c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b]
|
||||
d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c]
|
||||
e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d]
|
||||
f: &f [*e,*e,*e,*e,*e,*e,*e,*e,*e]
|
||||
g: [*f,*f,*f,*f,*f,*f,*f,*f,*f]
|
||||
---
|
||||
|
||||
Body.
|
||||
367
tests/fixtures/golden/frontmatter-legacy-golden.json
vendored
Normal file
367
tests/fixtures/golden/frontmatter-legacy-golden.json
vendored
Normal file
File diff suppressed because one or more lines are too long
202
tests/frontmatter-golden-parity.test.cjs
Normal file
202
tests/frontmatter-golden-parity.test.cjs
Normal file
@@ -0,0 +1,202 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* Golden parity, hermetic (ADR-3473 §8.1, #3881, phase test-matrix §D — redesigned).
|
||||
*
|
||||
* The parser moved from a hand-rolled line scanner to vendored js-yaml. This suite proves
|
||||
* nothing was silently changed by diffing the CURRENT parser's output against a golden
|
||||
* captured from the LEGACY parser, independently of it — but unlike the original design,
|
||||
* every fixture entry carries its OWN literal document text. Nothing here enumerates the
|
||||
* tree, reads a tracked repo path, or shells out to git. That is deliberate:
|
||||
*
|
||||
* The original design keyed ~376 golden entries by tracked repo path (every git-tracked
|
||||
* command file, workflow file, agent file, and doc under the repo's markdown surfaces). This repo
|
||||
* merges roughly 21 commits/day; a 14-day sample measured 937 touches of exactly those
|
||||
* covered files. Any PR that edits one of those files' frontmatter — adding an
|
||||
* `argument-hint`, changing `allowed-tools`, editing a description — changed its parse and
|
||||
* turned this suite red for a change that had nothing to do with the parser. The reflex fix
|
||||
* was "regenerate the golden," which overwrites the very snapshot meant to catch a real
|
||||
* regression — training people to blow away their own regression fixture on every unrelated
|
||||
* touch. It was also a guaranteed merge-conflict magnet: the JSON was one big file every
|
||||
* such PR would need to touch. Excluding `.changeset/**` (a prior, narrower fix) was not
|
||||
* enough — the design itself was wrong.
|
||||
*
|
||||
* This redesign carries no tracked-path dependency at all: each entry stores a stable `id`,
|
||||
* the literal `documentText` (shrunk from a real ddde001af-era corpus document — see
|
||||
* provenance below), and an `expectedParse` captured from the legacy parser. A PR editing
|
||||
* `commands/gsd/help.md` cannot affect this suite. The only thing that can ever conflict
|
||||
* here is two PRs both editing the parser itself.
|
||||
*
|
||||
* Golden provenance (do NOT re-derive `expectedParse` from the current parser — that would
|
||||
* make the comparison circular and prove nothing): `tests/fixtures/golden/
|
||||
* frontmatter-legacy-golden.json` was captured by compiling `src/frontmatter.cts` AS IT
|
||||
* EXISTED AT COMMIT ddde001af (`git show ddde001af:src/frontmatter.cts`) standalone with
|
||||
* tsc, against this repo's sibling support modules (`io.cts`, `shell-command-projection.
|
||||
* cts`, `validate.cts`, `text-lines.cts`, `unusable-input.cts`, `pattern.cts`, `phase-id.
|
||||
* cts`) — all byte-identical between ddde001af and HEAD (`git diff ddde001af..HEAD --stat`
|
||||
* over those paths is empty), so borrowing the current sources of those pure helpers does
|
||||
* not change what the legacy frontmatter parser itself computed. The legacy
|
||||
* `extractFrontmatter` was run once, at capture time, over a representative sample of real
|
||||
* ddde001af-era documents — every document then listed as a known divergence, every
|
||||
* adversarial fixture under `tests/fixtures/adversarial/frontmatter/`, and a sample chosen
|
||||
* for breadth across the distinct YAML shapes present in the corpus (block scalars, inline
|
||||
* arrays, dashed lists, object-lists, nested maps, unicode keys, CRLF, empty values,
|
||||
* comments, multi-doc-looking bodies) — each result was structurally serialized (see
|
||||
* `tests/helpers/frontmatter-golden-serializer.cjs`, D2) and committed alongside the
|
||||
* shrunk document text it was captured from. This is a one-time capture: the compiled
|
||||
* legacy module is not part of this repo and is not re-run by the suite below, which only
|
||||
* ever reads the committed golden.
|
||||
*
|
||||
* Shrinking: most entries store the frontmatter region plus a short stub body rather than a
|
||||
* whole file. Every entry was verified AT CAPTURE TIME that both the current parser and
|
||||
* the legacy parser produce the same structurally-serialized result over the original
|
||||
* full document and the shrunk `documentText` — any candidate where either parser's
|
||||
* output changed under shrinking was dropped rather than stored (0 of 51 candidates were
|
||||
* dropped by this check in this capture; 1 additional file, the adversarial
|
||||
* `unclosed-block.md` fixture, has no closing fence to truncate at and is stored
|
||||
* unshrunk, verbatim).
|
||||
*
|
||||
* Divergences: entries with `diverges: true` are documented, deliberate legacy/current
|
||||
* mismatches — see each entry's `justification`. They are asserted to STILL diverge
|
||||
* (D3), never silently absorbed as a wildcard exemption. Non-diverging entries are
|
||||
* asserted to match `expectedParse` exactly (D1).
|
||||
*/
|
||||
|
||||
const { describe, test } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
|
||||
const { extractFrontmatter } = require('../gsd-core/bin/lib/frontmatter.cjs');
|
||||
const { serializeFrontmatterValue } = require('./helpers/frontmatter-golden-serializer.cjs');
|
||||
|
||||
const GOLDEN_PATH = path.join(__dirname, 'fixtures', 'golden', 'frontmatter-legacy-golden.json');
|
||||
const golden = JSON.parse(fs.readFileSync(GOLDEN_PATH, 'utf8'));
|
||||
const ENTRIES = golden.entries;
|
||||
|
||||
/** Serialized current-parser output for one entry's embedded document text. */
|
||||
function currentSerialized(entry) {
|
||||
return serializeFrontmatterValue(extractFrontmatter(entry.documentText));
|
||||
}
|
||||
|
||||
describe('frontmatter golden parity, hermetic (ADR-3473 §8.1, #3881, §D)', () => {
|
||||
test('fixture sanity: entries are present and every id is unique', () => {
|
||||
assert.ok(Array.isArray(ENTRIES) && ENTRIES.length > 0, 'expected at least one golden entry');
|
||||
const ids = ENTRIES.map((e) => e.id);
|
||||
assert.equal(new Set(ids).size, ids.length, 'duplicate entry id(s) in the golden fixture');
|
||||
console.log(`frontmatter-golden-parity: ${ENTRIES.length} hermetic golden entries`);
|
||||
});
|
||||
|
||||
test('D1: every non-diverging entry matches its legacy-parser expectedParse exactly', () => {
|
||||
const failures = [];
|
||||
for (const entry of ENTRIES) {
|
||||
if (entry.diverges) continue;
|
||||
const actual = currentSerialized(entry);
|
||||
if (actual !== entry.expectedParse) {
|
||||
failures.push({ id: entry.id, expected: entry.expectedParse, actual });
|
||||
}
|
||||
}
|
||||
assert.deepEqual(
|
||||
failures,
|
||||
[],
|
||||
'undocumented parity divergence(s) — either the parser silently changed behavior, or '
|
||||
+ `this is a deliberate divergence that must be marked diverges:true with a justification: ${JSON.stringify(failures, null, 2)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test('D1 sensor: the parity check is not vacuous — a mutated expectedParse is caught', () => {
|
||||
const rel = ENTRIES.find((e) => !e.diverges);
|
||||
assert.ok(rel, 'expected at least one non-diverging entry to sensor-check against');
|
||||
const actual = currentSerialized(rel);
|
||||
const mutated = `${rel.expectedParse}__MUTATED__`;
|
||||
assert.notEqual(
|
||||
actual,
|
||||
mutated,
|
||||
'sensor failed: a mutated expectedParse must not equal the real parser output',
|
||||
);
|
||||
});
|
||||
|
||||
test('D3: every diverging entry actually diverges from its expectedParse today', () => {
|
||||
const stillMatching = [];
|
||||
for (const entry of ENTRIES) {
|
||||
if (!entry.diverges) continue;
|
||||
const actual = currentSerialized(entry);
|
||||
if (actual === entry.expectedParse) stillMatching.push(entry.id);
|
||||
}
|
||||
assert.deepEqual(
|
||||
stillMatching,
|
||||
[],
|
||||
'entries marked diverges:true that no longer diverge must have diverges FLIPPED TO '
|
||||
+ `false (it must never become a wildcard exemption): ${JSON.stringify(stillMatching)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test('D3: every diverging entry carries a non-empty justification', () => {
|
||||
for (const entry of ENTRIES) {
|
||||
if (!entry.diverges) continue;
|
||||
assert.ok(
|
||||
typeof entry.justification === 'string' && entry.justification.trim().length > 0,
|
||||
`${entry.id} is marked diverges:true but has no justification`,
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
test('hermeticity: fixture entries carry no filesystem path operands', () => {
|
||||
// sourcePath is provenance-only metadata (never read at test time) — everything else on
|
||||
// an entry must be inert data, not something that could be mistaken for a live path
|
||||
// lookup.
|
||||
for (const entry of ENTRIES) {
|
||||
assert.equal(typeof entry.documentText, 'string');
|
||||
assert.equal(typeof entry.expectedParse, 'string');
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('frontmatter golden serializer protects the gate itself (ADR-3473 §8.1, #3881, §D2)', () => {
|
||||
test('D2: JSON.stringify silently drops a named property on an Array', () => {
|
||||
// Reproduce the exact legacy shape: `k:\n - test: a\n other: b` parses to an
|
||||
// array whose element 0 is "test: a" and which ALSO carries `.other === "b"`.
|
||||
const namedArray = ['test: a'];
|
||||
namedArray.other = 'b';
|
||||
|
||||
assert.equal(
|
||||
JSON.stringify(namedArray),
|
||||
'["test: a"]',
|
||||
'JSON.stringify must (still) silently drop the named array property — this pins the '
|
||||
+ 'exact defect a JSON-based golden would have',
|
||||
);
|
||||
});
|
||||
|
||||
test('D2: the structural serializer distinguishes a plain array from the same array carrying a named property', () => {
|
||||
const plainArray = ['test: a'];
|
||||
const namedArray = ['test: a'];
|
||||
namedArray.other = 'b';
|
||||
|
||||
const plainSerialized = serializeFrontmatterValue(plainArray);
|
||||
const namedSerialized = serializeFrontmatterValue(namedArray);
|
||||
|
||||
assert.notEqual(
|
||||
plainSerialized,
|
||||
namedSerialized,
|
||||
'the serializer must distinguish ["test: a"] from the same array carrying .other = "b"',
|
||||
);
|
||||
assert.ok(
|
||||
namedSerialized.includes('"other"') && namedSerialized.includes('"b"'),
|
||||
`named-property serialization must surface the property and its value; got: ${namedSerialized}`,
|
||||
);
|
||||
// And it must not have been captured by dropping straight to JSON.stringify.
|
||||
assert.notEqual(namedSerialized, JSON.stringify(namedArray));
|
||||
});
|
||||
|
||||
test('D2: the named-array-property shape is real, not hypothetical — it appears in the captured golden', () => {
|
||||
// gsd-core__templates__summary-complex's `requires` entry is captured golden proof this
|
||||
// shape occurs on a real, tracked document (verified live against the legacy parser
|
||||
// while writing this suite): its expectedParse must carry a named-property tail.
|
||||
const entry = ENTRIES.find((e) => e.id === 'gsd-core__templates__summary-complex');
|
||||
assert.ok(entry, 'expected the summary-complex divergence entry in the golden set');
|
||||
assert.ok(
|
||||
/"requires":\["[^"]*"\]\{"provides":/.test(entry.expectedParse),
|
||||
`expected the expectedParse for ${entry.id} to carry a named-property tail on 'requires'; got: ${entry.expectedParse}`,
|
||||
);
|
||||
});
|
||||
});
|
||||
156
tests/frontmatter-roundtrip.property.test.cjs
Normal file
156
tests/frontmatter-roundtrip.property.test.cjs
Normal file
@@ -0,0 +1,156 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* ADR-3473 §8.1's mandated gate (#3881, phase test-matrix §E): "a property-based
|
||||
* `fast-check` round-trip test is the gate."
|
||||
*
|
||||
* E1: parse(serialize(x)) === parse(serialize(parse(serialize(x)))) — idempotence after
|
||||
* one round-trip cycle, the invariant #3349 violated (a value that changed shape on
|
||||
* a SECOND write, even though the first write looked fine).
|
||||
* E2: the #3257 full-line-comment channel survives a parse -> reconstruct -> re-parse ->
|
||||
* reconstruct cycle intact and in place.
|
||||
*
|
||||
* `serialize` = reconstructFrontmatter (object -> YAML body text, no `---` delimiters).
|
||||
* `parse` = extractFrontmatter (delimited document text -> object), applied to the body
|
||||
* wrapped back in `---` fences the way every real caller round-trips it.
|
||||
*
|
||||
* fast-check v4 in this repo: no `fc.stringOf`; arbitraries live at module scope (never
|
||||
* built inside a `describe` body) — see tests/frontmatter.property.test.cjs for the
|
||||
* established pattern this file follows.
|
||||
*/
|
||||
|
||||
const { describe, test } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const fc = require('./helpers/fast-check-setup.cjs');
|
||||
|
||||
const { extractFrontmatter, reconstructFrontmatter } = require('../gsd-core/bin/lib/frontmatter.cjs');
|
||||
|
||||
// ─── Arbitraries — realistic key/value shapes, not free-form noise ────────────────────
|
||||
|
||||
// A real top-level frontmatter key: lower-kebab/snake identifiers as seen across the
|
||||
// corpus (phase, key-decisions, tech-stack, human_verification, ...).
|
||||
const realisticKey = fc.stringMatching(/^[a-z][a-z0-9_-]{0,19}$/);
|
||||
|
||||
// A plain scalar value shaped like real frontmatter content: printable, no raw control
|
||||
// chars, no YAML-significant leading/trailing whitespace of its own (reconstructFrontmatter
|
||||
// is exercised elsewhere, in tests/frontmatter.property.test.cjs, for the quoting/escaping
|
||||
// contract itself — this file is about ROUND-TRIP IDENTITY, so values are drawn from the
|
||||
// well-formed subset rather than re-testing escaping).
|
||||
const realisticScalar = fc.stringMatching(/^[A-Za-z0-9][A-Za-z0-9 ._/:-]{0,60}$/);
|
||||
|
||||
// A short list of realistic scalars, the shape `tags:`/`requires:`/`key-decisions:` use.
|
||||
const realisticList = fc.array(realisticScalar, { minLength: 0, maxLength: 5 });
|
||||
|
||||
// One frontmatter object: a flat dictionary whose values are either a scalar or a list of
|
||||
// scalars — the two value shapes reconstructFrontmatter's top-level branch documents.
|
||||
const frontmatterObject = fc.dictionary(
|
||||
realisticKey,
|
||||
fc.oneof(realisticScalar, realisticList),
|
||||
{ minKeys: 1, maxKeys: 8 },
|
||||
);
|
||||
|
||||
/** serialize -> wrap in fences -> parse, the shape every real caller round-trips through. */
|
||||
function roundTripParse(obj) {
|
||||
const body = reconstructFrontmatter(obj);
|
||||
return extractFrontmatter(`---\n${body}\n---\n`);
|
||||
}
|
||||
|
||||
describe('frontmatter round-trip idempotence — ADR-3473 §8.1 mandated gate (#3881, §E1)', () => {
|
||||
test('property: parse(serialize(x)) is a fixed point of one more round-trip cycle', () => {
|
||||
fc.assert(
|
||||
fc.property(frontmatterObject, (x) => {
|
||||
const once = roundTripParse(x);
|
||||
const twice = roundTripParse(once);
|
||||
assert.deepEqual(
|
||||
twice,
|
||||
once,
|
||||
`round-trip is not idempotent for ${JSON.stringify(x)}: once=${JSON.stringify(once)} twice=${JSON.stringify(twice)}`,
|
||||
);
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('property: a single round-trip preserves every key and its scalar/list shape', () => {
|
||||
fc.assert(
|
||||
fc.property(frontmatterObject, (x) => {
|
||||
const once = roundTripParse(x);
|
||||
for (const [key, value] of Object.entries(x)) {
|
||||
assert.ok(key in once, `key ${key} lost on round-trip`);
|
||||
if (Array.isArray(value)) {
|
||||
assert.ok(Array.isArray(once[key]), `key ${key} lost its list shape on round-trip`);
|
||||
} else {
|
||||
assert.equal(typeof once[key], 'string', `key ${key} lost its scalar shape on round-trip`);
|
||||
}
|
||||
}
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('sensor: the idempotence check is not vacuous — a mutated second pass is caught', () => {
|
||||
// Prove the deepEqual comparison above can actually fail: fabricate a "second pass"
|
||||
// that differs from the first and confirm the property-style check rejects it.
|
||||
const once = roundTripParse({ phase: 'p1', tags: ['a', 'b'] });
|
||||
const mutatedTwice = { ...once, phase: `${once.phase}__MUTATED__` };
|
||||
assert.notDeepEqual(mutatedTwice, once, 'sensor failed: a mutated second pass must not equal the first');
|
||||
});
|
||||
});
|
||||
|
||||
describe('frontmatter round-trip preserves the #3257 comment channel (#3881, §E2)', () => {
|
||||
// A column-0 `# text` comment line, restricted to characters that cannot themselves be
|
||||
// mistaken for the next key line by extractCommentChannel's own matcher.
|
||||
const commentText = fc.stringMatching(/^# [A-Za-z0-9 .,'-]{1,40}$/);
|
||||
|
||||
test('property: a leading comment above a generated key survives a full round-trip cycle', () => {
|
||||
fc.assert(
|
||||
fc.property(realisticKey, realisticScalar, commentText, (key, value, comment) => {
|
||||
const doc = `---\n${comment}\n${key}: ${JSON.stringify(value)}\n---\n`;
|
||||
const extracted = extractFrontmatter(doc);
|
||||
assert.equal(extracted[key], value, 'sanity: the key itself must parse before testing comment survival');
|
||||
|
||||
const reconstructed = reconstructFrontmatter(extracted);
|
||||
assert.ok(
|
||||
reconstructed.includes(comment),
|
||||
`comment lost on first round-trip: ${JSON.stringify(reconstructed)}`,
|
||||
);
|
||||
|
||||
// Full cycle: re-parse the reconstructed doc and reconstruct again — the comment
|
||||
// must still be attached to the same key, not merely present anywhere.
|
||||
const reExtracted = extractFrontmatter(`---\n${reconstructed}\n---\n`);
|
||||
const reReconstructed = reconstructFrontmatter(reExtracted);
|
||||
assert.ok(
|
||||
reReconstructed.includes(comment),
|
||||
`comment lost on second round-trip cycle: ${JSON.stringify(reReconstructed)}`,
|
||||
);
|
||||
// The comment must still immediately precede its key (attached, not orphaned).
|
||||
const idx = reReconstructed.indexOf(comment);
|
||||
const keyIdx = reReconstructed.indexOf(`${key}:`);
|
||||
assert.ok(keyIdx > idx, `comment did not stay attached ahead of its key: ${JSON.stringify(reReconstructed)}`);
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('property: a trailing comment after the last key survives a full round-trip cycle', () => {
|
||||
fc.assert(
|
||||
fc.property(realisticKey, realisticScalar, commentText, (key, value, comment) => {
|
||||
const doc = `---\n${key}: ${JSON.stringify(value)}\n${comment}\n---\n`;
|
||||
const extracted = extractFrontmatter(doc);
|
||||
const reconstructed = reconstructFrontmatter(extracted);
|
||||
assert.ok(reconstructed.includes(comment), `trailing comment lost: ${JSON.stringify(reconstructed)}`);
|
||||
|
||||
const reExtracted = extractFrontmatter(`---\n${reconstructed}\n---\n`);
|
||||
const reReconstructed = reconstructFrontmatter(reExtracted);
|
||||
assert.ok(
|
||||
reReconstructed.includes(comment),
|
||||
`trailing comment lost on second cycle: ${JSON.stringify(reReconstructed)}`,
|
||||
);
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
test('sensor: comment-channel preservation is not vacuous — a document with no comment carries none forward', () => {
|
||||
const doc = '---\nkey: value\n---\n';
|
||||
const extracted = extractFrontmatter(doc);
|
||||
const reconstructed = reconstructFrontmatter(extracted);
|
||||
assert.ok(!reconstructed.includes('#'), `expected no comment to appear from nowhere: ${JSON.stringify(reconstructed)}`);
|
||||
});
|
||||
});
|
||||
@@ -1743,11 +1743,11 @@ describe('feat-3594: frontmatter parser preserves Unicode round-trip', () => {
|
||||
const content = loadFixture('unicode-keys-and-values.md');
|
||||
const fm = extractFrontmatter(content);
|
||||
assert.equal(fm.title, '日本語のタイトル');
|
||||
// The parser's key regex is /^(\s*)([a-zA-Z0-9_-]+):.../ so non-ASCII
|
||||
// keys (like `相:`) won't be captured. Pin that current behavior so
|
||||
// a future broadening to allow Unicode keys is visible (and so the
|
||||
// ASCII-only contract is asserted, not silently relied on).
|
||||
assert.equal(fm['相'], undefined, 'parser currently only recognizes ASCII keys (regression guard)');
|
||||
// ADR-3473 §8.1: the vendored js-yaml parser has no ASCII-only key
|
||||
// regex — non-ASCII keys (like `相:`) are recognized like any other
|
||||
// YAML key. Pin the broadened behavior so a future regression back to
|
||||
// ASCII-only keys is visible.
|
||||
assert.equal(fm['相'], '04', 'parser must recognize non-ASCII keys (js-yaml has no ASCII-only key regex)');
|
||||
// The status field has an emoji — must survive.
|
||||
assert.equal(fm.status, '🚧 in-flight');
|
||||
// Inline array with Greek letters.
|
||||
@@ -2773,3 +2773,160 @@ describe('extractFrontmatter BOM tolerance (#2977)', () => {
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Post-#3881-review findings 3 and 4 (ADR-3473 §8.1) — prototype-chain-safe
|
||||
// bracket reads/writes, and byte-vs-equivalence stability of the escaper.
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
{
|
||||
const { describe, test } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const { extractFrontmatter, reconstructFrontmatter, escapeDoubleQuotedScalar } = require('../gsd-core/bin/lib/frontmatter.cjs');
|
||||
|
||||
describe('#3881 review finding 3: prototype-chain keys never crash extract/reconstruct', () => {
|
||||
const hostileKeys = ['constructor', '__proto__', 'toString', 'valueOf', 'hasOwnProperty'];
|
||||
|
||||
for (const key of hostileKeys) {
|
||||
test(`a column-0-commented key named "${key}" round-trips without throwing`, () => {
|
||||
const yaml = `---\n# comment for ${key}\n${key}: val-${key}\nz: control\n---\n`;
|
||||
let fm;
|
||||
assert.doesNotThrow(() => { fm = extractFrontmatter(yaml); }, `extractFrontmatter must not throw on key "${key}"`);
|
||||
assert.strictEqual(fm[key], `val-${key}`, `key "${key}" must parse as its own value, not an inherited Object.prototype member`);
|
||||
assert.strictEqual(fm.z, 'control');
|
||||
|
||||
let reconstructed;
|
||||
assert.doesNotThrow(() => { reconstructed = reconstructFrontmatter(fm); }, `reconstructFrontmatter must not throw on key "${key}"`);
|
||||
assert.ok(reconstructed.includes(`# comment for ${key}`), `comment above "${key}" must survive reconstruct`);
|
||||
assert.ok(reconstructed.includes(`${key}: val-${key}`), `key "${key}" must survive reconstruct`);
|
||||
|
||||
const roundtrip = extractFrontmatter(`---\n${reconstructed}\n---\n`);
|
||||
assert.strictEqual(roundtrip[key], `val-${key}`, `key "${key}" must survive a full round-trip`);
|
||||
});
|
||||
}
|
||||
|
||||
test('all five hostile keys together in one document, each with its own comment', () => {
|
||||
let yaml = '---\n';
|
||||
for (const k of hostileKeys) yaml += `# leading comment for ${k}\n${k}: v-${k}\n`;
|
||||
yaml += '---\n';
|
||||
const fm = extractFrontmatter(yaml);
|
||||
for (const k of hostileKeys) assert.strictEqual(fm[k], `v-${k}`);
|
||||
const reconstructed = reconstructFrontmatter(fm);
|
||||
const roundtrip = extractFrontmatter(`---\n${reconstructed}\n---\n`);
|
||||
for (const k of hostileKeys) {
|
||||
assert.ok(reconstructed.includes(`# leading comment for ${k}`), `comment for ${k} lost`);
|
||||
assert.strictEqual(roundtrip[k], `v-${k}`, `${k} lost on round-trip`);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('#3881 review finding 4: escapeDoubleQuotedScalar pins named-escape output, and equivalence-preserving round-trip', () => {
|
||||
// Exact escaped-form pins: js-yaml's dump emits the YAML-named escape for each of these,
|
||||
// not the old hand-rolled chain's hex/raw-literal form. Pinning both the exact escape AND
|
||||
// the round-trip proves the new form is not merely "different" but semantically correct.
|
||||
const cases = [
|
||||
{ label: 'BEL', ch: '\x07', escaped: '\\a' },
|
||||
{ label: 'NUL', ch: '\x00', escaped: '\\0' },
|
||||
{ label: 'NEL', ch: '\x85', escaped: '\\N' },
|
||||
{ label: 'NBSP', ch: ' ', escaped: '\\_' },
|
||||
{ label: 'LINE SEPARATOR', ch: '
', escaped: '\\L' },
|
||||
{ label: 'PARAGRAPH SEPARATOR', ch: '
', escaped: '\\P' },
|
||||
{ label: 'BOM', ch: '', escaped: '\\uFEFF' },
|
||||
{ label: 'lone high surrogate', ch: '\uD800', escaped: '\\uD800' },
|
||||
];
|
||||
|
||||
for (const { label, ch, escaped } of cases) {
|
||||
test(`${label} (U+${ch.charCodeAt(0).toString(16).toUpperCase().padStart(4, '0')}) escapes to the exact pinned form and round-trips`, () => {
|
||||
assert.strictEqual(escapeDoubleQuotedScalar(ch), escaped, `${label} must escape to ${JSON.stringify(escaped)}`);
|
||||
|
||||
const reconstructed = reconstructFrontmatter({ weird: ch });
|
||||
let roundtrip;
|
||||
assert.doesNotThrow(() => { roundtrip = extractFrontmatter(`---\n${reconstructed}\n---\n`); },
|
||||
`${label} must produce re-parseable YAML, not silently collapse to unparseable`);
|
||||
assert.strictEqual(roundtrip.weird, ch, `${label} must round-trip to the exact same codepoint`);
|
||||
});
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Post-#3881-review finding 6: relocated from a standalone
|
||||
// tests/feat-3594-parser-adversarial-frontmatter.test.cjs, created earlier on this branch
|
||||
// under the false premise that no test owned the adversarial fixture corpus (it was already
|
||||
// folded here by consolidation epic #1969, describe block 'folded:feat-3594-parser-
|
||||
// adversarial-frontmatter' above). Folded rather than left standalone, per that epic's
|
||||
// precedent — the genuinely NEW coverage this file added (fixture-ownership check, the
|
||||
// anchor-alias-bomb fixtures, and the B1/B2 block-scalar rows) is preserved below; its
|
||||
// duplicate-of-already-folded assertions (duplicate-keys/crlf/unclosed/null-byte/huge-bounded/
|
||||
// unicode) are not re-added a third time.
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
{
|
||||
const { test, describe: __foldDescribe2 } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
const { extractFrontmatter, FRONTMATTER_UNPARSEABLE } = require('../gsd-core/bin/lib/frontmatter.cjs');
|
||||
|
||||
const FIXTURE_DIR2 = path.join(__dirname, 'fixtures', 'adversarial', 'frontmatter');
|
||||
function readFixture2(name) {
|
||||
return fs.readFileSync(path.join(FIXTURE_DIR2, name), 'utf8');
|
||||
}
|
||||
|
||||
__foldDescribe2('folded:feat-3594-fixture-ownership-and-block-scalar (relocated, #3881 review finding 6)', () => {
|
||||
// Table-driven ownership: every fixture file present on disk (excluding README.md, which
|
||||
// is documentation, not a fixture) must be exercised by at least one test in this file's
|
||||
// adversarial-frontmatter describe blocks (this one, or the earlier folded one above).
|
||||
// OWNED_ELSEWHERE lists fixtures the earlier fold already covers so this check does not
|
||||
// demand a third copy of the same assertions.
|
||||
const OWNED_ELSEWHERE = new Set([
|
||||
'duplicate-keys.md',
|
||||
'crlf-mixed.md',
|
||||
'unclosed-block.md',
|
||||
'unicode-keys-and-values.md',
|
||||
'null-byte-value.md',
|
||||
'huge-bounded.md',
|
||||
]);
|
||||
|
||||
test('every fixture on disk not already owned by the earlier fold has a matrix entry here', () => {
|
||||
const onDisk = fs
|
||||
.readdirSync(FIXTURE_DIR2)
|
||||
.filter((name) => name.endsWith('.md') && name !== 'README.md')
|
||||
.sort();
|
||||
const registeredHere = ['anchor-alias-bomb.md', 'anchor-alias-bomb-quoted.md'];
|
||||
const unowned = onDisk.filter((name) => !OWNED_ELSEWHERE.has(name) && !registeredHere.includes(name));
|
||||
assert.deepEqual(unowned, [], `fixture(s) present on disk with no owning test anywhere: ${unowned.join(', ')}`);
|
||||
});
|
||||
|
||||
test('anchor-alias-bomb.md: refused rather than expanded (ADR-3473 §8.1 consequence 6, row A8)', () => {
|
||||
const parsed = extractFrontmatter(readFixture2('anchor-alias-bomb.md'), 'anchor-alias-bomb.md');
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
assert.ok(Buffer.byteLength(JSON.stringify(parsed), 'utf8') < 1024);
|
||||
});
|
||||
|
||||
test('anchor-alias-bomb-quoted.md: refused identically, even quoted-key-spelled (#3881 review, finding 1)', () => {
|
||||
const parsed = extractFrontmatter(readFixture2('anchor-alias-bomb-quoted.md'), 'anchor-alias-bomb-quoted.md');
|
||||
assert.equal(Object.keys(parsed).length, 0);
|
||||
assert.equal(parsed[FRONTMATTER_UNPARSEABLE], true);
|
||||
assert.ok(Buffer.byteLength(JSON.stringify(parsed), 'utf8') < 1024);
|
||||
});
|
||||
|
||||
const ADD_TESTS_PATH = path.join(__dirname, '..', 'commands', 'gsd', 'add-tests.md');
|
||||
|
||||
test('B1 blockScalarValueIsNotTheBlockIndicator: argument-instructions is the instruction text, not "|"', () => {
|
||||
const content = fs.readFileSync(ADD_TESTS_PATH, 'utf8');
|
||||
const parsed = extractFrontmatter(content, ADD_TESTS_PATH);
|
||||
const value = parsed['argument-instructions'];
|
||||
assert.equal(typeof value, 'string');
|
||||
assert.notEqual(value, '|');
|
||||
assert.ok(value.length > 1, 'block scalar value must be the multi-line instruction body');
|
||||
assert.ok(value.includes('Parse the argument as a phase number'), 'block scalar value must retain the source instruction text');
|
||||
});
|
||||
|
||||
test('B2 blockScalarDoesNotInventATopLevelKey: parsing add-tests.md produces no phantom "Example" key', () => {
|
||||
const content = fs.readFileSync(ADD_TESTS_PATH, 'utf8');
|
||||
const parsed = extractFrontmatter(content, ADD_TESTS_PATH);
|
||||
assert.ok(!Object.prototype.hasOwnProperty.call(parsed, 'Example'), 'parser must not scrape a top-level "Example" key out of the block scalar body');
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
@@ -26,7 +26,7 @@ const {
|
||||
parseMustHavesBlock,
|
||||
FRONTMATTER_SCHEMAS,
|
||||
agentScalarNeedsDoubleQuoting,
|
||||
escapeDoubleQuoted,
|
||||
escapeDoubleQuotedScalar,
|
||||
} = require('../gsd-core/bin/lib/frontmatter.cjs');
|
||||
|
||||
// ─── extractFrontmatter ───────────────────────────────────────────────────────
|
||||
@@ -211,21 +211,13 @@ describe('extractFrontmatter: inline arrays', () => {
|
||||
assert.deepEqual(result, { tags: ['a, b', 'c', 'd'] });
|
||||
});
|
||||
|
||||
test('consecutive commas (empty items filtered)', () => {
|
||||
const result = extractFrontmatter('---\ntags: [a,,b]\n---');
|
||||
assert.deepEqual(result, { tags: ['a', 'b'] });
|
||||
});
|
||||
|
||||
test('whitespace-only items filtered', () => {
|
||||
const result = extractFrontmatter('---\ntags: [ , ]\n---');
|
||||
assert.deepEqual(result, { tags: [] });
|
||||
});
|
||||
|
||||
test('opening bracket only becomes empty array/object', () => {
|
||||
const result = extractFrontmatter('---\ntags: [\n---');
|
||||
assert.deepEqual(result, { tags: [] });
|
||||
assert.ok(Array.isArray(result.tags));
|
||||
});
|
||||
// `repairMalformedInlineArrays` (and its `splitLegacyInlineArrayItems` helper), which these
|
||||
// three cases pinned, was deleted (#3881 follow-up): a sweep of every tracked `*.md` file with
|
||||
// a frontmatter fence (910 files) found ZERO documents whose parse result changed with the
|
||||
// repair disabled. A real YAML flow sequence has none of this leniency — `[a,,b]` is an empty
|
||||
// flow-sequence-entry syntax error, `[ , ]` is the same, and an unclosed `[` is an unterminated
|
||||
// collection — so `extractFrontmatter` now correctly reports these as unparseable
|
||||
// (`FRONTMATTER_UNPARSEABLE`) instead of silently repairing them.
|
||||
});
|
||||
|
||||
describe('extractFrontmatter: dashed list arrays', () => {
|
||||
@@ -250,10 +242,12 @@ describe('extractFrontmatter: dashed list arrays', () => {
|
||||
assert.deepEqual(result, { tags: ['single quoted'] });
|
||||
});
|
||||
|
||||
test('opening bracket followed by dashed list', () => {
|
||||
const result = extractFrontmatter('---\ntags: [\n - a\n - b\n---');
|
||||
assert.deepEqual(result, { tags: ['a', 'b'] });
|
||||
});
|
||||
// `repairMalformedInlineArrays`'s "bare unclosed `key: [` followed by a block-sequence"
|
||||
// recovery, which this case pinned, was deleted alongside the rest of that function (#3881
|
||||
// follow-up; see the note above `extractFrontmatter: inline arrays`) — zero tracked documents
|
||||
// depended on it. A literal `[` with no closing bracket is an unterminated YAML flow
|
||||
// collection; `extractFrontmatter` now reports it as unparseable rather than silently
|
||||
// reinterpreting it as a block-sequence opener.
|
||||
});
|
||||
|
||||
describe('extractFrontmatter: empty / missing values', () => {
|
||||
@@ -1256,8 +1250,8 @@ describe('reconstructFrontmatter: strict-YAML round-trip (#1779)', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// #3497 — escape amplification. `escapeDoubleQuoted` escapes `\`/`"`/control
|
||||
// chars on every serialize (#1779), but `parseYamlRegion` only stripped the
|
||||
// #3497 — escape amplification. `escapeDoubleQuotedScalar` escapes `\`/`"`/control
|
||||
// chars on every serialize (#1779), but `parseGuardedYamlRegion` only stripped the
|
||||
// outer quote delimiters and never un-escaped the interior, so parse ∘ serialize
|
||||
// was NOT the identity: every read-modify-write cycle doubled the backslashes
|
||||
// (b → 2b+1, i.e. 2ⁿ−1 after n round-trips). A `last_activity_desc` containing
|
||||
@@ -1699,9 +1693,9 @@ describe('agentScalarNeedsDoubleQuoting: real-world values that must stay unquot
|
||||
}
|
||||
});
|
||||
|
||||
// ─── escapeDoubleQuoted (#1779 / #3497) ────────────────────────────────────────
|
||||
// ─── escapeDoubleQuotedScalar (#1779 / #3497) ────────────────────────────────────────
|
||||
|
||||
describe('escapeDoubleQuoted: exact output strings', () => {
|
||||
describe('escapeDoubleQuotedScalar: exact output strings', () => {
|
||||
test('backslash is escaped before the quote it precedes (ordering matters)', () => {
|
||||
// Input: a, \, ", b. If the quote were escaped BEFORE the backslash, the
|
||||
// backslash added in front of the quote would then itself get doubled by
|
||||
@@ -1710,40 +1704,40 @@ describe('escapeDoubleQuoted: exact output strings', () => {
|
||||
// followed by the quote.
|
||||
const input = 'a' + '\\' + '"' + 'b';
|
||||
const expected = 'a' + '\\'.repeat(3) + '"' + 'b';
|
||||
assert.equal(escapeDoubleQuoted(input), expected);
|
||||
assert.equal(escapeDoubleQuotedScalar(input), expected);
|
||||
});
|
||||
|
||||
test('double quote alone', () => {
|
||||
assert.equal(escapeDoubleQuoted('"'), '\\"');
|
||||
assert.equal(escapeDoubleQuotedScalar('"'), '\\"');
|
||||
});
|
||||
|
||||
test('newline alone', () => {
|
||||
assert.equal(escapeDoubleQuoted('\n'), '\\n');
|
||||
assert.equal(escapeDoubleQuotedScalar('\n'), '\\n');
|
||||
});
|
||||
|
||||
test('tab alone', () => {
|
||||
assert.equal(escapeDoubleQuoted('\t'), '\\t');
|
||||
assert.equal(escapeDoubleQuotedScalar('\t'), '\\t');
|
||||
});
|
||||
|
||||
test('carriage return alone', () => {
|
||||
assert.equal(escapeDoubleQuoted('\r'), '\\r');
|
||||
assert.equal(escapeDoubleQuotedScalar('\r'), '\\r');
|
||||
});
|
||||
|
||||
test('a C0 control char (0x01) becomes lowercase zero-padded \\xHH', () => {
|
||||
assert.equal(escapeDoubleQuoted('\u0001'), '\\x01');
|
||||
assert.equal(escapeDoubleQuotedScalar('\u0001'), '\\x01');
|
||||
});
|
||||
|
||||
test('DEL (0x7f) becomes \\x7f', () => {
|
||||
assert.equal(escapeDoubleQuoted('\u007f'), '\\x7f');
|
||||
assert.equal(escapeDoubleQuotedScalar('\u007f'), '\\x7f');
|
||||
});
|
||||
|
||||
test('plain string with no specials is returned unchanged', () => {
|
||||
assert.equal(escapeDoubleQuoted('plain'), 'plain');
|
||||
assert.equal(escapeDoubleQuotedScalar('plain'), 'plain');
|
||||
});
|
||||
|
||||
test('combined input exercising every escape in one pass', () => {
|
||||
const input = 'a\\b"c\nd\te\rf\u0001g\u007fh';
|
||||
const expected = 'a\\\\b\\"c\\nd\\te\\rf\\x01g\\x7fh';
|
||||
assert.equal(escapeDoubleQuoted(input), expected);
|
||||
assert.equal(escapeDoubleQuotedScalar(input), expected);
|
||||
});
|
||||
});
|
||||
|
||||
54
tests/helpers/frontmatter-golden-serializer.cjs
Normal file
54
tests/helpers/frontmatter-golden-serializer.cjs
Normal file
@@ -0,0 +1,54 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* Structural serializer for the frontmatter golden-parity gate (ADR-3473 §8.1, #3881, row D2).
|
||||
*
|
||||
* The legacy line-scanner parser can return an Array carrying a NAMED own-enumerable
|
||||
* property alongside its indexed elements — e.g. `k:\n - test: a\n other: b` yields
|
||||
* an array whose `Object.keys()` is `["0","other"]` (index "0" holds `"test: a"`, and
|
||||
* `"other"` holds `"b"` as a non-index property). `JSON.stringify` silently drops any
|
||||
* non-index own property of an array, so a JSON-based golden would compare only the
|
||||
* `["test: a"]` shape and never notice `.other` — a parity gate that cannot see the exact
|
||||
* shape it exists to protect (#3427's failure mode, reproduced inside the gate meant to
|
||||
* prevent it: see D2 in tests/frontmatter-golden-parity.test.cjs).
|
||||
*
|
||||
* This serializer instead walks every own enumerable property (`Object.keys`, which
|
||||
* includes non-index array properties) and folds arrays into a `[items]{named}` form so
|
||||
* the named-property tail is always represented in the output string. Symbol-keyed
|
||||
* properties (e.g. the #3257 comment channel, the unparseable marker) are deliberately
|
||||
* excluded: Object.keys never returns them, so they were already invisible to the legacy
|
||||
* line-scanner's output shape this golden pins.
|
||||
*
|
||||
* CORRECTED (post-#3881-review, finding 7): object keys were previously SORTED here,
|
||||
* "for determinism" — but ADR-3473 §8.1's stated contract is key-ORDER parity between the
|
||||
* legacy scanner and js-yaml, and a sorted serialization cannot see a key-order regression:
|
||||
* two objects with the SAME keys in DIFFERENT orders serialize identically once sorted, so
|
||||
* D1 was structurally blind to the exact invariant the ADR names. `Object.keys` already
|
||||
* returns string keys in a well-defined, deterministic order (insertion order, with the
|
||||
* usual integer-index-first carve-out that does not apply to frontmatter's non-numeric
|
||||
* keys) — sorting was never needed for determinism, only for (accidentally) hiding order.
|
||||
* Now order-preserving: `Object.keys(value)` is used as-is, for both objects and an
|
||||
* array's named (non-index) properties.
|
||||
*/
|
||||
function serializeFrontmatterValue(value) {
|
||||
if (value === null) return 'null';
|
||||
if (value === undefined) return 'undefined';
|
||||
if (Array.isArray(value)) {
|
||||
const items = value.map((item) => serializeFrontmatterValue(item));
|
||||
const namedKeys = Object.keys(value).filter((k) => !/^\d+$/.test(k));
|
||||
let out = `[${items.join(',')}]`;
|
||||
if (namedKeys.length) {
|
||||
out += `{${namedKeys
|
||||
.map((k) => `${JSON.stringify(k)}:${serializeFrontmatterValue(value[k])}`)
|
||||
.join(',')}}`;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
if (typeof value === 'object') {
|
||||
const keys = Object.keys(value);
|
||||
return `{${keys.map((k) => `${JSON.stringify(k)}:${serializeFrontmatterValue(value[k])}`).join(',')}}`;
|
||||
}
|
||||
return JSON.stringify(value);
|
||||
}
|
||||
|
||||
module.exports = { serializeFrontmatterValue };
|
||||
270
tests/lint-vendored-deps-manifest.test.cjs
Normal file
270
tests/lint-vendored-deps-manifest.test.cjs
Normal file
@@ -0,0 +1,270 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* ADR-3473 §8.1 (#3881, phase test-matrix §G — packaging).
|
||||
*
|
||||
* scripts/lint-vendored-deps.cjs used to be a single hand-rolled check hardcoded to
|
||||
* `re2js`; #3881 generalized it to a table-driven VENDORED manifest so adding js-yaml did
|
||||
* not need a second hardcoded block. This suite pins:
|
||||
* G1 the js-yaml row's byte-compare actually matches node_modules today.
|
||||
* G2 all four checks the original hand-rolled re2js guard ran (see
|
||||
* scripts/lint-vendored-deps.cjs's `checkRow`: .cjs drift, .d.cts drift, src/vendor/
|
||||
* twin drift, version-pin drift) still fire, asserted against re2js's CURRENT
|
||||
* behavior — not re-derived from the new manifest, which would validate the
|
||||
* refactor against its own output and prove nothing about drift.
|
||||
* G3 the hand-authored js-yaml type twin (no upstream to compare against) is
|
||||
* deliberately excluded from the byte-compare rather than silently skipped by
|
||||
* accident, and is pinned by a direct assertion on its declared surface instead.
|
||||
*/
|
||||
|
||||
const { describe, test } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const fs = require('node:fs');
|
||||
const os = require('node:os');
|
||||
const path = require('node:path');
|
||||
|
||||
const {
|
||||
VENDORED,
|
||||
compareFiles,
|
||||
checkRow,
|
||||
stripRangeOperator,
|
||||
declaredValueExports,
|
||||
checkHandAuthoredTwin,
|
||||
resolvePath,
|
||||
} = require('../scripts/lint-vendored-deps.cjs');
|
||||
|
||||
const REPO_ROOT = path.join(__dirname, '..');
|
||||
|
||||
function jsYamlRow() {
|
||||
const row = VENDORED.find((r) => r.name === 'js-yaml');
|
||||
assert.ok(row, 'expected a js-yaml row in VENDORED');
|
||||
return row;
|
||||
}
|
||||
|
||||
function re2jsRow() {
|
||||
const row = VENDORED.find((r) => r.name === 're2js');
|
||||
assert.ok(row, 'expected a re2js row in VENDORED');
|
||||
return row;
|
||||
}
|
||||
|
||||
describe('resolvePath: absolute-input safety does not change repo-relative resolution', () => {
|
||||
test('a repo-relative input still resolves under REPO_ROOT (unchanged behavior)', () => {
|
||||
const row = jsYamlRow();
|
||||
assert.equal(resolvePath(row.vendoredCjs), path.join(REPO_ROOT, row.vendoredCjs));
|
||||
});
|
||||
|
||||
test('an absolute input is returned as-is, not re-joined onto REPO_ROOT', () => {
|
||||
const absPath = path.join(os.tmpdir(), 'resolve-path-absolute-sensor.cjs');
|
||||
assert.equal(resolvePath(absPath), absPath);
|
||||
// Sensor: confirm this is not vacuous — path.join(ROOT, absPath) (the
|
||||
// pre-fix behavior) would NOT equal absPath, since joining an absolute
|
||||
// second segment onto ROOT is not the identity operation on either
|
||||
// POSIX or Windows.
|
||||
assert.notEqual(path.join(REPO_ROOT, absPath), absPath);
|
||||
});
|
||||
});
|
||||
|
||||
describe('G1: vendored js-yaml matches node_modules via the generalized manifest', () => {
|
||||
test('the js-yaml row byte-compares clean against node_modules today', () => {
|
||||
const findings = checkRow(jsYamlRow());
|
||||
assert.deepEqual(findings, [], `unexpected drift findings for js-yaml: ${JSON.stringify(findings)}`);
|
||||
});
|
||||
|
||||
test('sensor: compareFiles is not vacuous — it reports drift against a deliberately mutated copy', () => {
|
||||
const row = jsYamlRow();
|
||||
const upstreamAbs = path.join(REPO_ROOT, row.upstreamCjs);
|
||||
const tmpFile = path.join(os.tmpdir(), `js-yaml-mutated-${process.pid}-${Date.now()}.cjs`);
|
||||
const original = fs.readFileSync(upstreamAbs, 'utf8');
|
||||
fs.writeFileSync(tmpFile, `${original}\n// mutated for test\n`);
|
||||
try {
|
||||
// tmpFile is passed ABSOLUTE, not relativized against REPO_ROOT — a
|
||||
// temp dir can live on a different drive than the repo checkout
|
||||
// (observed on windows-latest CI), where path.relative() cannot
|
||||
// express a relative traversal and silently returns the absolute
|
||||
// path unchanged, defeating compareFiles's `path.join(ROOT, rel)`
|
||||
// resolution. compareFiles/resolvePath must accept an absolute path
|
||||
// as-is regardless of platform or drive.
|
||||
const drift = compareFiles(row.vendoredCjs, tmpFile);
|
||||
assert.ok(drift, 'expected compareFiles to report drift against a mutated copy, got null');
|
||||
assert.ok(drift.includes('!='), `expected a byte-length mismatch description, got: ${drift}`);
|
||||
} finally {
|
||||
fs.unlinkSync(tmpFile);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('G2: all four original re2js checks still fire after the manifest refactor', () => {
|
||||
test('fresh state: re2js has zero findings today (sanity baseline before mutating)', () => {
|
||||
const findings = checkRow(re2jsRow());
|
||||
assert.deepEqual(findings, [], `expected re2js to be fresh; findings: ${JSON.stringify(findings)}`);
|
||||
});
|
||||
|
||||
test('check 1 (cjs drift) fires against a mutated vendoredCjs copy', () => {
|
||||
const row = re2jsRow();
|
||||
const vendoredAbs = path.join(REPO_ROOT, row.vendoredCjs);
|
||||
const tmpFile = path.join(os.tmpdir(), `re2js-vendored-mutated-${process.pid}-${Date.now()}.cjs`);
|
||||
fs.writeFileSync(tmpFile, `${fs.readFileSync(vendoredAbs, 'utf8')}\n// mutated`);
|
||||
try {
|
||||
// Absolute tmpFile, not relativized — see the js-yaml sensor test above
|
||||
// for why: cross-drive path.relative() on Windows returns the absolute
|
||||
// path unchanged, which is exactly the shape that must still resolve.
|
||||
const mutatedRow = { ...row, vendoredCjs: tmpFile };
|
||||
const findings = checkRow(mutatedRow);
|
||||
assert.ok(
|
||||
findings.some((f) => f.includes('!=')),
|
||||
`expected a cjs-drift finding, got: ${JSON.stringify(findings)}`,
|
||||
);
|
||||
} finally {
|
||||
fs.unlinkSync(tmpFile);
|
||||
}
|
||||
});
|
||||
|
||||
test('check 2 (d.cts drift) fires against a mutated vendoredDts copy', () => {
|
||||
const row = re2jsRow();
|
||||
assert.ok(row.vendoredDts, 're2js is expected to carry a vendoredDts for this check to apply');
|
||||
const vendoredDtsAbs = path.join(REPO_ROOT, row.vendoredDts);
|
||||
const tmpFile = path.join(os.tmpdir(), `re2js-dts-mutated-${process.pid}-${Date.now()}.d.cts`);
|
||||
fs.writeFileSync(tmpFile, `${fs.readFileSync(vendoredDtsAbs, 'utf8')}\n// mutated`);
|
||||
try {
|
||||
// Absolute tmpFile — same cross-drive rationale as above.
|
||||
const mutatedRow = { ...row, vendoredDts: tmpFile };
|
||||
const findings = checkRow(mutatedRow);
|
||||
assert.ok(
|
||||
findings.some((f) => f.includes('!=')),
|
||||
`expected a d.cts-drift finding, got: ${JSON.stringify(findings)}`,
|
||||
);
|
||||
} finally {
|
||||
fs.unlinkSync(tmpFile);
|
||||
}
|
||||
});
|
||||
|
||||
test('check 3 (src/vendor twin drift) fires against a mutated srcTwin copy', () => {
|
||||
const row = re2jsRow();
|
||||
assert.ok(row.srcTwin, 're2js is expected to carry a srcTwin for this check to apply');
|
||||
const srcTwinAbs = path.join(REPO_ROOT, row.srcTwin);
|
||||
const tmpFile = path.join(os.tmpdir(), `re2js-srctwin-mutated-${process.pid}-${Date.now()}.d.cts`);
|
||||
fs.writeFileSync(tmpFile, `${fs.readFileSync(srcTwinAbs, 'utf8')}\n// mutated`);
|
||||
try {
|
||||
// Absolute tmpFile — same cross-drive rationale as above.
|
||||
const mutatedRow = { ...row, srcTwin: tmpFile };
|
||||
const findings = checkRow(mutatedRow);
|
||||
assert.ok(
|
||||
findings.some((f) => f.includes('!=')),
|
||||
`expected a src/vendor-twin-drift finding, got: ${JSON.stringify(findings)}`,
|
||||
);
|
||||
} finally {
|
||||
fs.unlinkSync(tmpFile);
|
||||
}
|
||||
});
|
||||
|
||||
test('check 4 (version-pin drift) fires when the row name has no package.json pin', () => {
|
||||
const row = re2jsRow();
|
||||
const mutatedRow = { ...row, name: 'a-package-that-is-not-pinned-anywhere' };
|
||||
const findings = checkRow(mutatedRow);
|
||||
assert.ok(
|
||||
findings.some((f) => f.includes('devDependencies') && f.includes('is missing')),
|
||||
`expected a missing-pin finding, got: ${JSON.stringify(findings)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test('check 4 (version-pin drift): stripRangeOperator mismatch is what the real check compares', () => {
|
||||
// checkRow reads package.json/node_modules directly and cannot be redirected, so this
|
||||
// exercises the exact comparison predicate checkRow applies
|
||||
// (stripRangeOperator(pinned) !== installed.version) against a synthetic mismatch,
|
||||
// proving the predicate itself can fail rather than only ever reading true.
|
||||
assert.equal(stripRangeOperator('^5.9.9') === '5.9.0', false, 'a genuine version mismatch must not compare equal');
|
||||
assert.equal(stripRangeOperator('^5.9.0') === '5.9.0', true, 'a matching version must compare equal');
|
||||
});
|
||||
});
|
||||
|
||||
describe('G3: the hand-authored js-yaml type twin is excluded from byte-compare, and pinned by test', () => {
|
||||
test('the js-yaml row is declared hand-authored with no upstream twin to compare', () => {
|
||||
const row = jsYamlRow();
|
||||
assert.equal(row.twinKind, 'hand-authored');
|
||||
assert.equal(row.upstreamDts, null, 'js-yaml ships no upstream .d.ts to compare against');
|
||||
assert.equal(row.vendoredDts, null, 'there is no bin-side .d.cts twin for js-yaml');
|
||||
assert.equal(row.srcTwin, 'src/vendor/js-yaml.d.cts');
|
||||
});
|
||||
|
||||
test('sensor: a byte-compare-neutral mutation (e.g. a trailing comment) produces NO drift finding — the BYTE-COMPARE exclusion is real, not accidental', () => {
|
||||
const row = jsYamlRow();
|
||||
const srcTwinAbs = path.join(REPO_ROOT, row.srcTwin);
|
||||
const original = fs.readFileSync(srcTwinAbs, 'utf8');
|
||||
fs.writeFileSync(srcTwinAbs, `${original}\n// mutated for test — must not be flagged\n`);
|
||||
try {
|
||||
const findings = checkRow(row);
|
||||
assert.deepEqual(
|
||||
findings,
|
||||
[],
|
||||
`hand-authored twin must be excluded from byte-compare; unexpected findings: ${JSON.stringify(findings)}`,
|
||||
);
|
||||
} finally {
|
||||
fs.writeFileSync(srcTwinAbs, original);
|
||||
}
|
||||
});
|
||||
|
||||
test('#3881 review, finding 4: srcTwin is NOT dead for a hand-authored row — a declared export the runtime does not have IS caught', () => {
|
||||
// Before the fix, `srcTwin` was read only inside the `twinKind === 'upstream-verbatim'`
|
||||
// branch; for a hand-authored row nothing ever consulted it, which is exactly how the
|
||||
// js-yaml.d.cts docblock could drift from runtime reality (finding 2) unnoticed.
|
||||
const row = jsYamlRow();
|
||||
const srcTwinAbs = path.join(REPO_ROOT, row.srcTwin);
|
||||
const original = fs.readFileSync(srcTwinAbs, 'utf8');
|
||||
fs.writeFileSync(
|
||||
srcTwinAbs,
|
||||
`${original}\nexport function thisExportDoesNotExistAtRuntime(): void;\n`,
|
||||
);
|
||||
try {
|
||||
const findings = checkRow(row);
|
||||
assert.ok(
|
||||
findings.some((f) => f.includes('thisExportDoesNotExistAtRuntime')),
|
||||
`expected a declared-export-not-at-runtime finding, got: ${JSON.stringify(findings)}`,
|
||||
);
|
||||
} finally {
|
||||
fs.writeFileSync(srcTwinAbs, original);
|
||||
}
|
||||
});
|
||||
|
||||
test('checkHandAuthoredTwin: fresh state is clean for the real js-yaml twin', () => {
|
||||
assert.deepEqual(checkHandAuthoredTwin(jsYamlRow()), []);
|
||||
});
|
||||
|
||||
test('declaredValueExports: extracts function/const/class exports, ignores type/interface exports', () => {
|
||||
const src = [
|
||||
'export interface Foo { x: number; }',
|
||||
'export type Bar = string;',
|
||||
'export function realFn(): void;',
|
||||
'export const REAL_CONST: string;',
|
||||
'export class RealClass {}',
|
||||
].join('\n');
|
||||
assert.deepEqual(declaredValueExports(src), ['realFn', 'REAL_CONST', 'RealClass']);
|
||||
});
|
||||
|
||||
test('contrast: the SAME mutation on an upstream-verbatim row (re2js) IS caught — proving the exclusion is deliberate', () => {
|
||||
const row = re2jsRow();
|
||||
const srcTwinAbs = path.join(REPO_ROOT, row.srcTwin);
|
||||
const original = fs.readFileSync(srcTwinAbs, 'utf8');
|
||||
fs.writeFileSync(srcTwinAbs, `${original}\n// mutated for test — must be flagged\n`);
|
||||
try {
|
||||
const findings = checkRow(row);
|
||||
assert.ok(findings.length > 0, 'expected the upstream-verbatim row to catch the same mutation the hand-authored row ignores');
|
||||
} finally {
|
||||
fs.writeFileSync(srcTwinAbs, original);
|
||||
}
|
||||
});
|
||||
|
||||
test("js-yaml.d.cts's declared surface is pinned (no upstream to byte-diff, so pin by contract instead)", () => {
|
||||
const content = fs.readFileSync(path.join(REPO_ROOT, 'src/vendor/js-yaml.d.cts'), 'utf8');
|
||||
// The declared surface is deliberately narrow (ADR-3473 §8.1: only what the FAILSAFE
|
||||
// read/write path needs). Pin each declared export by name.
|
||||
assert.match(content, /export function load\(/, 'load export missing');
|
||||
assert.match(content, /export function dump\(/, 'dump export missing');
|
||||
assert.match(content, /export const FAILSAFE_SCHEMA:/, 'FAILSAFE_SCHEMA export missing');
|
||||
assert.match(content, /export class YAMLException/, 'YAMLException export missing');
|
||||
// Deliberately NOT declared — anchors/aliases/custom types/loadAll are unreachable
|
||||
// from typed code through this twin (the security posture this twin encodes). Check
|
||||
// for an actual export statement, not just the word (which legitimately appears in
|
||||
// this file's own prose explaining the exclusion).
|
||||
assert.doesNotMatch(content, /export function loadAll\(/, 'loadAll must stay undeclared per the narrowed surface');
|
||||
});
|
||||
});
|
||||
@@ -191,13 +191,13 @@ describe('mutation-matrix ratchet: guard detects missing minScore', () => {
|
||||
// The assertion "every baseline module still exists in COVERED" enforces the
|
||||
// reverse: removing a module from COVERED also requires updating the baseline.
|
||||
const RATCHET_BASELINE = {
|
||||
'context-utilization': 80,
|
||||
'context-composer': 66, // #2929: extracted from prompt-budget; same floor as prompt-budget
|
||||
'prompt-budget': 66, // CI 68.33% 2026-06-14; was 90 (timeout-inflated local)
|
||||
'context-utilization': 91, // CI run 33012034388 (2026-08-25): measured 92.31%; floor(92.31)-1
|
||||
'context-composer': 78, // CI run 33012034388 (2026-08-25): measured 79.92%; floor(79.92)-1
|
||||
'prompt-budget': 87, // CI run 33012034388 (2026-08-25): measured 88.95%; floor(88.95)-1
|
||||
'frontmatter': 65, // #3706: raised from 62; measured 66.67 on PR 3867
|
||||
'adr-parser': 68,
|
||||
'config-schema': 52, // CI 54.55% 2026-06-14; was 68 (timeout-inflated local)
|
||||
'active-workstream-store': 80,
|
||||
'config-schema': 74, // CI run 33012034388 (2026-08-25): measured 75.51%; floor(75.51)-1
|
||||
'active-workstream-store': 86, // CI run 33012034388 (2026-08-25): measured 87.42%; floor(87.42)-1
|
||||
'core-utils': 75,
|
||||
'planning-inspect': 56, // CI run 32392791843: 57.03% (unit shard); ratchet candidate vs TARGET 80
|
||||
'plan-document': 75, // CI run 32392791843: 76.58% (unit shard)
|
||||
|
||||
191
tests/mutation-score-ratchet.test.cjs
Normal file
191
tests/mutation-score-ratchet.test.cjs
Normal file
@@ -0,0 +1,191 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* tests/mutation-score-ratchet.test.cjs
|
||||
*
|
||||
* Regression net for scripts/check-mutation-score-ratchet.cjs (#3881
|
||||
* follow-up, mutation-matrix piece 3: "the floor must ratchet up, not sit
|
||||
* where it is forever"). Drives the pure `evaluateRatchet` against boundary
|
||||
* inputs, then proves the CLI end-to-end against a synthetic Stryker `json`
|
||||
* reporter fixture: FAILS when the achieved score clears the floor by more
|
||||
* than the documented slack, PASSES when raised (or when within slack).
|
||||
*/
|
||||
|
||||
const { test, describe } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const path = require('node:path');
|
||||
const fs = require('node:fs');
|
||||
const os = require('node:os');
|
||||
|
||||
const {
|
||||
RATCHET_SLACK,
|
||||
evaluateRatchet,
|
||||
extractAchievedScore,
|
||||
} = require('../scripts/check-mutation-score-ratchet.cjs');
|
||||
const { runNode } = require('./helpers/process-seam.cjs');
|
||||
const { createTempDir, cleanup } = require('./helpers.cjs');
|
||||
const { PROBE_TIMEOUT_MS } = require('./helpers/timeouts.cjs');
|
||||
|
||||
const SCRIPT = path.resolve(__dirname, '..', 'scripts', 'check-mutation-score-ratchet.cjs');
|
||||
const REPO_ROOT = path.resolve(__dirname, '..');
|
||||
|
||||
describe('evaluateRatchet: pure boundary behaviour', () => {
|
||||
test(`achieved exactly floor + ${RATCHET_SLACK} does NOT ratchet (boundary, inclusive)`, () => {
|
||||
const { shouldRatchet } = evaluateRatchet(65 + RATCHET_SLACK, 65);
|
||||
assert.equal(shouldRatchet, false);
|
||||
});
|
||||
|
||||
test(`achieved floor + ${RATCHET_SLACK} + 0.01 DOES ratchet (just past the boundary)`, () => {
|
||||
const { shouldRatchet, suggestedFloor } = evaluateRatchet(65 + RATCHET_SLACK + 0.01, 65);
|
||||
assert.equal(shouldRatchet, true);
|
||||
assert.equal(suggestedFloor, Math.floor(65 + RATCHET_SLACK + 0.01) - 1);
|
||||
});
|
||||
|
||||
test('achieved below floor does NOT ratchet (a floor breach is Stryker\'s own MUTATION_BREAK problem, not this script\'s)', () => {
|
||||
const { shouldRatchet } = evaluateRatchet(40, 65);
|
||||
assert.equal(shouldRatchet, false);
|
||||
});
|
||||
|
||||
test('achieved equal to floor does NOT ratchet', () => {
|
||||
const { shouldRatchet } = evaluateRatchet(65, 65);
|
||||
assert.equal(shouldRatchet, false);
|
||||
});
|
||||
|
||||
test('suggestedFloor follows floor(achieved) - 1 exactly (this file\'s own documented convention)', () => {
|
||||
const { suggestedFloor } = evaluateRatchet(92.7, 60);
|
||||
assert.equal(suggestedFloor, 91);
|
||||
});
|
||||
});
|
||||
|
||||
describe('extractAchievedScore: Stryker json-reporter document', () => {
|
||||
test('computes the same score Stryker itself would report for a mixed killed/survived set', () => {
|
||||
const report = {
|
||||
schemaVersion: '1.0',
|
||||
thresholds: { high: 80, low: 60 },
|
||||
files: {
|
||||
'foo.js': {
|
||||
language: 'javascript',
|
||||
source: 'x',
|
||||
mutants: [
|
||||
{ id: '1', mutatorName: 'a', status: 'Killed', location: { start: { line: 1, column: 1 }, end: { line: 1, column: 2 } } },
|
||||
{ id: '2', mutatorName: 'a', status: 'Killed', location: { start: { line: 1, column: 1 }, end: { line: 1, column: 2 } } },
|
||||
{ id: '3', mutatorName: 'a', status: 'Killed', location: { start: { line: 1, column: 1 }, end: { line: 1, column: 2 } } },
|
||||
{ id: '4', mutatorName: 'a', status: 'Survived', location: { start: { line: 1, column: 1 }, end: { line: 1, column: 2 } } },
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
assert.equal(extractAchievedScore(report), 75);
|
||||
});
|
||||
|
||||
test('throws when the report has no scoreable mutants (empty files map — a wiring bug, never a 0% score)', () => {
|
||||
assert.throws(() => extractAchievedScore({ schemaVersion: '1.0', thresholds: {}, files: {} }), /no scoreable mutants/);
|
||||
});
|
||||
});
|
||||
|
||||
// ── CLI end-to-end: fail on a planted over-floor score, pass when the floor is raised ───
|
||||
// SYNTHETIC_FLOOR is a fixture value this test file owns outright — never a real module's
|
||||
// minScore from scripts/mutation-matrix.cjs. That real config ratchets UP as modules improve
|
||||
// (exactly what this script's own CLI enforces), so a row that hardcodes a real floor breaks
|
||||
// every time the ratchet does its job (see config-schema: 52 -> 74 by commit 973321541, which
|
||||
// broke this file's previous PLANTED/RESTORED rows). Building a synthetic `--matrix` fixture
|
||||
// with a floor this test controls makes the rows indifferent to any real module's floor moving.
|
||||
const SYNTHETIC_MODULE = 'synthetic-ratchet-fixture';
|
||||
const SYNTHETIC_FLOOR = 65;
|
||||
|
||||
function withMatrixFixture(floor, fn) {
|
||||
const dir = createTempDir('mutation-score-ratchet-matrix-');
|
||||
const matrixPath = path.join(dir, 'fixture-mutation-matrix.cjs');
|
||||
fs.writeFileSync(
|
||||
matrixPath,
|
||||
`'use strict';\nmodule.exports = { COVERED: { '${SYNTHETIC_MODULE}': { minScore: ${floor} } } };\n`,
|
||||
'utf8'
|
||||
);
|
||||
try {
|
||||
return fn(matrixPath);
|
||||
} finally {
|
||||
cleanup(dir);
|
||||
}
|
||||
}
|
||||
|
||||
function withReportFixture(mutationScore, fn) {
|
||||
// Build a Stryker json-reporter-shaped document whose achieved score is EXACTLY
|
||||
// `mutationScore` via N killed + (100 - N) survived out of 100 mutants — avoids floating
|
||||
// point ambiguity in the fixture itself.
|
||||
const killed = Math.round(mutationScore);
|
||||
const mutants = [];
|
||||
for (let i = 0; i < 100; i++) {
|
||||
mutants.push({
|
||||
id: String(i),
|
||||
mutatorName: 'a',
|
||||
status: i < killed ? 'Killed' : 'Survived',
|
||||
location: { start: { line: 1, column: 1 }, end: { line: 1, column: 2 } },
|
||||
});
|
||||
}
|
||||
const report = {
|
||||
schemaVersion: '1.0',
|
||||
thresholds: { high: 80, low: 60 },
|
||||
files: { 'foo.js': { language: 'javascript', source: 'x', mutants } },
|
||||
};
|
||||
const dir = createTempDir('mutation-score-ratchet-test-');
|
||||
const reportPath = path.join(dir, 'mutation.json');
|
||||
fs.writeFileSync(reportPath, JSON.stringify(report), 'utf8');
|
||||
try {
|
||||
return fn(reportPath);
|
||||
} finally {
|
||||
cleanup(dir);
|
||||
}
|
||||
}
|
||||
|
||||
describe('check-mutation-score-ratchet CLI: end-to-end fail-then-pass', () => {
|
||||
test(`PLANTED: achieved score far above a synthetic module's floor (${SYNTHETIC_FLOOR}) FAILS the ratchet`, () => {
|
||||
withMatrixFixture(SYNTHETIC_FLOOR, (matrixPath) => {
|
||||
withReportFixture(SYNTHETIC_FLOOR + RATCHET_SLACK + 10, (reportPath) => {
|
||||
const result = runNode(
|
||||
[SCRIPT, '--module', SYNTHETIC_MODULE, '--report', reportPath, '--matrix', matrixPath],
|
||||
{ cwd: REPO_ROOT, timeoutMs: PROBE_TIMEOUT_MS }
|
||||
);
|
||||
assert.notEqual(result.exitCode, 0, `expected nonzero exit; stderr: ${result.stderr}`);
|
||||
assert.match(result.stderr, /raise the floor/);
|
||||
assert.match(result.stderr, new RegExp(SYNTHETIC_MODULE));
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
test('RESTORED: an achieved score within slack of the same synthetic floor PASSES', () => {
|
||||
withMatrixFixture(SYNTHETIC_FLOOR, (matrixPath) => {
|
||||
withReportFixture(SYNTHETIC_FLOOR + 1, (reportPath) => {
|
||||
const result = runNode(
|
||||
[SCRIPT, '--module', SYNTHETIC_MODULE, '--report', reportPath, '--matrix', matrixPath],
|
||||
{ cwd: REPO_ROOT, timeoutMs: PROBE_TIMEOUT_MS }
|
||||
);
|
||||
assert.equal(result.exitCode, 0, `expected exit 0; stderr: ${result.stderr}`);
|
||||
assert.match(result.stdout, /ok mutation-score-ratchet/);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
test('an unknown --module exits nonzero with a clear message', () => {
|
||||
withMatrixFixture(SYNTHETIC_FLOOR, (matrixPath) => {
|
||||
withReportFixture(90, (reportPath) => {
|
||||
const result = runNode(
|
||||
[SCRIPT, '--module', 'does-not-exist', '--report', reportPath, '--matrix', matrixPath],
|
||||
{ cwd: REPO_ROOT, timeoutMs: PROBE_TIMEOUT_MS }
|
||||
);
|
||||
assert.notEqual(result.exitCode, 0);
|
||||
assert.match(result.stderr, /unknown module/);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
test('a missing report file exits nonzero with a clear message', () => {
|
||||
withMatrixFixture(SYNTHETIC_FLOOR, (matrixPath) => {
|
||||
const result = runNode(
|
||||
[SCRIPT, '--module', SYNTHETIC_MODULE, '--report', path.join(os.tmpdir(), 'does-not-exist-mutation.json'), '--matrix', matrixPath],
|
||||
{ cwd: REPO_ROOT, timeoutMs: PROBE_TIMEOUT_MS }
|
||||
);
|
||||
assert.notEqual(result.exitCode, 0);
|
||||
assert.match(result.stderr, /report not found/);
|
||||
});
|
||||
});
|
||||
});
|
||||
93
tests/mutation-test-derivation-drift.test.cjs
Normal file
93
tests/mutation-test-derivation-drift.test.cjs
Normal file
@@ -0,0 +1,93 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* tests/mutation-test-derivation-drift.test.cjs
|
||||
*
|
||||
* Regression net for scripts/lint-mutation-test-derivation-drift.cjs (#3881
|
||||
* follow-up, mutation-matrix piece 2). Drives the guard's pure `findDrift`
|
||||
* against a synthetic COVERED map so this test never depends on the real
|
||||
* tests/ tree (hermetic, and immune to future test-file churn).
|
||||
*
|
||||
* Also proves, against the REAL repo (scripts/mutation-matrix.cjs's exported
|
||||
* COVERED + derivation helpers), that the guard currently reports zero drift
|
||||
* — the same invariant `npm run lint:ci` enforces, exercised in-process here
|
||||
* so a regression is caught by the normal test suite too, not only by lint:ci.
|
||||
*/
|
||||
|
||||
const { test, describe } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
|
||||
const { findDrift } = require('../scripts/lint-mutation-test-derivation-drift.cjs');
|
||||
|
||||
describe('lint-mutation-test-derivation-drift: findDrift (synthetic)', () => {
|
||||
test('a module-named file that requires the module and is in `tests` is NOT drift', () => {
|
||||
const covered = {
|
||||
widget: { tests: ['tests/widget.unit.test.cjs'] },
|
||||
};
|
||||
const findRequiringTestFiles = (mod) => (mod === 'widget' ? ['widget.unit.test.cjs'] : []);
|
||||
const matchesModuleNamingRule = (mod, file) => file.startsWith(`${mod}.`) || file.startsWith(`${mod}-`);
|
||||
|
||||
const drift = findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule);
|
||||
assert.deepEqual(drift, []);
|
||||
});
|
||||
|
||||
test('a module-named file that requires the module and is in `excludeTests` is NOT drift (deliberate exclusion)', () => {
|
||||
const covered = {
|
||||
widget: { tests: ['tests/widget.unit.test.cjs'], excludeTests: ['widget.integration.test.cjs'] },
|
||||
};
|
||||
const findRequiringTestFiles = (mod) => (mod === 'widget' ? ['widget.unit.test.cjs', 'widget.integration.test.cjs'] : []);
|
||||
const matchesModuleNamingRule = (mod, file) => file.startsWith(`${mod}.`) || file.startsWith(`${mod}-`);
|
||||
|
||||
const drift = findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule);
|
||||
assert.deepEqual(drift, []);
|
||||
});
|
||||
|
||||
test('PLANTED OMISSION: a module-named file that requires the module but is in neither `tests` nor `excludeTests` IS reported', () => {
|
||||
// Reproduces the exact #3888 shape: a new frontmatter-named test file added on a
|
||||
// branch, requiring frontmatter.cjs, that nobody registered anywhere.
|
||||
const covered = {
|
||||
widget: { tests: ['tests/widget.unit.test.cjs'] },
|
||||
};
|
||||
const findRequiringTestFiles = (mod) =>
|
||||
(mod === 'widget' ? ['widget.unit.test.cjs', 'widget.new-consequence.test.cjs'] : []);
|
||||
const matchesModuleNamingRule = (mod, file) => file.startsWith(`${mod}.`) || file.startsWith(`${mod}-`);
|
||||
|
||||
const drift = findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule);
|
||||
assert.deepEqual(drift, [{ module: 'widget', file: 'widget.new-consequence.test.cjs' }]);
|
||||
});
|
||||
|
||||
test('a requiring file that does NOT match the naming rule is never drift (cross-cutting files need extraTests, not auto-detection)', () => {
|
||||
const covered = {
|
||||
widget: { tests: ['tests/widget.unit.test.cjs'] },
|
||||
};
|
||||
const findRequiringTestFiles = (mod) => (mod === 'widget' ? ['widget.unit.test.cjs', 'unrelated-integration.test.cjs'] : []);
|
||||
const matchesModuleNamingRule = (mod, file) => file.startsWith(`${mod}.`) || file.startsWith(`${mod}-`);
|
||||
|
||||
const drift = findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule);
|
||||
assert.deepEqual(drift, []);
|
||||
});
|
||||
|
||||
test('a module with no requiring files at all reports no drift', () => {
|
||||
const covered = { widget: { tests: [] } };
|
||||
const findRequiringTestFiles = () => [];
|
||||
const matchesModuleNamingRule = () => false;
|
||||
assert.deepEqual(findDrift(covered, findRequiringTestFiles, matchesModuleNamingRule), []);
|
||||
});
|
||||
});
|
||||
|
||||
describe('lint-mutation-test-derivation-drift: real repo has zero drift', () => {
|
||||
test('scripts/mutation-matrix.cjs COVERED has no undisposed module-named requiring test file', () => {
|
||||
const {
|
||||
COVERED,
|
||||
findRequiringTestFiles,
|
||||
matchesModuleNamingRule,
|
||||
} = require('../scripts/mutation-matrix.cjs');
|
||||
|
||||
const drift = findDrift(COVERED, findRequiringTestFiles, matchesModuleNamingRule);
|
||||
assert.deepEqual(
|
||||
drift,
|
||||
[],
|
||||
`found undisposed test file(s): ${JSON.stringify(drift)} — see scripts/lint-mutation-test-derivation-drift.cjs`
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -792,16 +792,25 @@ All checks passed.
|
||||
const output = JSON.parse(result.output);
|
||||
assert.strictEqual(output.summary.total_items, 1,
|
||||
'total_items must reflect the frontmatter array, not the unstructured body prose');
|
||||
// #2286 review LOW finding: extractFrontmatter's generic array-item
|
||||
// parser has no notion of nested key/value objects — a `- test: "..."`
|
||||
// entry is ALWAYS flattened to the raw post-"- " text, verbatim (only
|
||||
// its own wrapping quote is stripped, and only at the string's outer
|
||||
// edges). normalizeHumanVerificationEntry deliberately does NOT strip
|
||||
// a leading "key:"-shaped prefix (see its doc comment) because doing
|
||||
// so is indistinguishable from truncating a legitimate plain string
|
||||
// that starts with a word and a colon — so this documented, slightly
|
||||
// ugly artifact is the CORRECT (non-data-lossy) output for this shape.
|
||||
assert.strictEqual(output.results[0].items[0].name, 'test: "Confirm the widget renders correctly');
|
||||
// ADR-3473 §8.1 (#3881): pre-migration, extractFrontmatter's hand-rolled array-item
|
||||
// scanner had no notion of nested key/value objects — a `- test: "..."` entry was
|
||||
// flattened via a REGEX quote-strip (`.replace(/^["']|["']$/g, '')`) that only ever
|
||||
// matches a quote at the very start or very end of the WHOLE post-"- " string. Since
|
||||
// this string starts with `test:` (not a quote), only the regex's END anchor matched,
|
||||
// stripping the trailing `"` but leaving the opening one embedded mid-string — a
|
||||
// documented but genuinely ugly artifact (`test: "Confirm the widget renders correctly`,
|
||||
// unbalanced quote and all).
|
||||
//
|
||||
// Under js-yaml (ADR-3473 §8.1), `- test: "..."` is parsed as real YAML — a proper
|
||||
// mapping `{test: "Confirm the widget renders correctly"}` — and `flattenObjectListItem`
|
||||
// re-joins it as `key: value` with the value's OWN quoting already resolved by the real
|
||||
// parser, not re-derived by a second regex. The embedded quote is gone because it was
|
||||
// never data to begin with; it was YAML's own value-delimiter syntax. This is strictly
|
||||
// more correct (no unbalanced-quote artifact) and the `normalizeHumanVerificationEntry`
|
||||
// consumer is unaffected — it still receives a `name` string of the same shape (still not
|
||||
// lossy of the `test:` label prefix, which is a deliberate, documented, and unrelated
|
||||
// decision — see normalizeHumanVerificationEntry's doc comment).
|
||||
assert.strictEqual(output.results[0].items[0].name, 'test: Confirm the widget renders correctly');
|
||||
assert.strictEqual(output.results[0].items[0].category, 'human_uat');
|
||||
});
|
||||
|
||||
|
||||
@@ -1689,7 +1689,12 @@ describe('verify key-links command', () => {
|
||||
writePlanWithKeyLinks(tmpDir, [
|
||||
'- from: "src/a.js"',
|
||||
' to: "src/b.js"',
|
||||
' pattern: "exports\\.targetFunc"',
|
||||
// ADR-3473 §8.1 (#3881): a bare `\.` inside a YAML double-quoted scalar is not a
|
||||
// recognized escape sequence — `\\.` (a real backslash escaping itself, then a literal
|
||||
// dot) is the valid spelling for the same intended pattern string `exports\.targetFunc`.
|
||||
// The old hand-rolled parseMustHavesBlock never validated YAML escape rules and
|
||||
// silently accepted the invalid form; the vendored js-yaml parser correctly refuses it.
|
||||
' pattern: "exports\\\\.targetFunc"',
|
||||
]);
|
||||
// pattern NOT in source, but found in target
|
||||
fs.writeFileSync(path.join(tmpDir, 'src', 'a.js'), 'const x = 1;\n');
|
||||
|
||||
Reference in New Issue
Block a user