* test(#3884): failing-first coverage for strict argv and absence-signalling --pick ADR-3473 §8.4 says failure is a value. Three families currently encode failure as success, and this commit pins each one RED before the fix lands. Measured on this tree, 2026-08-26: gsd-tools generate-slug "test" --pick nonexistent -> empty stdout, exit 0 (#3365) gsd-tools audit-open --pick nonexistent_field -> dumps the entire human-readable audit report, exit 0 gsd-tools generate-slug "Hello World" --raw --pick bogus -> prints "hello-world", another field's value, exit 0 gsd-tools query state.planned-phase 3 (positional, no --phase) -> exit 0; STATE.md's "Phase: 2 of 5 (Widget Support)" is overwritten to "Phase: null - READY TO EXECUTE" and the frontmatter gains a corrupted current_phase_name (#3358) tests/pick-flag.test.cjs:27 previously asserted the #3365 defect as the contract ("returns empty string for missing field", success === true). That assertion is replaced by the required behavior rather than deleted. The new parseNamedArgs block calls the spec-object signature that does not exist yet, so it fails today by construction. The 11 existing behavior-lock tests are left untouched here; they are corrected in the implementation commit. C1/C4 assert at the consumer's output - STATE.md's bytes - per ADR-3180 Decision 4(b). A unit assertion on the parser would have passed throughout this defect's life. Design: .gsd/phase/feat-3884-failure-is-a-value/40-design.md Test matrix: .gsd/phase/feat-3884-failure-is-a-value/50-test-matrix.md Refs #3884 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * enhance(#3884): failure is a value — strict argv, and --pick that signals absence Implements ADR-3473 §8.4. Absence, emptiness and failure stop being interchangeable ways to say "I could not answer". parseNamedArgs (src/command-arg-projection.cts) Takes a spec object with a REQUIRED `positionals: number | 'rest'` and returns the hub's Result shape instead of a bare Record. Declaring the positional arity is what makes #3358's call site unrepresentable rather than merely detectable: an unrecognized flag or a token past the declared boundary is now InvalidArgs, naming the offending token and listing the accepted flags. The legacy positional-array call shape throws a TypeError — an internal invariant violation per ADR-3473 Decision 2, so a stale hand-written .cjs call site fails loudly instead of destructuring undefined off a Result. parseNamedArgsOrExit projects a failure onto the caller's error(); it is a projection over the one parser, not a second parser. Measured before, against a STATE.md with a populated phase-2 block: query state.planned-phase 3 (positional, no --phase) -> exit 0; "Phase: 2 of 5 (Widget Support)" overwritten to "Phase: null - READY TO EXECUTE", frontmatter gains a corrupted current_phase_name After: exit 1, `unexpected positional argument "3"`, STATE.md byte-identical. The flag form is unchanged and still updates STATE.md. --pick <field> (gsd-core/bin/gsd-tools.cjs) extractField returns {found,value}, and the pick block no longer shares one catch between "output was not JSON" and "field was absent". An absent field exits 1 with pick_field_absent, naming the field and the keys that do exist; non-JSON output exits 1 with pick_output_not_json instead of dumping the command's entire output. A field that is PRESENT with value null, '', 0 or false still prints at exit 0 — that is an answer, not a failure, and it is what keeps `--pick count` printing 0 on a fresh project. Measured before: `audit-open --pick nonexistent_field` printed the whole human-readable audit report at exit 0, and `generate-slug X --raw --pick bogus` printed "hello-world" — a different field's value, confidently, at exit 0. ADR-3409 Decision 7 explicitly deferred this contract fix to #3473; this is it. The sub-issue's "returns 0 when the count is zero OR absent" wording is superseded by the ADR rule it implements: zero prints 0, absence exits non-zero. Defaulting absence to 0 would demote "could not answer" to "the answer is zero" — the hazard docs/how-to/resolve-unreachable-guard-findings.md already warns against. Guard ledger (ADR-3473 Decision 6) scripts/lint-unreachable-guard-drift.cjs Detector A is RETIRED. Its premise — that a `--pick ... || echo` arm can never fire — is now false, so the shape it forbade is the correct idiom and keeping it would forbid the fix. Detector B (glob-consuming cat/ls, a nullglob mechanism this change does not touch) is retained in full, as are the shared scanner, the escape-marker parser and the baseline. Net: -1 detector, 0 added. The file is not deleted. Call-site audit 45 prompt-layer --pick invocations, every one a plain X=$(...) assignment — none in an if test, && chain, or a pipeline whose status is consumed, and no shell block in workflows/commands/agents/references sets -e. Of the 13 (command, field) pairs the prompt layer reads, 10 are always present; the 3 sometimes-absent ones each sit behind a prior found/existence check. No ADR-3409-class "field the command never produces" remains. Design: .gsd/phase/feat-3884-failure-is-a-value/40-design.md Test matrix: .gsd/phase/feat-3884-failure-is-a-value/50-test-matrix.md Refs #3884 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3884): escape untrusted tokens in diagnostics, and cover five unpinned rows Two review findings, both fixed here rather than recorded as limits. 1. A newline in an untrusted token forged a second stderr line. Before, plain-text mode: $ gsd-tools query state.planned-phase $'foo\nError: forged second line' Error: unexpected positional argument "foo Error: forged second line" After: Error: unexpected positional argument "foo\nError: forged second line" --json-errors mode was never affected — io.error runs that payload through JSON.stringify. Plain-text mode writes 'Error: ' + message verbatim, and the three new InvalidArgs reasons plus the two new --pick diagnostics all interpolate a token that comes straight from argv. Fixed with ONE shared helper, formatDiagnosticToken (src/io.cts), applied at every interpolation site — not a copy per site. It is deliberately NOT applied inside error() itself: several callers in this tree emit intentional multi-line diagnostics, and escaping newlines there would mangle them. The available-top-level-keys list needed the same treatment for a reason the review did not anticipate: `frontmatter get <file>` reads an ARBITRARY user document and echoes that document's own keys into the diagnostic. Verified reachable — a frontmatter key containing a newline reaches the key list — so formatKeyForDiagnosticList is guarding a live path, not a hypothetical one. Ordinary keys still render plain and unquoted; a fix that merely dropped the key would also have passed a "one line" assertion, so the test pins the escaped key's presence too. 2. Five behavior-table rows were implemented but nothing pinned them: B7 a dotted path that dies partway B9 bracket syntax on a non-array B10 a negative array index, in and out of range B14 a JSON root that is not an object B17 an @file: payload over 50KB B17 is the load-bearing one. output() writes @file:<path> instead of inline JSON past 50000 characters, and --pick resolves that BEFORE parsing; with no test, a future reordering of those two steps turns every large result into a false pick_output_not_json. The fixture seeds 1200 phase directories and measures the payload at 62474 characters, asserting the spill actually happened rather than assuming it. Refs #3884 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3884): correct the strict-argv surface against a full verification run The first full run came back with 90 failures across 12 files, none in the new tests. They were the argv surface telling me what it actually is. Ten root causes; each classified before anything was changed. I over-implemented, and that is reverted. ADR-3473 §8.4 says parseNamedArgs rejects "unrecognized and positional tokens". It says nothing about a value flag whose value is missing. Making that an error was my design decision, not the rule, and it broke a deliberately recorded contract: `--prd` with no value resolving to null (tests/init.test.cjs emptyPrdValueIsFalsyAndTreatedAsAbsent, row B5; tests/section-manifest-init-facts.test.cjs "flag-shaped value"). The "requires a value" branch is deleted outright rather than kept behind an option — an unused strictness mode is speculative generality. Unknown-flag and unexpected-positional rejection, which is what §8.4 actually mandates, is unchanged. --wave needed a third flag kind the original design did not anticipate. `--wave N` is documented (commands/gsd/execute-phase.md:4,48) and the shipped workflow reconstructs and passes it (execute-phase.md:84), while #2932 records token-PRESENCE semantics: the CLI cares only that the flag appeared, and the value belongs to the workflow layer. That is neither a boolean flag nor a value flag, so `optionalValueFlags` now exists — presence-only in `data`, and the validation cursor consumes a following non-flag token so it is not reported as a stray positional. Every other declared boolean flag was checked against every argument-hint and prose usage in commands/, workflows/, agents/ and docs/; `--wave` is the only one of this shape. Five tests were pinning forms that never worked. tests/adr857-core-without-capabilities.test.cjs passed `init plan-phase --phase 01-stub`, but the documented form is positional (docs/CLI-TOOLS.md:776) and the handler reads args[2] — which for that form is the literal string "--phase". Measured on the pre-fix build against a real .planning/phases/01-stub/ directory: init plan-phase 01-stub -> phase_found=true init plan-phase --phase 01-stub -> phase_found=false The test asserted only exit 0 and key presence, so it had been green while proving nothing about phase resolution. Corrected to the documented form and strengthened to assert phase_found === true. Same class in state.test.cjs (`--plan-count`, a flag that does not exist; the real one is `--plans`), milestone-archive.test.cjs (`init new-milestone --json`, silently ignored), and concurrency-safety.test.cjs (a bare positional field name whose OR-assertion passed because a whole-document dump happens to contain the substring it looked for). Six handlers had no argv validation at all — the same #3358 shape this phase exists to close, found while fixing the rest: init verify-work / phase-op / review / todos / remove-workspace read args[2] with nothing checking the rest, and validate health read --repair/--backfill through a bare args.includes() scan that bypassed the parser entirely. All now go through the seam, so the flag has one owner. tests/init-debug.test.cjs rows C4/C5 asserted that an unrecognized flag must NOT fail. That is the behavior §8.4 removes, and Decision 8 says a caller's local expectation does not override §8, so they are inverted and renamed — a test still called "ignores an unrecognized flag" while asserting rejection would be its own defect. Row C6's point is its PWNED canary; that assertion is kept verbatim and only its exit-status expectation changed, because the hostile token is now rejected rather than absorbed. The blast-radius estimate in 40-design.md is corrected rather than quietly left wrong. get_impact reported MEDIUM / 8 symbols upstream, and that was accurate for what the graph can see — parseNamedArgs's callers. It cannot see that those callers' handlers accept argv shapes wider than the code reading args[2] suggests, which is where the real surface was. Refs #3884 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3884): withdraw the validate-health tightening, finish the A2/A3 revert Second full run: 46 failures, down from 90. Four causes, two of them mine. Reverted `validate health` entirely — it was scope creep, and it broke a real flag. ~30 of the 46 read `unknown flag "--json"; accepted: --repair, --backfill`. The previous commit routed `validate health` through the parser on the reasoning that a flag should have one owner. That was wrong twice over: §8.4 names parseNamedArgs and count queries, and `validate health` was never a parseNamedArgs call site — it read its flags, just not through the parser, so it had no silent-drop defect to fix. Tightening it omitted `--json`, which the health-diagnostic suites use heavily. The handler is now byte-for-behaviour back to its pre-branch form. `validate context` stays converted: it genuinely was a call site, and its `--json` is now declared rather than read by a second `args.includes` scan. The five handlers that had NO validation at all — init verify-work / phase-op / review / todos / remove-workspace — stay fixed. Those read args[2] with nothing checking the rest, which is the #3358 shape this phase owns. Finished the A2/A3 revert. Three tests still encoded the deleted "a value flag with a missing value is an error" rule, including one added by the previous commit for that rule. All three now assert the reverted null contract, and the ones whose titles said "rejected" are renamed — a test named for a contract it no longer asserts is its own defect. `--wave=` and `--wave --weird` are correctly rejected. Neither is documented in commands/gsd/execute-phase.md, gsd-core/workflows/execute-phase.md or docs/, and neither is emitted by the shipped prompt layer, so both are unrecognized tokens that §8.4 mandates rejecting. `doesNotConsumeFollowingFlagAsWaveValue` keeps the property it exists for — asserted directly now, at the parser, that `--wave` does not swallow a following flag as its value — and only its exit-status expectation changed. A contradiction inside this branch, surfaced by the audit and resolved the safe way. Two pre-existing #3573 tests call `state begin-phase '2'` and `state planned-phase '2'` with a bare positional, relying on the old permissive parser to ignore it. This branch's own #3358 regression test requires that exact argv to be REJECTED. The two are mutually exclusive. Widening the router to accept a bare positional — mirroring complete-phase — would have silently re-opened #3358, and was verified to do exactly that: with the widened router, `query state.planned-phase 3` returned exit 0 and wrote current_phase_name again. It is reverted. docs/CLI-TOOLS.md:116 and docs/COMMANDS.md:2192 document only the `--phase N` form for both verbs, so the two #3573 tests move to it. Their assertions were never about the call shape — only that total_phases survives the resync — and both still pass. complete-phase is untouched: its bare positional IS documented, and it keeps the dynamic boundary and the negative-space note that record why. The audit that produced this is in the PR body: for every handler whose declaration changed, the flags it reads anywhere in its body, the flags the shipped surface documents, and the shapes the suite passes, compared. The `--json` miss was a pattern, not an accident — declaring a handler's flags from its parseNamedArgs call alone misses whatever it reads elsewhere. Refs #3884 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3884): backfill the changeset PR number Refs #3884 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -271,20 +271,29 @@ describe('B2 — CLI loop render-hooks: exit 0, activeHooks:[], placeholder for
|
||||
describe('B3 — init bundles for 5-step loop entry seam: exit 0 and valid JSON with capabilities off', () => {
|
||||
// Cases: the 5-step loop's main init entry points (those available without git)
|
||||
const INIT_CASES = [
|
||||
// #3884 (ADR-3473 §8.4): these three init subcommands take the phase as a
|
||||
// bare POSITIONAL (docs/CLI-TOOLS.md:775 `init plan-phase <phase>`, :787
|
||||
// `init execute-phase <phase>`) — there is no `--phase` flag for any of
|
||||
// them. Under the pre-#3884 permissive parser, `--phase 01-stub` silently
|
||||
// resolved to phase_found:false (args[2] literally became the string
|
||||
// "--phase"), which these tests never caught because they only checked
|
||||
// exit 0 and key PRESENCE. Corrected to the real, documented positional
|
||||
// form and strengthened to assert phase_found === true so a future
|
||||
// regression of this kind fails loudly instead of passing vacuously.
|
||||
{
|
||||
label: 'init plan-phase',
|
||||
args: ['init', 'plan-phase', '--phase', '01-stub'],
|
||||
args: ['init', 'plan-phase', '01-stub'],
|
||||
// Required fields that prove the bundle is a real JSON object used by the loop
|
||||
requiredFields: ['tdd_mode', 'phase_found', 'planning_exists'],
|
||||
},
|
||||
{
|
||||
label: 'init execute-phase',
|
||||
args: ['init', 'execute-phase', '--phase', '01-stub'],
|
||||
args: ['init', 'execute-phase', '01-stub'],
|
||||
requiredFields: ['tdd_mode', 'phase_found', 'config_exists'],
|
||||
},
|
||||
{
|
||||
label: 'init verify-work',
|
||||
args: ['init', 'verify-work', '--phase', '01-stub'],
|
||||
args: ['init', 'verify-work', '01-stub'],
|
||||
requiredFields: ['phase_found', 'commit_docs'],
|
||||
},
|
||||
];
|
||||
@@ -296,6 +305,12 @@ describe('B3 — init bundles for 5-step loop entry seam: exit 0 and valid JSON
|
||||
before(() => {
|
||||
// Bare project with .planning/ but all caps off in config
|
||||
tmpDir = makeProject(ALL_FALSE_CONFIG);
|
||||
// A real phase directory matching the "01-stub" argument used by every
|
||||
// INIT_CASES entry above — without it, phase_found is trivially false
|
||||
// regardless of whether the CLI call shape is correct, and the
|
||||
// strengthened phase_found:true assertion below could not distinguish
|
||||
// a working positional form from the #3358-class silent-drop bug.
|
||||
fs.mkdirSync(path.join(tmpDir, '.planning', 'phases', '01-stub'), { recursive: true });
|
||||
});
|
||||
|
||||
after(() => {
|
||||
@@ -330,6 +345,16 @@ describe('B3 — init bundles for 5-step loop entry seam: exit 0 and valid JSON
|
||||
`${label}: bundle must contain field "${field}", got keys: ${Object.keys(parsed).join(', ')}`,
|
||||
);
|
||||
}
|
||||
// Genuine assertion, not merely key presence (see the fix note on
|
||||
// INIT_CASES above): the seeded project has a real "01-stub" phase
|
||||
// directory, so the phase MUST actually resolve. A silently-dropped
|
||||
// phase argument still has a `phase_found` key (value `false`) — key
|
||||
// presence alone would pass on that defect.
|
||||
assert.strictEqual(
|
||||
parsed.phase_found,
|
||||
true,
|
||||
`${label}: phase "01-stub" must actually resolve (phase_found:true), got: ${JSON.stringify(parsed.phase_found)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test(`${label} returns parseable JSON with bare project (no config at all)`, () => {
|
||||
|
||||
@@ -577,7 +577,13 @@ describe('regressions', () => {
|
||||
assert.strictEqual(seen.getter, 'function');
|
||||
assert.strictEqual(seen.failFast, 'sdk_fail_fast', 'the literal must survive moving to cli-exit');
|
||||
assert.strictEqual(seen.frozen, true);
|
||||
assert.strictEqual(seen.reasonCount, 23, 'ERROR_REASON must keep all 23 members');
|
||||
// #3884 (ADR-3473 §8.4) legitimately added two new codes —
|
||||
// PICK_FIELD_ABSENT and PICK_OUTPUT_NOT_JSON — for the `--pick`
|
||||
// absence contract (see .gsd/phase/feat-3884-failure-is-a-value/40-design.md
|
||||
// rows B6/B11). 23 -> 25 is an intentional, documented growth of the
|
||||
// enum, not drift; bump the golden count rather than treat this as a
|
||||
// Hyrum violation.
|
||||
assert.strictEqual(seen.reasonCount, 25, 'ERROR_REASON must keep all 25 members (23 + #3884 PICK_FIELD_ABSENT/PICK_OUTPUT_NOT_JSON)');
|
||||
assert.ok(
|
||||
seen.keys.includes('SDK_FAIL_FAST'),
|
||||
`ERROR_REASON must still include SDK_FAIL_FAST, got: ${JSON.stringify(seen.keys)}`,
|
||||
|
||||
@@ -1,93 +1,115 @@
|
||||
'use strict';
|
||||
|
||||
const { test } = require('node:test');
|
||||
const { test, describe } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const {
|
||||
parseNamedArgs,
|
||||
parseMultiwordArg,
|
||||
} = require('../gsd-core/bin/lib/command-arg-projection.cjs');
|
||||
const fc = require('./helpers/fast-check-setup.cjs');
|
||||
const { createTempProject, cleanup } = require('./helpers.cjs');
|
||||
const { runCli } = require('./helpers/cli-negative.cjs');
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// parseNamedArgs — behavior-lock tests (green before AND after the #312 fix)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
test('value flag with valid value', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--name', 'foo'], ['name']),
|
||||
{ name: 'foo' }
|
||||
);
|
||||
const result = parseNamedArgs(['--name', 'foo'], { valueFlags: ['name'], positionals: 0 });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { name: 'foo' } });
|
||||
});
|
||||
|
||||
test('value flag followed by another flag (value rejected)', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--name', '--other'], ['name']),
|
||||
{ name: null }
|
||||
);
|
||||
// Corrected after the first full verification run: a value flag whose next
|
||||
// token is another flag is NOT an error (see the "strict argv" describe
|
||||
// block below, valueFlagFollowedByAnotherFlagResolvesToNullNotAnError) — it
|
||||
// resolves to `null` and the cursor advances by 1 so the following token is
|
||||
// validated on its own merits. `--other` is deliberately left undeclared
|
||||
// here since this row tests extraction only; `positionals: 'rest'` skips
|
||||
// the unrelated unknown-flag validation.
|
||||
test('value flag followed by another flag resolves to null, not rejected', () => {
|
||||
const result = parseNamedArgs(['--name', '--other'], { valueFlags: ['name'], positionals: 'rest' });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { name: null } });
|
||||
});
|
||||
|
||||
// Corrected after the first full verification run: a value flag with no
|
||||
// following token at all resolves to `null`, not an error — see the
|
||||
// "strict argv" describe block below.
|
||||
test('value flag at end of array (no following token)', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--name'], ['name']),
|
||||
{ name: null }
|
||||
);
|
||||
const result = parseNamedArgs(['--name'], { valueFlags: ['name'], positionals: 0 });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { name: null } });
|
||||
});
|
||||
|
||||
test('value flag absent from args', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--x', 'y'], ['name']),
|
||||
{ name: null }
|
||||
);
|
||||
// The original 'value flag absent from args' row passed `['--x', 'y']` with
|
||||
// only `name` declared. Under strict mode `--x` is itself an unknown flag —
|
||||
// split into two rows so neither original intent (an undeclared flag is
|
||||
// null when TRULY absent; `--x` is rejected) is silently dropped.
|
||||
test('absent declared flag resolves to null (not an error)', () => {
|
||||
const result = parseNamedArgs([], { valueFlags: ['name'], positionals: 0 });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { name: null } });
|
||||
});
|
||||
|
||||
test('an undeclared flag token is rejected, not silently ignored', () => {
|
||||
const result = parseNamedArgs(['--x', 'y'], { valueFlags: ['name'], positionals: 0 });
|
||||
assert.strictEqual(result.ok, false);
|
||||
assert.strictEqual(result.kind, 'InvalidArgs');
|
||||
assert.strictEqual(result.arg, '--x');
|
||||
});
|
||||
|
||||
test('boolean flag present', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--write'], [], ['write']),
|
||||
{ write: true }
|
||||
);
|
||||
const result = parseNamedArgs(['--write'], { booleanFlags: ['write'], positionals: 0 });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { write: true } });
|
||||
});
|
||||
|
||||
test('boolean flag absent', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs([], [], ['write']),
|
||||
{ write: false }
|
||||
);
|
||||
const result = parseNamedArgs([], { booleanFlags: ['write'], positionals: 0 });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { write: false } });
|
||||
});
|
||||
|
||||
// Negative space N4: a repeated flag is not an unknown token — first
|
||||
// occurrence still wins, and each occurrence is itself a well-formed
|
||||
// flag+value pair, so strict validation still passes.
|
||||
test('first-occurrence-wins: duplicate value flag uses first index', () => {
|
||||
// Locks the indexOf-first semantics that the Map must preserve (#312)
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--name', 'a', '--name', 'b'], ['name']),
|
||||
{ name: 'a' }
|
||||
);
|
||||
const result = parseNamedArgs(['--name', 'a', '--name', 'b'], { valueFlags: ['name'], positionals: 0 });
|
||||
assert.deepStrictEqual(result, { ok: true, data: { name: 'a' } });
|
||||
});
|
||||
|
||||
test('mixed multiple flags (the O(flags*argv) case)', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--a', '1', '--flag', '--b', '2'], ['a', 'b'], ['flag']),
|
||||
{ a: '1', b: '2', flag: true }
|
||||
const result = parseNamedArgs(
|
||||
['--a', '1', '--flag', '--b', '2'],
|
||||
{ valueFlags: ['a', 'b'], booleanFlags: ['flag'], positionals: 0 },
|
||||
);
|
||||
assert.deepStrictEqual(result, { ok: true, data: { a: '1', b: '2', flag: true } });
|
||||
});
|
||||
|
||||
test('empty args with multiple declared flags', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs([], ['name', 'path'], ['verbose', 'dry-run']),
|
||||
{ name: null, path: null, verbose: false, 'dry-run': false }
|
||||
const result = parseNamedArgs(
|
||||
[],
|
||||
{ valueFlags: ['name', 'path'], booleanFlags: ['verbose', 'dry-run'], positionals: 0 },
|
||||
);
|
||||
assert.deepStrictEqual(result, {
|
||||
ok: true,
|
||||
data: { name: null, path: null, verbose: false, 'dry-run': false },
|
||||
});
|
||||
});
|
||||
|
||||
test('value flag value undefined via array boundary', () => {
|
||||
// --count is last token; args[idx+1] is undefined — must return null
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--other', 'x', '--count'], ['count']),
|
||||
{ count: null }
|
||||
// Corrected after the first full verification run: a value flag exhausted
|
||||
// by the array boundary resolves to `null`, not InvalidArgs — including
|
||||
// when it is preceded by another well-formed flag+value pair.
|
||||
test('value flag at end of argv resolves to null even when preceded by another flag', () => {
|
||||
const result = parseNamedArgs(
|
||||
['--other', 'x', '--count'],
|
||||
{ valueFlags: ['other', 'count'], positionals: 0 },
|
||||
);
|
||||
assert.deepStrictEqual(result, { ok: true, data: { other: 'x', count: null } });
|
||||
});
|
||||
|
||||
test('boolean flag does not clobber an already-set value-flag key when names differ', () => {
|
||||
assert.deepStrictEqual(
|
||||
parseNamedArgs(['--msg', 'hello', '--verbose'], ['msg'], ['verbose']),
|
||||
{ msg: 'hello', verbose: true }
|
||||
const result = parseNamedArgs(
|
||||
['--msg', 'hello', '--verbose'],
|
||||
{ valueFlags: ['msg'], booleanFlags: ['verbose'], positionals: 0 },
|
||||
);
|
||||
assert.deepStrictEqual(result, { ok: true, data: { msg: 'hello', verbose: true } });
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -122,6 +144,282 @@ test('parseMultiwordArg: flag at end of array with no tokens returns null', () =
|
||||
);
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// parseNamedArgs — strict argv (#3358, ADR-3473 §8.4)
|
||||
//
|
||||
// New shape: parseNamedArgs(args, spec) where
|
||||
// spec = { valueFlags?: string[], booleanFlags?: string[], positionals: number | 'rest' }
|
||||
// returning { ok: true, data } | { ok: false, kind: 'InvalidArgs', arg, reason }.
|
||||
//
|
||||
// TODAY (measured on this tree): the function ignores this shape entirely —
|
||||
// its real signature is still (args, valueFlags = [], booleanFlags = []), so
|
||||
// passing a spec OBJECT as the second positional argument makes
|
||||
// `for (const flag of valueFlags)` iterate a non-iterable plain object,
|
||||
// throwing `TypeError: valueFlags is not iterable` before any of these rows
|
||||
// can even reach their assertions. Every row below therefore fails against
|
||||
// the current tree — either via that uncaught throw, or (for the two legacy
|
||||
// rows) because `assert.throws` finds nothing thrown at all.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe('parseNamedArgs — strict argv (#3358, ADR-3473 §8.4)', () => {
|
||||
test('valueFlagWithValueResolvesOk', () => {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'begin-phase', '--phase', '3'],
|
||||
{ valueFlags: ['phase', 'name', 'plans'], positionals: 2 },
|
||||
);
|
||||
assert.deepStrictEqual(result, { ok: true, data: { phase: '3', name: null, plans: null } });
|
||||
});
|
||||
|
||||
// Corrected after the first full verification run: ADR-3473 §8.4 mandates
|
||||
// rejecting *unrecognized* and *positional* tokens — it says nothing about
|
||||
// a value flag whose value is missing or flag-shaped. Treating that as an
|
||||
// error was an over-implementation (not the ADR's rule) and it broke the
|
||||
// long-standing, deliberately-recorded `null` contract exercised by
|
||||
// tests/init.test.cjs emptyPrdValueIsFalsyAndTreatedAsAbsent (row B5) and
|
||||
// tests/section-manifest-init-facts.test.cjs "flag-shaped value (--prd
|
||||
// --weird)". A value flag whose next token is absent or flag-shaped
|
||||
// resolves to `null` and is NOT an error; the cursor advances by 1 so the
|
||||
// following flag token is validated on its own merits on the next
|
||||
// iteration.
|
||||
test('valueFlagFollowedByAnotherFlagResolvesToNullNotAnError', () => {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'planned-phase', '--phase', '--name', 'x'],
|
||||
{ valueFlags: ['phase', 'name'], positionals: 2 },
|
||||
);
|
||||
assert.deepStrictEqual(result, { ok: true, data: { phase: null, name: 'x' } });
|
||||
});
|
||||
|
||||
test('unknownFlagIsRejectedAndListsAcceptedFlags', () => {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'begin-phase', '--bogus', 'x'],
|
||||
{ valueFlags: ['phase', 'name'], positionals: 2 },
|
||||
);
|
||||
assert.strictEqual(result.ok, false);
|
||||
assert.strictEqual(result.kind, 'InvalidArgs');
|
||||
assert.strictEqual(result.arg, '--bogus');
|
||||
assert.match(result.reason, /phase/i, 'reason must name an accepted flag');
|
||||
assert.match(result.reason, /name/i, 'reason must name an accepted flag');
|
||||
});
|
||||
|
||||
// #3358: the exact call site shape (`state planned-phase 3`, no --phase)
|
||||
// that let a stray positional silently drop and overwrite STATE.md's
|
||||
// previously-current phase block. See tests/state.test.cjs
|
||||
// positionalPlannedPhaseLeavesStateMdUntouched_3358 for the consumer-output
|
||||
// identity row this defect is actually observed through.
|
||||
test('unexpectedPositionalIsRejected_3358', () => {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'planned-phase', '3'],
|
||||
{ valueFlags: ['phase', 'name', 'plans'], positionals: 2 },
|
||||
);
|
||||
assert.strictEqual(result.ok, false);
|
||||
assert.strictEqual(result.arg, '3');
|
||||
assert.match(result.reason, /positional/i);
|
||||
});
|
||||
|
||||
// Negative space N3: a positional the caller declares (and reads itself
|
||||
// via args[2]) must never be flagged as unexpected.
|
||||
test('declaredPositionalIsNotFlagged', () => {
|
||||
const result = parseNamedArgs(
|
||||
['init', 'execute-phase', '01', '--tdd'],
|
||||
{ booleanFlags: ['tdd'], positionals: 3 },
|
||||
);
|
||||
assert.strictEqual(result.ok, true);
|
||||
assert.strictEqual(result.data.tdd, true);
|
||||
});
|
||||
|
||||
// Required boundary triple over a fixed argv: positionals one short of the
|
||||
// token's index rejects it; positionals at or past that index accepts it.
|
||||
test('positionalBoundaryAtNMinus1_N_NPlus1', () => {
|
||||
const argv = ['state', 'complete-phase', '3'];
|
||||
|
||||
const nMinus1 = parseNamedArgs(argv, { valueFlags: ['phase'], positionals: 2 });
|
||||
assert.strictEqual(nMinus1.ok, false);
|
||||
assert.strictEqual(nMinus1.arg, '3');
|
||||
|
||||
const atN = parseNamedArgs(argv, { valueFlags: ['phase'], positionals: 3 });
|
||||
assert.strictEqual(atN.ok, true);
|
||||
|
||||
const nPlus1 = parseNamedArgs(argv, { valueFlags: ['phase'], positionals: 4 });
|
||||
assert.strictEqual(nPlus1.ok, true);
|
||||
});
|
||||
|
||||
// Negative space N5: a value beginning with a single `-` (a negative
|
||||
// number) is not mistaken for a flag. The strict pass must reuse the same
|
||||
// `startsWith('--')` predicate the permissive parser already gets right.
|
||||
test('negativeNumberValueIsNotTreatedAsFlag', () => {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'record-metric', '--plans', '-1'],
|
||||
{ valueFlags: ['plans'], positionals: 2 },
|
||||
);
|
||||
assert.strictEqual(result.ok, true);
|
||||
assert.strictEqual(result.data.plans, '-1');
|
||||
});
|
||||
|
||||
// Negative space N6: `init quick <description>` consumes everything after
|
||||
// the family/subcommand as free text — undeclared-flag rejection must be
|
||||
// disabled for this documented shape, not accidentally re-enabled.
|
||||
test('restPositionalsAcceptFreeTextIncludingUnknownFlags', () => {
|
||||
const result = parseNamedArgs(
|
||||
['init', 'quick', 'add', 'a', '--dry-run', 'option'],
|
||||
{ positionals: 'rest' },
|
||||
);
|
||||
assert.strictEqual(result.ok, true);
|
||||
});
|
||||
|
||||
// ADR-3473 Decision 2: both ends of this seam are gsd-core's own source. A
|
||||
// stale call site using the legacy 3-positional-argument shape must throw
|
||||
// loudly rather than silently destructuring undefined off a Result.
|
||||
test('legacyArrayArgumentShapeThrows', () => {
|
||||
assert.throws(() => parseNamedArgs(['--a', '1'], ['a']));
|
||||
});
|
||||
|
||||
test('missingSpecThrows', () => {
|
||||
assert.throws(() => parseNamedArgs(['--a', '1']));
|
||||
});
|
||||
|
||||
test('bareDoubleDashIsRejectedNotCrashing', () => {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'planned-phase', '--'],
|
||||
{ valueFlags: ['phase'], positionals: 2 },
|
||||
);
|
||||
assert.strictEqual(result.ok, false);
|
||||
assert.strictEqual(result.arg, '--');
|
||||
});
|
||||
|
||||
// A hostile positional must be rejected as opaque data — never executed,
|
||||
// interpolated, or otherwise treated as anything but a literal string that
|
||||
// fails validation and is echoed back verbatim in `arg`.
|
||||
test('hostileTokensAreRejectedAsOpaqueData', () => {
|
||||
const hostileTokens = [';', '$(id)', 'line1\nline2', 'a b'];
|
||||
for (const token of hostileTokens) {
|
||||
const result = parseNamedArgs(
|
||||
['state', 'planned-phase', token],
|
||||
{ valueFlags: ['phase'], positionals: 2 },
|
||||
);
|
||||
assert.strictEqual(result.ok, false, `hostile token should be rejected: ${JSON.stringify(token)}`);
|
||||
assert.strictEqual(result.arg, token);
|
||||
}
|
||||
});
|
||||
|
||||
// Required fast-check property (parsers get one): for any argv built only
|
||||
// from declared flags and their well-formed (non-`--`-prefixed) values,
|
||||
// with positionals:0, the result is ok:true and every declared key
|
||||
// resolves to exactly the value it was given.
|
||||
test('fc: wellFormedArgvAlwaysParsesOk', () => {
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.uniqueArray(
|
||||
fc.constantFrom('phase', 'name', 'plans', 'summary', 'text'),
|
||||
{ minLength: 1, maxLength: 5 },
|
||||
).chain((flags) => fc.tuple(
|
||||
fc.constant(flags),
|
||||
fc.array(
|
||||
fc.stringMatching(/^[a-zA-Z0-9_]+$/).filter((s) => s.length > 0),
|
||||
{ minLength: flags.length, maxLength: flags.length },
|
||||
),
|
||||
)),
|
||||
([flags, values]) => {
|
||||
const argv = [];
|
||||
for (let i = 0; i < flags.length; i++) {
|
||||
argv.push(`--${flags[i]}`, values[i]);
|
||||
}
|
||||
const result = parseNamedArgs(argv, { valueFlags: flags, positionals: 0 });
|
||||
assert.strictEqual(result.ok, true);
|
||||
for (let i = 0; i < flags.length; i++) {
|
||||
assert.strictEqual(result.data[flags[i]], values[i]);
|
||||
}
|
||||
},
|
||||
),
|
||||
);
|
||||
});
|
||||
|
||||
// Required fast-check property, negative side: for any argv containing at
|
||||
// least one token past the boundary that is neither a declared flag nor a
|
||||
// declared flag's value, the result is ok:false.
|
||||
test('fc: anyUndeclaredTokenAlwaysRejects', () => {
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.constantFrom('phase', 'name', 'plans'),
|
||||
fc.stringMatching(/^[a-zA-Z0-9_]+$/).filter((s) => s.length > 0),
|
||||
(declaredFlag, undeclaredToken) => {
|
||||
const argv = [`--${declaredFlag}`, 'val', undeclaredToken];
|
||||
const result = parseNamedArgs(argv, { valueFlags: [declaredFlag], positionals: 0 });
|
||||
assert.strictEqual(result.ok, false);
|
||||
},
|
||||
),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// formatDiagnosticToken (io.cjs) — untrusted-token diagnostic escaping.
|
||||
//
|
||||
// Adversarial review finding (isolated review, verified live): a token
|
||||
// embedded verbatim in a plain-text "Error: <message>" diagnostic can forge
|
||||
// a second stderr line beginning "Error:" by smuggling its own "\n". Repro
|
||||
// on this tree BEFORE the fix:
|
||||
// $ node gsd-tools.cjs query state.planned-phase "foo\nError: forged second line"
|
||||
// Error: unexpected positional argument "foo
|
||||
// Error: forged second line"
|
||||
// These tests spawn the real CLI (the vulnerability is about the literal
|
||||
// bytes on stderr, not `parseNamedArgs`'s return value) through the exact
|
||||
// call shape the finding used: `query state.planned-phase <hostile token>`
|
||||
// hits the "unexpected positional argument" reason string, which embeds the
|
||||
// token directly. Asserts on the RAW stderr string (not trimmed) — a
|
||||
// trimmed assertion would hide a leading/trailing forged blank line.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe('formatDiagnosticToken escapes untrusted tokens in plain-text diagnostics', () => {
|
||||
const HOSTILE_TOKENS = [
|
||||
['embedded newline forging a second Error: line', 'foo\nError: forged second line'],
|
||||
['embedded double quote', 'foo"bar'],
|
||||
['embedded C0 control character', 'foo\x07bar'],
|
||||
];
|
||||
|
||||
for (const [label, token] of HOSTILE_TOKENS) {
|
||||
test(`unexpected-positional diagnostic stays single-line for a token with ${label}`, () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runCli(['query', 'state.planned-phase', token], { cwd: tmpDir, jsonErrors: false });
|
||||
assert.notStrictEqual(result.status, 0, 'a rejected positional must exit non-zero');
|
||||
const rawStderr = result.stderr;
|
||||
const nonEmptyLines = rawStderr.split('\n').filter((l) => l.length > 0);
|
||||
assert.strictEqual(
|
||||
nonEmptyLines.length, 1,
|
||||
`expected exactly one non-empty stderr line, got raw stderr: ${JSON.stringify(rawStderr)}`,
|
||||
);
|
||||
assert.match(nonEmptyLines[0], /^Error: /);
|
||||
const errorPrefixedLineCount = rawStderr.split('\n').filter((l) => l.startsWith('Error:')).length;
|
||||
assert.strictEqual(errorPrefixedLineCount, 1, 'the hostile token must not forge a second "Error:" line');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Same repro shape, but through the "unknown flag" reason string (the
|
||||
// second of the three sites the finding named) — a hostile token that
|
||||
// itself starts with "--" so it is walked as a flag, not a positional.
|
||||
test('unknown-flag diagnostic stays single-line for a hostile flag-shaped token', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runCli(
|
||||
['query', 'state.planned-phase', '--bogus\nError: forged', 'x'],
|
||||
{ cwd: tmpDir, jsonErrors: false },
|
||||
);
|
||||
assert.notStrictEqual(result.status, 0);
|
||||
const rawStderr = result.stderr;
|
||||
const nonEmptyLines = rawStderr.split('\n').filter((l) => l.length > 0);
|
||||
assert.strictEqual(
|
||||
nonEmptyLines.length, 1,
|
||||
`expected exactly one non-empty stderr line, got raw stderr: ${JSON.stringify(rawStderr)}`,
|
||||
);
|
||||
assert.match(nonEmptyLines[0], /^Error: unknown flag/);
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Folded from tests/bug-3431-debug-command-yaml.test.cjs — consolidation epic #1969 (B3 #1972)
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
// Reads .md/.json/.yml product files whose deployed text IS what the
|
||||
// runtime loads — testing text content tests the deployed contract.
|
||||
//
|
||||
// docs-guard-exempt: #3884 — the docs/CLI-TOOLS.md:736 citation below is an
|
||||
// explanatory comment pointing at documented CLI shape, not a read target;
|
||||
// this file performs unrelated filesystem reads (STATE.md, phase/plan
|
||||
// fixtures under .planning/) and never reads any docs/ file.
|
||||
|
||||
/**
|
||||
* GSD Tools Tests - Concurrency Safety
|
||||
@@ -537,16 +542,38 @@ must_haves:
|
||||
`
|
||||
);
|
||||
|
||||
// #3884 (ADR-3473 §8.4): `frontmatter get <file> <field>` is not a real
|
||||
// form — the documented shape is `frontmatter get <file> [--field key]`
|
||||
// (docs/CLI-TOOLS.md:736). Under the pre-#3884 permissive parser the bare
|
||||
// "must_haves" positional was silently dropped, `field` resolved to
|
||||
// null, and cmdFrontmatterGet dumped the WHOLE frontmatter object — the
|
||||
// test's original `result.output.includes('acceptance')` branch passed
|
||||
// only because the full dump happens to contain that substring, not
|
||||
// because field selection ever worked. `cmdFrontmatterGet` never calls
|
||||
// `parseMustHavesBlock` (that WARNING is only emitted by other
|
||||
// consumers), so the WARNING branch of the old assertion could never
|
||||
// fire through this command either. Corrected to the real `--field`
|
||||
// form and strengthened to assert on the actual, field-scoped payload.
|
||||
const result = runGsdTools(
|
||||
['frontmatter', 'get', path.join(planDir, '01-01-PLAN.md'), 'must_haves'],
|
||||
['frontmatter', 'get', path.join(planDir, '01-01-PLAN.md'), '--field', 'must_haves'],
|
||||
tmpDir
|
||||
);
|
||||
|
||||
const stderr = result.error || '';
|
||||
assert.ok(
|
||||
stderr.includes('WARNING') && stderr.includes('must_haves') ||
|
||||
result.output.includes('acceptance'),
|
||||
`Expected WARNING about must_haves parse or valid parse result. stderr: ${stderr}, stdout: ${result.output}`
|
||||
assert.ok(result.success, `frontmatter get --field must_haves failed: ${result.error}`);
|
||||
const parsed = JSON.parse(result.output);
|
||||
assert.deepStrictEqual(
|
||||
Object.keys(parsed),
|
||||
['must_haves'],
|
||||
`--field must_haves must scope the output to only that field, got keys: ${Object.keys(parsed).join(', ')}`,
|
||||
);
|
||||
// Dash-less list items under a YAML mapping key fold into a single plain
|
||||
// scalar string, not an array — this is the actual "0 items" parse
|
||||
// hazard the test's title names, surfaced directly rather than via a
|
||||
// WARNING this command path never emits.
|
||||
assert.strictEqual(
|
||||
typeof parsed.must_haves.acceptance,
|
||||
'string',
|
||||
`bare-content (no dash prefix) must_haves.acceptance must parse as a scalar string, not a list, got: ${JSON.stringify(parsed.must_haves.acceptance)}`,
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -667,12 +667,20 @@ describe('#1778: thread workflow uses the 1.6 named-flag frontmatter.set form',
|
||||
'named-flag form must write status: resolved into the file',
|
||||
);
|
||||
|
||||
// Pre-1.6 positional form — must fail with the documented message and NOT mutate.
|
||||
// Pre-1.6 positional form — must fail and NOT mutate.
|
||||
//
|
||||
// #3884 (ADR-3473 §8.4): the strict parser now rejects the stray
|
||||
// positional tokens ("status", "resolved") BEFORE cmdFrontmatterSet's own
|
||||
// "file, field, and value required" guard ever runs, so the error text
|
||||
// changed. The behavioral contract this test guards — fails, and does
|
||||
// NOT mutate the file — is unchanged and, if anything, strengthened (the
|
||||
// rejection now happens earlier, at argv-parsing time, not deep inside
|
||||
// the command).
|
||||
const badFile = writeTempFile('---\nstatus: open\nupdated: "2025-01-01"\n---\n\n# thread body\n');
|
||||
const bad = runGsdTools(['frontmatter', 'set', badFile, 'status', 'resolved']);
|
||||
assert.ok(!bad.success, 'positional form must fail (it is the bug being guarded against)');
|
||||
assert.ok(
|
||||
(bad.error + bad.output).includes('file, field, and value required'),
|
||||
(bad.error + bad.output).includes('unexpected positional argument'),
|
||||
`positional form must error with the documented message; got:\n${bad.error}${bad.output}`,
|
||||
);
|
||||
assert.strictEqual(
|
||||
|
||||
@@ -311,38 +311,49 @@ describe('init.debug --diagnose forwarding and hostile argv (matrix §C)', () =>
|
||||
assert.equal(output.diagnose, true);
|
||||
});
|
||||
|
||||
test('ignores an unrecognized flag (row C4)', () => {
|
||||
test('rejects an unrecognized flag with the flag named (row C4)', () => {
|
||||
// ADR-3473 §8.4 (Bucket-B correction): "`parseNamedArgs` rejects
|
||||
// unrecognized ... tokens with a non-zero exit — it is called by agents
|
||||
// that will drift again." An unrecognized flag is exactly the mandated
|
||||
// rejection, not a thing to silently absorb.
|
||||
const result = runGsdTools(['init', 'debug', '--nope'], tmpDir);
|
||||
assert.ok(result.success, `an unknown flag must not fail the command: ${result.error}`);
|
||||
const output = JSON.parse(result.output);
|
||||
assert.equal(output.diagnose, false);
|
||||
assert.equal(result.success, false, 'an unknown flag must now fail the command');
|
||||
assert.match(result.error, /--nope/, 'the rejection must name the offending flag');
|
||||
});
|
||||
|
||||
test('survives a flag-shaped trailing token (row C5)', () => {
|
||||
test('rejects a flag-shaped trailing token, naming it (row C5)', () => {
|
||||
const result = runGsdTools(['init', 'debug', '--diagnose', '--weird'], tmpDir);
|
||||
assert.ok(result.success, `must not crash on a flag-shaped token: ${result.error}`);
|
||||
assert.equal(JSON.parse(result.output).diagnose, true);
|
||||
assert.equal(result.success, false, 'an unrecognized flag-shaped token must now fail the command');
|
||||
assert.match(result.error, /--weird/, 'the rejection must name the offending flag');
|
||||
});
|
||||
|
||||
test('does not interpolate shell metacharacters (row C6)', () => {
|
||||
test('does not interpolate shell metacharacters even though the hostile positional is now rejected (row C6)', () => {
|
||||
const canary = path.join(tmpDir, 'PWNED');
|
||||
const hostile = `; touch ${canary}; $(touch ${canary}) \`touch ${canary}\` && touch ${canary}`;
|
||||
|
||||
const result = runGsdTools(['init', 'debug', hostile], tmpDir);
|
||||
|
||||
assert.ok(result.success, `hostile argv must not fail the command: ${result.error}`);
|
||||
// §8.4 now rejects this as an unexpected positional argument (exit
|
||||
// non-zero) instead of silently absorbing it — that is at least as safe
|
||||
// as the old accept-and-ignore behavior. The canary assertion is the
|
||||
// actual point of this test and is unchanged: no shell ever touches this
|
||||
// string, whether the token is accepted or rejected.
|
||||
assert.equal(result.success, false, 'a stray positional argument must now fail the command');
|
||||
assert.equal(fs.existsSync(canary), false, 'no shell interpolation of an attacker-controlled argument');
|
||||
assert.equal(result.output.includes(' at '), false, 'no stack trace in non-debug output');
|
||||
assert.equal(result.error.includes(' at '), false, 'no stack trace in non-debug output');
|
||||
});
|
||||
|
||||
test('survives a very long argument (row C7/C8)', () => {
|
||||
test('rejects a very long or unicode positional argument, not just tolerates it (row C7/C8)', () => {
|
||||
// Classified as the same §8.4 unexpected-positional-argument shape as
|
||||
// C6: `init debug` declares no positionals, so any bare token here is a
|
||||
// stray positional and must now be rejected rather than silently
|
||||
// absorbed.
|
||||
const long = 'x'.repeat(8192);
|
||||
const unicode = 'ünïcødé-🐛-测试';
|
||||
|
||||
for (const arg of [long, unicode]) {
|
||||
const result = runGsdTools(['init', 'debug', arg], tmpDir);
|
||||
assert.ok(result.success, `argument of length ${arg.length} must not crash: ${result.error}`);
|
||||
assert.equal(JSON.parse(result.output).diagnose, false);
|
||||
assert.equal(result.success, false, `argument of length ${arg.length} must now fail the command, not crash`);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -11,6 +11,7 @@ const { runGsdTools, cleanup, absPlanningPath, TOOLS_PATH, parseFrontmatter } =
|
||||
const { createFixture, seedPhase } = require('./fixtures/index.cjs');
|
||||
const { createTempProject, createTempDir } = require('./helpers.cjs');
|
||||
const { executionContextRefs } = require('../scripts/command-contract-helpers.cjs');
|
||||
const { escapeRegex } = require('../gsd-core/bin/lib/pattern.cjs');
|
||||
|
||||
/**
|
||||
* #3188: write the canonical flat planning docs so an init-query "present" test
|
||||
@@ -3648,31 +3649,61 @@ describe('init section manifest', () => {
|
||||
});
|
||||
|
||||
test('handlesMalformedWaveAssignments', (t) => {
|
||||
// Documented handling (decision made during this dispatch): parseNamedArgs's
|
||||
// booleanFlags check is an EXACT token match against the literal "--wave" —
|
||||
// "--wave=" and "--wave==1" are different literal tokens, so neither activates
|
||||
// the flag. No crash either way; this is the same exact-match discipline that
|
||||
// keeps "--waves"/"--wave-filter" from false-activating (row 52).
|
||||
// Corrected after the first full verification run: neither --wave= nor
|
||||
// --wave==1 is a documented or shipped token (commands/gsd/execute-phase.md,
|
||||
// gsd-core/workflows/execute-phase.md, and the docs tree all only ever
|
||||
// emit the space-separated --wave N form) — each is an exact, distinct,
|
||||
// undeclared flag token, so ADR-3473 §8.4 mandates rejecting it outright
|
||||
// rather than silently letting it fall through unrecognized. Exit 1, and
|
||||
// — same exact-match discipline that keeps "--waves"/"--wave-filter"
|
||||
// from false-activating (row 52) — the rejection must name the
|
||||
// malformed token itself, proving it was never coerced into activating
|
||||
// --wave.
|
||||
const dir = seedSinglePhaseProject(t, 'gsd-e50-');
|
||||
for (const token of ['--wave=', '--wave==1']) {
|
||||
const body = parseOkJson(runExecutePhase(['1', token], dir), `malformed-wave:${token}`);
|
||||
assert.ok(!body.section_manifest.included.includes('partial-wave'), `"${token}" must not activate --wave`);
|
||||
const result = runExecutePhase(['1', token], dir);
|
||||
assert.equal(result.status, 1, `malformed-wave:${token}: expected exit 1, got ${result.status}`);
|
||||
const err = JSON.parse(result.stderr);
|
||||
assert.match(err.message, new RegExp(escapeRegex(token)), `"${token}" must be named as the unknown flag, proving it did not activate --wave`);
|
||||
}
|
||||
});
|
||||
|
||||
test('doesNotConsumeFollowingFlagAsWaveValue', (t) => {
|
||||
// Unit-level: --wave is an optionalValueFlags entry (#2932's `--wave N`
|
||||
// shape) — its cursor never swallows a following flag-shaped token as
|
||||
// its value; it advances by 1, not 2, leaving --weird for its own
|
||||
// validation. Assert the extraction directly rather than through the
|
||||
// full CLI, since --weird's own (correct) rejection below makes the
|
||||
// manifest body unreachable.
|
||||
const { parseNamedArgs } = require('../gsd-core/bin/lib/command-arg-projection.cjs');
|
||||
const extracted = parseNamedArgs(['--wave', '--weird'], { optionalValueFlags: ['wave'], positionals: 'rest' });
|
||||
assert.strictEqual(extracted.ok, true);
|
||||
assert.strictEqual(extracted.data.wave, true, '--wave must resolve to present (true), not be starved by the following token');
|
||||
|
||||
// Integration: --weird is a genuinely undeclared flag on execute-phase,
|
||||
// so ADR-3473 §8.4 mandates rejecting it — exit 1, not the old exit-0
|
||||
// "ignored" shape. The rejection naming "--weird" (not "--wave") is
|
||||
// itself proof --wave did not consume it as a value.
|
||||
const dir = seedSinglePhaseProject(t, 'gsd-e51-');
|
||||
const body = parseOkJson(runExecutePhase(['1', '--wave', '--weird'], dir), 'wave-then-weird');
|
||||
// Boolean-flag semantics: --wave never reads a following token as its value,
|
||||
// so an adjacent flag-shaped token is simply ignored, not eaten or mis-parsed.
|
||||
assert.deepStrictEqual(body.section_manifest.included, ['partial-wave']);
|
||||
const result = runExecutePhase(['1', '--wave', '--weird'], dir);
|
||||
assert.equal(result.status, 1, `wave-then-weird: expected exit 1, got ${result.status}`);
|
||||
const err = JSON.parse(result.stderr);
|
||||
assert.match(err.message, /--weird/, 'the unknown-flag rejection must name --weird, proving --wave did not consume it as its value');
|
||||
});
|
||||
|
||||
test('nearMissFlagNamesDoNotActivateWave', (t) => {
|
||||
// Corrected after the first full verification run: neither "--waves"
|
||||
// nor "--wave-filter" is documented or shipped for execute-phase, so
|
||||
// each is a genuinely undeclared flag — ADR-3473 §8.4 mandates
|
||||
// rejecting it (exit 1), not silently ignoring it. The rejection
|
||||
// naming the near-miss token itself is what proves it never
|
||||
// false-activated --wave.
|
||||
const dir = seedSinglePhaseProject(t, 'gsd-e52-');
|
||||
for (const flag of ['--waves', '--wave-filter']) {
|
||||
const body = parseOkJson(runExecutePhase(['1', flag], dir), `near-miss:${flag}`);
|
||||
assert.ok(!body.section_manifest.included.includes('partial-wave'), `"${flag}" must not activate --wave`);
|
||||
const result = runExecutePhase(['1', flag], dir);
|
||||
assert.equal(result.status, 1, `near-miss:${flag}: expected exit 1, got ${result.status}`);
|
||||
const err = JSON.parse(result.stderr);
|
||||
assert.match(err.message, new RegExp(escapeRegex(flag)), `"${flag}" must be named as the unknown flag, proving it did not activate --wave`);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -452,6 +452,13 @@ describe('bug #3600: milestone phase filter understands project-code-prefixed di
|
||||
fs.mkdirSync(path.join(tmpDir, '.planning', 'phases', name), { recursive: true });
|
||||
}
|
||||
|
||||
// #3884 (ADR-3473 §8.4): `--json` was never a real flag for `init
|
||||
// new-milestone` — `init` subcommands always emit a JSON bundle regardless
|
||||
// of any flag (the machine-readable-output flag is `--raw`, documented at
|
||||
// docs/CLI-TOOLS.md:30, not `--json`). Under the pre-#3884 permissive
|
||||
// parser the unrecognized token was silently dropped and the assertions
|
||||
// below never actually depended on it; the strict parser now rejects it.
|
||||
// Removed across this describe block's four call sites.
|
||||
test('init.new-milestone counts CK-NN-name dirs against numeric `Phase N:` headings', () => {
|
||||
writeConfig(tmpDir, { project_code: 'CK' });
|
||||
writeState(tmpDir, 'v1.0.0');
|
||||
@@ -464,7 +471,7 @@ describe('bug #3600: milestone phase filter understands project-code-prefixed di
|
||||
ensurePhaseDir(tmpDir, 'CK-01-discovery');
|
||||
ensurePhaseDir(tmpDir, 'CK-02-build');
|
||||
|
||||
const r = runGsdTools(['init', 'new-milestone', '--json'], tmpDir);
|
||||
const r = runGsdTools(['init', 'new-milestone'], tmpDir);
|
||||
assert.ok(r.success, `init new-milestone failed: ${r.error || r.output}`);
|
||||
const payload = JSON.parse(r.output);
|
||||
assert.strictEqual(payload.phase_dir_count, 2,
|
||||
@@ -480,7 +487,7 @@ describe('bug #3600: milestone phase filter understands project-code-prefixed di
|
||||
].join('\n'));
|
||||
ensurePhaseDir(tmpDir, '01-first');
|
||||
|
||||
const r = runGsdTools(['init', 'new-milestone', '--json'], tmpDir);
|
||||
const r = runGsdTools(['init', 'new-milestone'], tmpDir);
|
||||
assert.ok(r.success);
|
||||
assert.strictEqual(JSON.parse(r.output).phase_dir_count, 1);
|
||||
});
|
||||
@@ -495,7 +502,7 @@ describe('bug #3600: milestone phase filter understands project-code-prefixed di
|
||||
].join('\n'));
|
||||
ensurePhaseDir(tmpDir, 'PROJ-42');
|
||||
|
||||
const r = runGsdTools(['init', 'new-milestone', '--json'], tmpDir);
|
||||
const r = runGsdTools(['init', 'new-milestone'], tmpDir);
|
||||
assert.ok(r.success);
|
||||
assert.strictEqual(JSON.parse(r.output).phase_dir_count, 1,
|
||||
'PROJ-42 directory must still match Phase PROJ-42: via the custom-ID path');
|
||||
@@ -513,7 +520,7 @@ describe('bug #3600: milestone phase filter understands project-code-prefixed di
|
||||
ensurePhaseDir(tmpDir, 'CK-99-backlog');
|
||||
ensurePhaseDir(tmpDir, 'CK-100-future');
|
||||
|
||||
const r = runGsdTools(['init', 'new-milestone', '--json'], tmpDir);
|
||||
const r = runGsdTools(['init', 'new-milestone'], tmpDir);
|
||||
assert.ok(r.success);
|
||||
assert.strictEqual(JSON.parse(r.output).phase_dir_count, 1,
|
||||
'only CK-01-first should match Phase 1; CK-99 and CK-100 must be excluded');
|
||||
|
||||
@@ -7,7 +7,11 @@
|
||||
|
||||
const { test, describe } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const { runGsdTools } = require('./helpers.cjs');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
|
||||
const { seedPhase } = require('./fixtures/index.cjs');
|
||||
const { runCli } = require('./helpers/cli-negative.cjs');
|
||||
|
||||
// ─── --pick flag ─────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -24,10 +28,110 @@ describe('--pick flag', () => {
|
||||
assert.strictEqual(result.output, 'hello-world');
|
||||
});
|
||||
|
||||
test('returns empty string for missing field', () => {
|
||||
// #3365 / ADR-3473 §8.4 P6: an ABSENT field is a failure ("I could not
|
||||
// answer"), never a demotion to the empty answer at exit 0. This inverts
|
||||
// the old pinned assertion below (kept as a comment for the historical
|
||||
// record — measured on this tree, 2026-08-26, exit 0 + empty stdout):
|
||||
// const result = runGsdTools('generate-slug "test" --pick nonexistent');
|
||||
// assert.strictEqual(result.success, true);
|
||||
// assert.strictEqual(result.output, '');
|
||||
test('absentFieldExitsNonZero_3365', () => {
|
||||
const result = runGsdTools('generate-slug "test" --pick nonexistent');
|
||||
assert.strictEqual(result.success, true);
|
||||
assert.strictEqual(result.success, false, 'an absent --pick field must exit non-zero');
|
||||
assert.strictEqual(result.output, '');
|
||||
assert.match(result.error, /nonexistent/, 'stderr must name the requested field');
|
||||
});
|
||||
|
||||
// P2 (test matrix): a count of zero is a real value, not absence — this
|
||||
// must keep PASSING before and after the fix (the non-change half of #3365).
|
||||
test('zeroCountPrintsZeroAtExitZero', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runGsdTools('query phases.list --type summaries --pick count', tmpDir);
|
||||
assert.strictEqual(result.success, true);
|
||||
assert.strictEqual(result.output, '0');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// P4 (test matrix, negative space N1): a field present with an explicit
|
||||
// `null` value is an answer, not a failure — must keep PASSING before and
|
||||
// after the fix. Measured: `phases.list --type plans --pick phase_dir` on
|
||||
// the enumeration path (no --phase given) returns `phase_dir: null`.
|
||||
test('presentButNullIsEmptyAtExitZero', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runGsdTools('query phases.list --type plans --pick phase_dir', tmpDir);
|
||||
assert.strictEqual(result.success, true);
|
||||
assert.strictEqual(result.output, '');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// P10 (test matrix): required boundary triple over an array field of
|
||||
// known length N=3 (three seeded phase directories).
|
||||
test('arrayIndexBoundaryAtLenMinus1_Len_LenPlus1', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
seedPhase(tmpDir, '01-alpha');
|
||||
seedPhase(tmpDir, '02-beta');
|
||||
seedPhase(tmpDir, '03-gamma');
|
||||
|
||||
const atLenMinus1 = runGsdTools('query phases.list --pick directories[2]', tmpDir);
|
||||
assert.strictEqual(atLenMinus1.success, true);
|
||||
assert.strictEqual(atLenMinus1.output, '03-gamma');
|
||||
|
||||
const atLen = runGsdTools('query phases.list --pick directories[3]', tmpDir);
|
||||
assert.strictEqual(atLen.success, false, 'index == length is out of range and must exit non-zero');
|
||||
|
||||
const atLenPlus1 = runGsdTools('query phases.list --pick directories[4]', tmpDir);
|
||||
assert.strictEqual(atLenPlus1.success, false, 'index == length + 1 is out of range and must exit non-zero');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// P12 (test matrix): the measured B11 defect — a non-JSON command's
|
||||
// `--pick` must never dump the whole document as a coincidental "success".
|
||||
// TODAY (measured on this tree, 2026-08-26), against an empty temp project:
|
||||
// $ gsd-tools audit-open --pick nonexistent_field
|
||||
// ### Milestone Close: Open Artifact Audit
|
||||
//
|
||||
// All artifact types clear. Safe to proceed.
|
||||
//
|
||||
// ---
|
||||
// exit 0
|
||||
test('nonJsonOutputDoesNotDumpWholeDocument', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runGsdTools('audit-open --pick nonexistent_field', tmpDir);
|
||||
assert.strictEqual(result.success, false);
|
||||
assert.strictEqual(result.output, '');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// P13 (test matrix): `--raw --pick <known field>` withdraws its
|
||||
// coincidental "success" — measured today: exit 0, stdout `hello-world`,
|
||||
// via the same non-JSON dump `--raw` produces.
|
||||
test('rawPlusPickIsRejectedNotCoincidentallyRight', () => {
|
||||
const result = runGsdTools(['generate-slug', 'Hello World', '--raw', '--pick', 'slug']);
|
||||
assert.strictEqual(result.success, false);
|
||||
});
|
||||
|
||||
// P14 (test matrix): the confidently-wrong case — measured today: exit 0,
|
||||
// stdout `hello-world` (the SLUG field's value, not the bogus field asked
|
||||
// for), via the same non-JSON dump.
|
||||
test('rawPlusPickBogusDoesNotEmitAnotherFieldsValue', () => {
|
||||
const result = runGsdTools(['generate-slug', 'Hello World', '--raw', '--pick', 'bogus']);
|
||||
assert.strictEqual(result.success, false);
|
||||
assert.ok(
|
||||
!result.output.includes('hello-world'),
|
||||
`must not leak another field's value; got: ${JSON.stringify(result.output)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test('errors when --pick has no value', () => {
|
||||
@@ -55,4 +159,282 @@ describe('--pick flag', () => {
|
||||
assert.ok(result.output.length > 0, 'timestamp should not be empty');
|
||||
assert.match(result.output, /^\d{4}-\d{2}-\d{2}T/);
|
||||
});
|
||||
|
||||
// B7 (design 40-design.md; test matrix P7): a dotted path that resolves
|
||||
// partway then dies. `count` is a number on `phases.list --type summaries`
|
||||
// (a real, always-present field); walking `.missing` off it is not a
|
||||
// plain object, so the path dies partway through — the same failure class
|
||||
// as B6 (field absent outright), not a crash.
|
||||
test('absentDottedPathExitsNonZero', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runCli(
|
||||
['query', 'phases.list', '--type', 'summaries', '--pick', 'count.missing'],
|
||||
{ cwd: tmpDir },
|
||||
);
|
||||
assert.notStrictEqual(result.status, 0);
|
||||
assert.strictEqual(result.reason, 'pick_field_absent');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// B9 (test matrix P11): bracket syntax applied to a non-array field.
|
||||
test('bracketOnNonArrayExitsNonZero', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runCli(
|
||||
['query', 'phases.list', '--type', 'summaries', '--pick', 'count[0]'],
|
||||
{ cwd: tmpDir },
|
||||
);
|
||||
assert.notStrictEqual(result.status, 0);
|
||||
assert.strictEqual(result.reason, 'pick_field_absent');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// B10 (test matrix): the existing boundary test above only exercises
|
||||
// non-negative indices — negative-index normalization
|
||||
// (`arr.length + index`) is a separate branch in extractField and was
|
||||
// otherwise untested. N=3 seeded phase directories.
|
||||
test('negativeArrayIndexInRangeResolves', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
seedPhase(tmpDir, '01-alpha');
|
||||
seedPhase(tmpDir, '02-beta');
|
||||
seedPhase(tmpDir, '03-gamma');
|
||||
|
||||
const last = runGsdTools('query phases.list --pick directories[-1]', tmpDir);
|
||||
assert.strictEqual(last.success, true);
|
||||
assert.strictEqual(last.output, '03-gamma');
|
||||
|
||||
const first = runGsdTools('query phases.list --pick directories[-3]', tmpDir);
|
||||
assert.strictEqual(first.success, true);
|
||||
assert.strictEqual(first.output, '01-alpha');
|
||||
|
||||
const outOfRange = runGsdTools('query phases.list --pick directories[-4]', tmpDir);
|
||||
assert.strictEqual(outOfRange.success, false, 'index == -(N+1) is out of range and must exit non-zero');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// B14 (test matrix P15): the JSON root itself is not an object. VERIFIED
|
||||
// on this tree: config-get with --default on a missing key emits the bare
|
||||
// JSON string "fallback" (not an object), so --pick must fail rather than
|
||||
// walk a string as if it had named fields.
|
||||
test('nonObjectJsonRootExitsNonZero', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const plain = runGsdTools('config-get nonexistent.key --default fallback', tmpDir);
|
||||
assert.strictEqual(plain.success, true);
|
||||
assert.strictEqual(plain.output, '"fallback"');
|
||||
|
||||
const result = runCli(
|
||||
['config-get', 'nonexistent.key', '--default', 'fallback', '--pick', 'value'],
|
||||
{ cwd: tmpDir },
|
||||
);
|
||||
assert.notStrictEqual(result.status, 0);
|
||||
assert.strictEqual(result.reason, 'pick_field_absent');
|
||||
assert.match(result.message, /JSON string, not an object/);
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// B17 (test matrix P19/P20, negative space N8): io.cjs's output() writes
|
||||
// `@file:<path>` instead of inline JSON once the serialized payload
|
||||
// exceeds 50000 characters, and `--pick` MUST resolve that redirection
|
||||
// BEFORE parsing — otherwise every large result becomes a false
|
||||
// pick_output_not_json. The fixture below seeds exactly PHASE_COUNT real
|
||||
// phase directories (skipping phase number 999, which phase.cjs's sentinel
|
||||
// predicate — SENTINEL_RANGES [0,999] — excludes from the list regardless
|
||||
// of padding width, confirmed empirically; skipping it keeps `count`
|
||||
// exactly PHASE_COUNT so the assertions below are deterministic) with
|
||||
// padded names long enough that the serialized JSON provably exceeds the
|
||||
// threshold. The spill is MEASURED, not assumed: the plain (non --pick)
|
||||
// path transparently resolves @file: back to inline JSON (#1891), so its
|
||||
// stdout length IS the real serialized payload size.
|
||||
test('largeAtFilePayloadStillResolves + largeAtFilePayloadAbsentFieldIsAbsentNotNonJson', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const PHASE_COUNT = 1200;
|
||||
let made = 0;
|
||||
for (let i = 1; made < PHASE_COUNT; i++) {
|
||||
if (i === 999) continue; // sentinel phase id — excluded from the list, would skew `count`
|
||||
seedPhase(tmpDir, `${String(i).padStart(5, '0')}-phase-name-padding-to-make-this-longer`);
|
||||
made++;
|
||||
}
|
||||
|
||||
const plain = runGsdTools('query phases.list', tmpDir);
|
||||
assert.strictEqual(plain.success, true);
|
||||
assert.ok(
|
||||
plain.output.length > 50000,
|
||||
`fixture must exceed the 50000-char @file: spill threshold; measured ${plain.output.length}`,
|
||||
);
|
||||
|
||||
// Present field ("largeAtFilePayloadStillResolves"): resolves at exit
|
||||
// 0 through the @file: payload.
|
||||
const present = runGsdTools('query phases.list --pick count', tmpDir);
|
||||
assert.strictEqual(present.success, true);
|
||||
assert.strictEqual(present.output, String(PHASE_COUNT));
|
||||
|
||||
// Absent field ("largeAtFilePayloadAbsentFieldIsAbsentNotNonJson"):
|
||||
// must be pick_field_absent, NOT pick_output_not_json — proving the
|
||||
// @file: resolution ran before the JSON.parse/absence check.
|
||||
const absent = runCli(
|
||||
['query', 'phases.list', '--pick', 'nonexistent_field'],
|
||||
{ cwd: tmpDir },
|
||||
);
|
||||
assert.notStrictEqual(absent.status, 0);
|
||||
assert.strictEqual(absent.reason, 'pick_field_absent');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// formatDiagnosticToken (io.cjs) — untrusted --pick token escaping.
|
||||
//
|
||||
// Adversarial review finding (isolated review, verified live): `--pick`'s
|
||||
// field value reaches the "field not found" / "output was not JSON"
|
||||
// diagnostics verbatim. Repro on this tree BEFORE the fix:
|
||||
// $ node gsd-tools.cjs generate-slug x --pick $'a\nError: forged'
|
||||
// Error: --pick a
|
||||
// Error: forged: field not found; available top-level keys: slug
|
||||
// Spawns the real CLI (the vulnerability is about the literal bytes on
|
||||
// stderr) and asserts on the RAW stderr string — a trimmed assertion would
|
||||
// hide a leading/trailing forged blank line.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe('formatDiagnosticToken escapes untrusted --pick field values', () => {
|
||||
const HOSTILE_TOKENS = [
|
||||
['embedded newline forging a second Error: line', 'a\nError: forged'],
|
||||
['embedded double quote', 'a"bogus'],
|
||||
['embedded C0 control character', 'a\x07bogus'],
|
||||
];
|
||||
|
||||
for (const [label, token] of HOSTILE_TOKENS) {
|
||||
test(`--pick field-not-found diagnostic stays single-line for a token with ${label}`, () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const result = runCli(['generate-slug', 'x', '--pick', token], { cwd: tmpDir, jsonErrors: false });
|
||||
assert.notStrictEqual(result.status, 0);
|
||||
const rawStderr = result.stderr;
|
||||
const nonEmptyLines = rawStderr.split('\n').filter((l) => l.length > 0);
|
||||
assert.strictEqual(
|
||||
nonEmptyLines.length, 1,
|
||||
`expected exactly one non-empty stderr line, got raw stderr: ${JSON.stringify(rawStderr)}`,
|
||||
);
|
||||
assert.match(nonEmptyLines[0], /^Error: /);
|
||||
const errorPrefixedLineCount = rawStderr.split('\n').filter((l) => l.startsWith('Error:')).length;
|
||||
assert.strictEqual(errorPrefixedLineCount, 1, 'the hostile token must not forge a second "Error:" line');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// formatKeyForDiagnosticList (gsd-tools.cjs) — untrusted frontmatter KEY
|
||||
// escaping, as distinct from the untrusted --pick TOKEN escaping above.
|
||||
//
|
||||
// `frontmatter get <file>` (no --field) reads an arbitrary user-authored
|
||||
// markdown file and, on a subsequent --pick miss, echoes that document's own
|
||||
// top-level frontmatter keys straight into the "field not found; available
|
||||
// top-level keys: ..." diagnostic. A key is therefore untrusted input from a
|
||||
// user document in exactly the way a --pick argv token is untrusted input
|
||||
// from the shell — formatKeyForDiagnosticList (gsd-tools.cjs) exists to
|
||||
// neutralize it the same way formatDiagnosticToken neutralizes the token.
|
||||
//
|
||||
// Reachable + verified live on this tree, e.g. for a frontmatter key
|
||||
// containing a real embedded newline:
|
||||
// $ printf '---\n"weird\\nkey": v\nplain: y\n---\n\nbody\n' > f.md
|
||||
// $ gsd-tools frontmatter get f.md --pick absent_field
|
||||
// Error: --pick "absent_field": field not found; available top-level keys: weird\nkey, plain
|
||||
// The `\n` in that stderr is the two-character ESCAPED sequence backslash-n,
|
||||
// not a real newline — the raw/untrimmed stderr assertions below pin that.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe('formatKeyForDiagnosticList escapes untrusted frontmatter keys', () => {
|
||||
test('hostileFrontmatterKeyCannotForgeASecondErrorLine', () => {
|
||||
const HOSTILE_KEY_FIXTURES = [
|
||||
['embedded newline', '---\n"weird\\nkey": v\nplain: y\n---\n\nbody\n', 'weird\\nkey'],
|
||||
['embedded double quote', '---\n"weird\\"quotekey": v\nplain: y\n---\n\nbody\n', 'weird\\"quotekey'],
|
||||
['embedded C0 control character', '---\n"weird\\u0007ctrlkey": v\nplain: y\n---\n\nbody\n', 'weird\\u0007ctrlkey'],
|
||||
];
|
||||
|
||||
for (const [label, frontmatterSource, expectedEscapedKey] of HOSTILE_KEY_FIXTURES) {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const f = path.join(tmpDir, 'weird.md');
|
||||
fs.writeFileSync(f, frontmatterSource);
|
||||
|
||||
const result = runCli(
|
||||
['frontmatter', 'get', f, '--pick', 'absent_field'],
|
||||
{ cwd: tmpDir, jsonErrors: false },
|
||||
);
|
||||
assert.notStrictEqual(result.status, 0, `[${label}] must exit non-zero`);
|
||||
|
||||
const rawStderr = result.stderr;
|
||||
// Split on the raw, UNTRIMMED stderr and drop exactly one trailing
|
||||
// empty element (the newline error() always terminates its message
|
||||
// with) — a hostile key that forged a second line would leave MORE
|
||||
// than one element after that single drop.
|
||||
const lines = rawStderr.split('\n');
|
||||
assert.strictEqual(
|
||||
lines[lines.length - 1], '',
|
||||
`[${label}] expected a single trailing empty element from the terminating newline, got raw stderr: ${JSON.stringify(rawStderr)}`,
|
||||
);
|
||||
const linesWithoutTrailingEmpty = lines.slice(0, -1);
|
||||
assert.strictEqual(
|
||||
linesWithoutTrailingEmpty.length, 1,
|
||||
`[${label}] expected exactly one line after dropping the trailing empty element, got raw stderr: ${JSON.stringify(rawStderr)}`,
|
||||
);
|
||||
const errorPrefixedLineCount = linesWithoutTrailingEmpty.filter((l) => l.startsWith('Error:')).length;
|
||||
assert.strictEqual(errorPrefixedLineCount, 1, `[${label}] the hostile key must not forge a second "Error:" line`);
|
||||
|
||||
// The diagnostic must stay USEFUL, not merely safe: a "fix" that
|
||||
// dropped the offending key entirely would also pass the one-line
|
||||
// assertions above, so pin that the escaped key is still present.
|
||||
assert.ok(
|
||||
linesWithoutTrailingEmpty[0].includes(`available top-level keys: ${expectedEscapedKey}, plain`),
|
||||
`[${label}] expected the escaped key to still name the offending key, got: ${JSON.stringify(linesWithoutTrailingEmpty[0])}`,
|
||||
);
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Negative-space control: an ORDINARY frontmatter document (no hostile
|
||||
// bytes in any key) must still produce a plain, readable, unquoted key
|
||||
// list — proving the escape does not turn every normal diagnostic into
|
||||
// JSON-quoted noise.
|
||||
test('ordinaryFrontmatterKeysStayPlainAndUnquotedInDiagnostic', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const f = path.join(tmpDir, 'plain.md');
|
||||
fs.writeFileSync(f, '---\nalpha: v\nbeta: y\n---\n\nbody\n');
|
||||
|
||||
const result = runCli(
|
||||
['frontmatter', 'get', f, '--pick', 'absent_field'],
|
||||
{ cwd: tmpDir, jsonErrors: false },
|
||||
);
|
||||
assert.notStrictEqual(result.status, 0);
|
||||
assert.match(result.stderr, /available top-level keys: alpha, beta\n$/);
|
||||
// Only the KEY LIST must stay unquoted — `--pick "absent_field"` earlier
|
||||
// in the same message is legitimately JSON-quoted by formatDiagnosticToken
|
||||
// (a separate escape, for the untrusted argv token, not the frontmatter
|
||||
// key), so scope the "no JSON-quoting noise" assertion to the key-list
|
||||
// segment rather than the whole stderr string.
|
||||
const keyListSegment = result.stderr.slice(result.stderr.indexOf('available top-level keys:'));
|
||||
assert.ok(!keyListSegment.includes('"'), `ordinary keys must not be JSON-quoted, got: ${JSON.stringify(keyListSegment)}`);
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -290,11 +290,21 @@ describe('flag value shapes drive section_manifest by truthiness, not semantic v
|
||||
assert.equal(occurrences.length, 1, 'must be a single membership, not one entry per duplicate token');
|
||||
});
|
||||
|
||||
test('flag-shaped value (--prd --weird) does not crash and deterministically excludes prd-express-gate (row D6)', () => {
|
||||
test('flag-shaped value (--prd --reviews) does not crash and deterministically excludes prd-express-gate (row D6)', () => {
|
||||
// parseNamedArgs treats a token starting with "--" as the NEXT flag, never
|
||||
// as this flag's value — so --prd here resolves to null (absent), not the
|
||||
// literal string "--weird".
|
||||
const result = runGsdTools(['init', 'plan-phase', '1', '--prd', '--weird'], tmpDir);
|
||||
// literal string "--reviews".
|
||||
//
|
||||
// Corrected after the first full verification run: the original choice of
|
||||
// `--weird` here predates ADR-3473 §8.4's strict unrecognized-flag
|
||||
// rejection (this file is from #2994/epic #1671, before #3358's strict
|
||||
// parseNamedArgs) and is itself an unrecognized flag for `plan-phase` —
|
||||
// it now correctly fails with exit 1 / "unknown flag --weird" instead of
|
||||
// proving the "flag-shaped value" point this test exists for. Swapped for
|
||||
// `--reviews`, a real declared plan-phase boolean flag, matching the same
|
||||
// substitution already used by the sibling row
|
||||
// tests/init.test.cjs:emptyPrdValueIsFalsyAndTreatedAsAbsent (row B5).
|
||||
const result = runGsdTools(['init', 'plan-phase', '1', '--prd', '--reviews'], tmpDir);
|
||||
assert.ok(result.success, `a flag-shaped value must not crash the command: ${result.error}`);
|
||||
const output = JSON.parse(result.output);
|
||||
assert.ok(output.section_manifest.excluded.includes('prd-express-gate'), '--prd immediately followed by another --flag token must resolve to absent, per parseNamedArgs');
|
||||
|
||||
@@ -1527,8 +1527,16 @@ describe('#3573 total_phases — roadmap absent with an asserted milestone', ()
|
||||
);
|
||||
seedPhaseDirs(tmpDir, [1]);
|
||||
|
||||
// ADR-3473 §8.4 / #3358: a bare positional phase ("state begin-phase 2")
|
||||
// is now a rejected, undeclared token — see
|
||||
// tests/state.test.cjs positionalPlannedPhaseLeavesStateMdUntouched_3358,
|
||||
// the sibling regression for "planned-phase" that locks in exactly this
|
||||
// rejection. Use the documented "--phase N" flag form (see
|
||||
// CLI-TOOLS.md line 116 in the docs directory) instead; this test's own
|
||||
// assertions were never about the bare-positional shape itself, only
|
||||
// about total_phases surviving the resync.
|
||||
const rec = runNode(
|
||||
[TOOLS_PATH, 'state', 'begin-phase', '2'],
|
||||
[TOOLS_PATH, 'state', 'begin-phase', '--phase', '2'],
|
||||
{ cwd: tmpDir, env: { ...process.env, ...TEST_ENV_BASE }, timeoutMs: 60000 },
|
||||
);
|
||||
assert.ok(rec.exitCode === 0, `state begin-phase failed: ${rec.stderr}`);
|
||||
@@ -1587,8 +1595,16 @@ describe('#3573 total_phases — roadmap absent with an asserted milestone', ()
|
||||
);
|
||||
seedPhaseDirs(tmpDir, [1]);
|
||||
|
||||
// ADR-3473 §8.4 / #3358: a bare positional phase ("state planned-phase 2")
|
||||
// is now a rejected, undeclared token — see
|
||||
// tests/state.test.cjs positionalPlannedPhaseLeavesStateMdUntouched_3358,
|
||||
// the regression test that locks in exactly this rejection for this same
|
||||
// subcommand. Use the documented "--phase N" flag form (see
|
||||
// COMMANDS.md line 2192 in the docs directory) instead; this test's own
|
||||
// assertions were never about the bare-positional shape itself, only
|
||||
// about total_phases surviving the resync.
|
||||
const rec = runNode(
|
||||
[TOOLS_PATH, 'state', 'planned-phase', '2', '--name', 'Core'],
|
||||
[TOOLS_PATH, 'state', 'planned-phase', '--phase', '2', '--name', 'Core'],
|
||||
{ cwd: tmpDir, env: { ...process.env, ...TEST_ENV_BASE }, timeoutMs: 60000 },
|
||||
);
|
||||
assert.ok(rec.exitCode === 0, `state planned-phase failed: ${rec.stderr}`);
|
||||
|
||||
@@ -8566,7 +8566,14 @@ describe('regressions: table-format STATE.md (#1162)', () => {
|
||||
fs.mkdirSync(phaseDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(phaseDir, '1-01-PLAN.md'), '# Plan 1');
|
||||
|
||||
const result = runGsdTools(['state', 'planned-phase', '1', '--plan-count', '1'], tmpDir);
|
||||
// #3884 (ADR-3473 §8.4): `--plan-count` was never a declared flag (the
|
||||
// real flag is `--plans`) and the bare '1' was never read as a phase
|
||||
// positional either — both were silently dropped by the pre-#3884
|
||||
// permissive parser. The command "worked" only because
|
||||
// cmdStatePlannedPhase falls back to STATE.md's own current phase (1
|
||||
// here) when no --phase is given, so the assertion below never actually
|
||||
// exercised phase/plan-count plumbing. Corrected to the real flags.
|
||||
const result = runGsdTools(['state', 'planned-phase', '--phase', '1', '--plans', '1'], tmpDir);
|
||||
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
@@ -8707,7 +8714,9 @@ describe('regressions: table-format STATE.md (#1162) — updateCurrentPositionFi
|
||||
fs.mkdirSync(phaseDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(phaseDir, '2-01-PLAN.md'), '# Plan\n');
|
||||
|
||||
const result = runGsdTools(['state', 'planned-phase', '2', '--plan-count', '1'], tmpDir);
|
||||
// #3884: `--plan-count` / bare positional never worked — see the (a)
|
||||
// Finding-2a-sibling note on the earlier occurrence of this pattern.
|
||||
const result = runGsdTools(['state', 'planned-phase', '--phase', '2', '--plans', '1'], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const written = fs.readFileSync(statePath, 'utf-8');
|
||||
@@ -8733,7 +8742,9 @@ describe('regressions: table-format STATE.md (#1162) — updateCurrentPositionFi
|
||||
fs.mkdirSync(phaseDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(phaseDir, '2-01-PLAN.md'), '# Plan\n');
|
||||
|
||||
const result = runGsdTools(['state', 'planned-phase', '2', '--plan-count', '1'], tmpDir);
|
||||
// #3884: `--plan-count` / bare positional never worked — see the note on
|
||||
// the first occurrence of this pattern above.
|
||||
const result = runGsdTools(['state', 'planned-phase', '--phase', '2', '--plans', '1'], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const written = fs.readFileSync(statePath, 'utf-8');
|
||||
@@ -8754,7 +8765,9 @@ describe('regressions: table-format STATE.md (#1162) — updateCurrentPositionFi
|
||||
fs.mkdirSync(phaseDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(phaseDir, '2-01-PLAN.md'), '# Plan\n');
|
||||
|
||||
const result = runGsdTools(['state', 'planned-phase', '2', '--plan-count', '1'], tmpDir);
|
||||
// #3884: `--plan-count` / bare positional never worked — see the note on
|
||||
// the first occurrence of this pattern above.
|
||||
const result = runGsdTools(['state', 'planned-phase', '--phase', '2', '--plans', '1'], tmpDir);
|
||||
assert.ok(result.success, `Command failed: ${result.error}`);
|
||||
|
||||
const written = fs.readFileSync(statePath, 'utf-8');
|
||||
@@ -18891,3 +18904,122 @@ describe('ADR-3473 §8.7 (#3872): reconcileReportedFields / the transaction diff
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
// Consumer-output identity (ADR-3180 Decision 4(b)) — #3358 / #3884
|
||||
//
|
||||
// For #3358 the consumer is `state planned-phase`'s EFFECT on STATE.md, not
|
||||
// `parseNamedArgs`'s return value — a unit assertion on the parser alone
|
||||
// would have passed throughout this defect's entire life. These rows spawn
|
||||
// the real CLI against a temp project and assert on STATE.md's bytes.
|
||||
// ────────────────────────────────────────────────────────────────────────
|
||||
describe('state — consumer-output identity (ADR-3180 Decision 4(b), #3358)', () => {
|
||||
function stateMdWithPopulatedPhaseTwo() {
|
||||
return [
|
||||
'---',
|
||||
"gsd_state_version: '1.0'",
|
||||
'status: planning',
|
||||
'progress:',
|
||||
' total_phases: 5',
|
||||
' completed_phases: 1',
|
||||
' total_plans: 10',
|
||||
' completed_plans: 4',
|
||||
' percent: 40',
|
||||
'---',
|
||||
'',
|
||||
'# Project State',
|
||||
'',
|
||||
'## Current Position',
|
||||
'',
|
||||
'Phase: 2 of 5 (Widget Support)',
|
||||
'Plan: 1 of 3 in current phase',
|
||||
'Status: Ready to execute',
|
||||
'Last activity: 2026-08-20 — Phase 2 planning complete',
|
||||
'',
|
||||
'Progress: [####------] 40%',
|
||||
'',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
// #3358: a stray positional (`3`) past `state planned-phase`'s declared
|
||||
// boundary is silently dropped by the CURRENT permissive parseNamedArgs —
|
||||
// every flag resolves to `null` — and the command still RUNS, overwriting
|
||||
// the previously-current phase block.
|
||||
//
|
||||
// Measured on this tree, 2026-08-26, against exactly this fixture:
|
||||
// $ gsd-tools query state.planned-phase 3 --cwd <tmp>
|
||||
// {"updated":["Current Position","Current Phase Name"],"phase":null,"plan_count":null}
|
||||
// exit 0
|
||||
// STATE.md's `## Current Position` block changed from:
|
||||
// Phase: 2 of 5 (Widget Support)
|
||||
// to:
|
||||
// Phase: null — READY TO EXECUTE
|
||||
// (and frontmatter gained `current_phase_name: READY TO EXECUTE`, an
|
||||
// outright corruption of the curated phase name).
|
||||
test('positionalPlannedPhaseLeavesStateMdUntouched_3358', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const statePath = writeState(tmpDir, stateMdWithPopulatedPhaseTwo());
|
||||
const before = fs.readFileSync(statePath);
|
||||
|
||||
const result = runGsdTools('query state.planned-phase 3', tmpDir);
|
||||
|
||||
assert.notStrictEqual(result.exitCode, 0, 'a positional argument past the boundary must exit non-zero');
|
||||
const after = fs.readFileSync(statePath);
|
||||
assert.ok(before.equals(after), 'STATE.md must be byte-identical to before the rejected call');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// Control: the flag form of the exact same intent must keep succeeding and
|
||||
// keep updating STATE.md — proves C1 above is not passing merely because
|
||||
// `state planned-phase` is broken outright.
|
||||
test('flagFormPlannedPhaseStillUpdatesStateMd', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const statePath = writeState(tmpDir, stateMdWithPopulatedPhaseTwo());
|
||||
|
||||
const result = runGsdTools('query state.planned-phase --phase 3 --name X --plans 2', tmpDir);
|
||||
|
||||
assert.strictEqual(result.success, true, result.error);
|
||||
const after = fs.readFileSync(statePath, 'utf-8');
|
||||
assert.match(after, /Phase: 3 \(X\) — READY TO EXECUTE/);
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
|
||||
// #3358, second call site: an extra positional token on `add-decision`
|
||||
// must not be silently absorbed into a successful write.
|
||||
test('positionalOnAddDecisionAppendsNothing', () => {
|
||||
const tmpDir = createTempProject();
|
||||
try {
|
||||
const statePath = writeState(tmpDir, [
|
||||
'---',
|
||||
"gsd_state_version: '1.0'",
|
||||
'status: planning',
|
||||
'---',
|
||||
'',
|
||||
'# Project State',
|
||||
'',
|
||||
'## Accumulated Context',
|
||||
'',
|
||||
'### Decisions',
|
||||
'',
|
||||
'- none yet',
|
||||
'',
|
||||
].join('\n'));
|
||||
const before = fs.readFileSync(statePath, 'utf-8');
|
||||
|
||||
const result = runGsdTools(['query', 'state.add-decision', 'stray-token', '--summary', 'x'], tmpDir);
|
||||
|
||||
assert.notStrictEqual(result.exitCode, 0, 'an extra positional argument must exit non-zero');
|
||||
const after = fs.readFileSync(statePath, 'utf-8');
|
||||
assert.ok(!after.includes('- [Phase'), 'no decision row should have been appended');
|
||||
assert.strictEqual(after, before, 'STATE.md must be unchanged when the call is rejected');
|
||||
} finally {
|
||||
cleanup(tmpDir);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -43,8 +43,6 @@ const {
|
||||
dedupeViolationsForBaseline,
|
||||
writeBaseline,
|
||||
toPosixRel,
|
||||
PICK_RE,
|
||||
ECHO_FALLBACK_RE,
|
||||
CAT_LS_COMMAND_RE,
|
||||
HEREDOC_AFTER_COMMAND_RE,
|
||||
isNoopFallback,
|
||||
@@ -83,109 +81,56 @@ function markerComment(reason) {
|
||||
return `# gsd-scan-ignore: ${reason}`;
|
||||
}
|
||||
|
||||
// ─── Detector A — PICK_RE / ECHO_FALLBACK_RE ──────────────────────────────
|
||||
// ─── Detector A — RETIRED, #3884 ───────────────────────────────────────────
|
||||
//
|
||||
// ADR-3473 §8.4 made `--pick` exit non-zero on an absent field (issue
|
||||
// #3884), which made Detector A's own premise false — the `|| echo D` arm it
|
||||
// forbade is now the CORRECT idiom, not an unreachable one. Detector A (its
|
||||
// regexes, its branch in the scan, and its `kind: 'A'` finding shape) was
|
||||
// removed from scripts/lint-unreachable-guard-drift.cjs; this describe block
|
||||
// now pins the negative claim instead of the old positive one — the exact
|
||||
// shapes that used to be flagged (canonical, no-stderr-redirect,
|
||||
// empty-string-fallback, fenced, duplicated, CRLF) must produce ZERO
|
||||
// violations, proving the retirement did not leave a partial/half-removed
|
||||
// detector behind.
|
||||
|
||||
describe('Detector A — --pick + || echo fallback', () => {
|
||||
test('A1: canonical shape with 2>/dev/null is flagged, found names --pick', () => {
|
||||
const line = pickEchoLine({ stderr: true, fallback: '"d"' });
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 1);
|
||||
assert.strictEqual(violations[0].kind, 'A');
|
||||
assert.strictEqual(violations[0].found, '--pick');
|
||||
assert.strictEqual(violations[0].text, line.trim());
|
||||
describe('Detector A (--pick + || echo) — retired, #3884', () => {
|
||||
test('detectorAShapeIsNoLongerAFinding: the canonical shape, with/without a stderr redirect, and an empty-string fallback are all unreported', () => {
|
||||
for (const opts of [{ stderr: true, fallback: '"d"' }, { stderr: false, fallback: '"d"' }, { fallback: '""' }]) {
|
||||
const line = pickEchoLine(opts);
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, [], `expected no violations for ${JSON.stringify(opts)}`);
|
||||
}
|
||||
});
|
||||
|
||||
test('A2: without a stderr redirect is still flagged', () => {
|
||||
const line = pickEchoLine({ stderr: false, fallback: '"d"' });
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 1);
|
||||
assert.strictEqual(violations[0].kind, 'A');
|
||||
test('detectorAShapeIsNoLongerAFinding: fenced, duplicated, and CRLF variants of the shape are also unreported', () => {
|
||||
const line = pickEchoLine();
|
||||
const fenced = ['```bash', line, '```'].join('\n');
|
||||
const duplicated = [line, line].join('\n');
|
||||
const crlf = `${line}\r\n`;
|
||||
assert.deepStrictEqual(findUnreachableGuardDrift(fenced, FAKE_FILE).violations, []);
|
||||
assert.deepStrictEqual(findUnreachableGuardDrift(duplicated, FAKE_FILE).violations, []);
|
||||
assert.deepStrictEqual(findUnreachableGuardDrift(crlf, FAKE_FILE).violations, []);
|
||||
});
|
||||
|
||||
test('A3: an empty-string default is still flagged (unreachable AND a no-op)', () => {
|
||||
const line = pickEchoLine({ fallback: '""' });
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 1);
|
||||
});
|
||||
|
||||
test('A4: a --pick-less config-get fallback is NOT detected', () => {
|
||||
const line = ['X=$(gsd_run query config-get k 2>/dev/null ', '|', '|', ' echo "false")'].join('');
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A5: a pick with no fallback is NOT detected', () => {
|
||||
const line = 'X=$(gsd_run query phases.list --pick summaries_total)';
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A6: a git fallback is NOT detected', () => {
|
||||
const line = ['X=$(git rev-list --count HEAD ', '|', '|', ' echo 0)'].join('');
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A7: a grep fallback is NOT detected', () => {
|
||||
const line = ["Y=$(grep -cE '^' file.md ", '|', '|', ' echo "0")'].join('');
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A8: the and-or ternary idiom is NOT detected', () => {
|
||||
const line = ['$([ -n "$X" ] && echo "a" ', '|', '|', ' echo "")'].join('');
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A9 (known limit): a cross-line split is NOT detected', () => {
|
||||
const text = [
|
||||
test('detectorAShapeIsNoLongerAFinding: no other --pick + || echo variant (git/grep/config-get/ternary/cross-line/printf fallback) is reported either', () => {
|
||||
const variants = [
|
||||
['X=$(gsd_run query config-get k 2>/dev/null ', '|', '|', ' echo "false")'].join(''),
|
||||
'X=$(gsd_run query phases.list --pick summaries_total)',
|
||||
['X=$(git rev-list --count HEAD ', '|', '|', ' echo 0)'].join(''),
|
||||
["Y=$(grep -cE '^' file.md ", '|', '|', ' echo "0")'].join(''),
|
||||
['$([ -n "$X" ] && echo "a" ', '|', '|', ' echo "")'].join(''),
|
||||
["X=$(gsd_run query phases.list --pick f ", '|', '|', " printf 'd')"].join(''),
|
||||
];
|
||||
for (const line of variants) {
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, [], `expected no violations for ${JSON.stringify(line)}`);
|
||||
}
|
||||
const crossLine = [
|
||||
'X=$(gsd_run query phases.list --pick summaries_total 2>/dev/null)',
|
||||
['Y=$(echo "$X" ', '|', '|', ' echo "0")'].join(''),
|
||||
].join('\n');
|
||||
const { violations } = findUnreachableGuardDrift(text, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A10 (known limit): a printf fallback is NOT detected', () => {
|
||||
const line = ["X=$(gsd_run query phases.list --pick f ", '|', '|', " printf 'd')"].join('');
|
||||
const { violations } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
});
|
||||
|
||||
test('A11: a fenced block is not an exemption — the same line inside ```bash still flags', () => {
|
||||
const line = pickEchoLine();
|
||||
const text = ['```bash', line, '```'].join('\n');
|
||||
const { violations } = findUnreachableGuardDrift(text, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 1);
|
||||
assert.strictEqual(violations[0].line, 2);
|
||||
});
|
||||
|
||||
test('A12: reports each violating line separately, with correct line numbers', () => {
|
||||
const l1 = pickEchoLine({ pick: 'a' });
|
||||
const l2 = pickEchoLine({ pick: 'b' });
|
||||
const text = ['no-op', l1, 'middle', l2].join('\n');
|
||||
const { violations } = findUnreachableGuardDrift(text, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 2);
|
||||
assert.strictEqual(violations[0].line, 2);
|
||||
assert.strictEqual(violations[1].line, 4);
|
||||
});
|
||||
|
||||
test('A13: byte-identical duplicates count as 2 occurrences', () => {
|
||||
const line = pickEchoLine();
|
||||
const text = [line, line].join('\n');
|
||||
const { violations } = findUnreachableGuardDrift(text, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 2);
|
||||
assert.strictEqual(violations[0].text, violations[1].text);
|
||||
});
|
||||
|
||||
test('A15: CRLF line endings yield the identical verdict to LF', () => {
|
||||
const line = pickEchoLine();
|
||||
const lf = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
const crlf = findUnreachableGuardDrift(`${line}\r\n`, FAKE_FILE);
|
||||
assert.strictEqual(lf.violations.length, 1);
|
||||
assert.strictEqual(crlf.violations.length, 1);
|
||||
assert.strictEqual(crlf.violations[0].text, lf.violations[0].text);
|
||||
assert.deepStrictEqual(findUnreachableGuardDrift(crossLine, FAKE_FILE).violations, []);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -360,7 +305,7 @@ describe('Detector B — cat <glob> (B-i), ls <glob> || <real fallback> (B-ii),
|
||||
|
||||
describe('Escape marker — # gsd-scan-ignore:', () => {
|
||||
test('M1: a marker naming an issue exempts the line', () => {
|
||||
const line = `${pickEchoLine()} ${markerComment('#3409')}`;
|
||||
const line = `${catLine('dir/*.md')} ${markerComment('#3409')}`;
|
||||
const { violations, malformed } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
assert.deepStrictEqual(malformed, []);
|
||||
@@ -374,7 +319,7 @@ describe('Escape marker — # gsd-scan-ignore:', () => {
|
||||
});
|
||||
|
||||
test('M3: a free-text reason reports a malformed declaration, not a plain violation', () => {
|
||||
const line = `${pickEchoLine()} ${markerComment('because I said so')}`;
|
||||
const line = `${catLine('dir/*.md')} ${markerComment('because I said so')}`;
|
||||
const { violations, malformed } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
assert.strictEqual(malformed.length, 1);
|
||||
@@ -382,7 +327,7 @@ describe('Escape marker — # gsd-scan-ignore:', () => {
|
||||
});
|
||||
|
||||
test('M4: an empty reason is not an audit trail — malformed', () => {
|
||||
const line = `${pickEchoLine()} # gsd-scan-ignore:`;
|
||||
const line = `${catLine('dir/*.md')} # gsd-scan-ignore:`;
|
||||
const { violations, malformed } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
assert.strictEqual(malformed.length, 1);
|
||||
@@ -390,14 +335,14 @@ describe('Escape marker — # gsd-scan-ignore:', () => {
|
||||
});
|
||||
|
||||
test('M5: a whitespace-only reason is rejected — malformed', () => {
|
||||
const line = `${pickEchoLine()} # gsd-scan-ignore: `;
|
||||
const line = `${catLine('dir/*.md')} # gsd-scan-ignore: `;
|
||||
const { violations, malformed } = findUnreachableGuardDrift(line, FAKE_FILE);
|
||||
assert.deepStrictEqual(violations, []);
|
||||
assert.strictEqual(malformed.length, 1);
|
||||
});
|
||||
|
||||
test('M6: the marker binds only to its own line — a marker above a violation does not exempt it', () => {
|
||||
const text = [markerComment('#3409'), pickEchoLine()].join('\n');
|
||||
const text = [markerComment('#3409'), catLine('dir/*.md')].join('\n');
|
||||
const { violations, malformed } = findUnreachableGuardDrift(text, FAKE_FILE);
|
||||
assert.strictEqual(violations.length, 1, 'the violation on line 2 must still fire');
|
||||
assert.deepStrictEqual(malformed, []);
|
||||
@@ -437,7 +382,7 @@ describe('Escape marker — # gsd-scan-ignore:', () => {
|
||||
const isolatedScript = buildIsolatedGuard(root);
|
||||
const wfDir = path.join(root, 'gsd-core', 'workflows');
|
||||
fs.mkdirSync(wfDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(wfDir, 'fake.md'), `${pickEchoLine()} ${markerComment(reason)}\n`);
|
||||
fs.writeFileSync(path.join(wfDir, 'fake.md'), `${catLine('dir/*.md')} ${markerComment(reason)}\n`);
|
||||
const baselinePath = path.join(root, BASELINE_REL_PATH);
|
||||
fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
|
||||
fs.writeFileSync(baselinePath, JSON.stringify({ entries: [] }), 'utf8');
|
||||
@@ -662,19 +607,14 @@ describe('Cross-platform & encoding', () => {
|
||||
const posixRel = 'gsd-core/workflows/fake.md';
|
||||
assert.strictEqual(toPosixRel(winRel), posixRel);
|
||||
assert.strictEqual(toPosixRel(posixRel), posixRel);
|
||||
const { violations } = findUnreachableGuardDrift(pickEchoLine(), winRel);
|
||||
const { violations } = findUnreachableGuardDrift(catLine('dir/*.md'), winRel);
|
||||
assert.strictEqual(violations[0].file, posixRel);
|
||||
assert.ok(!violations[0].file.includes('\\'));
|
||||
});
|
||||
|
||||
test('P2: CRLF input yields the same violations as LF (Detector A)', () => {
|
||||
const line = pickEchoLine();
|
||||
const lf = findUnreachableGuardDrift(line, FAKE_FILE).violations;
|
||||
const crlf = findUnreachableGuardDrift(line.replace(/\n/g, '\r\n') + '\r\n', FAKE_FILE).violations;
|
||||
assert.strictEqual(lf.length, 1);
|
||||
assert.strictEqual(crlf.length, 1);
|
||||
assert.strictEqual(lf[0].text, crlf[0].text);
|
||||
});
|
||||
// P2 (formerly "CRLF input yields the same violations as LF (Detector A)")
|
||||
// was retired alongside Detector A itself, #3884 — its claim is now fully
|
||||
// subsumed by P3 below, the only detector left whose CRLF parity matters.
|
||||
|
||||
test('P3: CRLF does not defeat the glob detector (Detector B)', () => {
|
||||
const line = catLine('dir/*.md');
|
||||
@@ -686,7 +626,7 @@ describe('Cross-platform & encoding', () => {
|
||||
});
|
||||
|
||||
test('P4: the baseline key is CR-free under CRLF — matches an LF-recorded baseline entry', () => {
|
||||
const line = pickEchoLine();
|
||||
const line = catLine('dir/*.md');
|
||||
const baseline = [{ file: FAKE_FILE, text: line.trim(), count: 1 }];
|
||||
const crlfViolations = findUnreachableGuardDrift(`${line}\r\n`, FAKE_FILE).violations;
|
||||
assert.ok(!crlfViolations[0].text.includes('\r'), 'the baseline-key text must carry no trailing \\r');
|
||||
@@ -716,7 +656,7 @@ describe('Hostile input', () => {
|
||||
const wfDir = path.join(root, 'gsd-core', 'workflows');
|
||||
fs.mkdirSync(wfDir, { recursive: true });
|
||||
const esc = String.fromCharCode(0x1b);
|
||||
const line = pickEchoLine() + ` # ${esc}[31mred${esc}[0m`;
|
||||
const line = catLine('dir/*.md') + ` # ${esc}[31mred${esc}[0m`;
|
||||
fs.writeFileSync(path.join(wfDir, 'fake.md'), `${line}\n`);
|
||||
writeBaselineFakeEmpty(root);
|
||||
|
||||
@@ -816,8 +756,8 @@ describe('Hostile input', () => {
|
||||
describe('Property tests', () => {
|
||||
// DOCUMENT-SHAPED, not writer-seeded (CONTRIBUTING.md's Fixture provenance
|
||||
// #2371): tokens are drawn from a shell-ish alphabet independent of
|
||||
// PICK_RE/ECHO_FALLBACK_RE's own literals, not generated from the
|
||||
// detector's regex source.
|
||||
// CAT_LS_COMMAND_RE's own literals, not generated from the detector's
|
||||
// regex source.
|
||||
const wordArb = fc.constantFrom(
|
||||
'gsd_run', 'query', 'phases.list', 'config-get', 'k', 'v', 'f', '2>/dev/null',
|
||||
'echo', 'printf', '"0"', '"d"', '$(', ')', 'X=', '&&', ';', 'if', 'then', 'fi',
|
||||
@@ -825,17 +765,17 @@ describe('Property tests', () => {
|
||||
);
|
||||
const lineArb = fc.array(wordArb, { minLength: 1, maxLength: 12 }).map((ws) => ws.join(' '));
|
||||
|
||||
test('F1: detector A never fires on a document-shaped line lacking --pick or lacking || echo', () => {
|
||||
// Retired-detector regression net (#3884): unlike the pre-retirement F1,
|
||||
// this deliberately does NOT filter out the `--pick` + `|| echo` combined
|
||||
// shape — it fuzzes lines that DO carry both tokens (via injectPipe) and
|
||||
// asserts a `kind: 'A'` violation is unconditionally impossible now that
|
||||
// Detector A no longer exists, closing off the possibility of a partial
|
||||
// removal (e.g. a stray branch reachable only through some input shape
|
||||
// this suite's hand-written fixtures do not happen to hit).
|
||||
test('F1: no document-shaped line — including one deliberately carrying both --pick and || echo — ever produces a kind:\'A\' violation', () => {
|
||||
fc.assert(
|
||||
fc.property(lineArb, fc.boolean(), (line, injectPipe) => {
|
||||
// Build a line that deliberately lacks at least one of the two
|
||||
// required tokens, without deriving the construction from
|
||||
// PICK_RE/ECHO_FALLBACK_RE themselves.
|
||||
const hasPick = line.includes('--pick');
|
||||
const rawFallback = injectPipe ? `${line} ${'|'}${'|'} echo done` : line;
|
||||
const hasEcho = /\|\|\s*echo\b/.test(rawFallback);
|
||||
fc.pre(!(hasPick && hasEcho));
|
||||
|
||||
const { violations } = findUnreachableGuardDrift(rawFallback, FAKE_FILE);
|
||||
const aViolations = violations.filter((v) => v.kind === 'A');
|
||||
assert.deepStrictEqual(aViolations, []);
|
||||
@@ -949,13 +889,13 @@ describe('Integration — CLI end-to-end', () => {
|
||||
assert.deepStrictEqual(malformed, []);
|
||||
});
|
||||
|
||||
test('C2: a fresh violation exits non-zero and the message names the remedy', (t) => {
|
||||
test('detectorBStillReportsGlobShapes (formerly C2): a reintroduced Detector-B shape still exits non-zero and names the remedy — proves the guard can FAIL, not just pass, after Detector A\'s retirement', (t) => {
|
||||
const root = createTempDir('gsd-3409-c2-');
|
||||
t.after(() => cleanup(root));
|
||||
const isolatedScript = buildIsolatedGuard(root);
|
||||
const wfDir = path.join(root, 'gsd-core', 'workflows');
|
||||
fs.mkdirSync(wfDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(wfDir, 'fake.md'), `${pickEchoLine()}\n`);
|
||||
fs.writeFileSync(path.join(wfDir, 'fake.md'), `${catLine('dir/*.md')}\n`);
|
||||
const baselinePath = path.join(root, BASELINE_REL_PATH);
|
||||
fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
|
||||
fs.writeFileSync(baselinePath, JSON.stringify({ entries: [] }), 'utf8');
|
||||
@@ -967,7 +907,8 @@ describe('Integration — CLI end-to-end', () => {
|
||||
assert.strictEqual(report.reason, REASON.FAIL_FRESH_VIOLATION);
|
||||
assert.strictEqual(report.violations.length, 1);
|
||||
assert.strictEqual(report.violations[0].file, FAKE_FILE);
|
||||
assert.strictEqual(report.violations[0].kind, 'A');
|
||||
assert.strictEqual(report.violations[0].kind, 'B');
|
||||
assert.strictEqual(report.violations[0].found, 'cat');
|
||||
});
|
||||
|
||||
test('C3: --update regenerates a baseline that then passes', (t) => {
|
||||
@@ -994,7 +935,7 @@ describe('Integration — CLI end-to-end', () => {
|
||||
const wfDir = path.join(root, 'gsd-core', 'workflows');
|
||||
fs.mkdirSync(wfDir, { recursive: true });
|
||||
fs.writeFileSync(path.join(wfDir, 'a.md'), `${catLine('dir/*.md')}\n`);
|
||||
fs.writeFileSync(path.join(wfDir, 'b.md'), `${pickEchoLine()}\n`);
|
||||
fs.writeFileSync(path.join(wfDir, 'b.md'), 'ls -d other/*.md 2>/dev/null || echo "none"\n');
|
||||
|
||||
runNode([isolatedScript, '--update'], { timeoutMs: PROBE_TIMEOUT_MS });
|
||||
const firstBaseline = fs.readFileSync(path.join(root, BASELINE_REL_PATH), 'utf8');
|
||||
@@ -1036,20 +977,12 @@ describe('dedupeViolationsForBaseline', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// ─── Regex-level sanity (documents the two regexes' shapes directly) ─────
|
||||
// ─── Regex-level sanity (documents Detector B's surviving regexes' shapes) ─
|
||||
//
|
||||
// PICK_RE / ECHO_FALLBACK_RE were retired with Detector A (#3884) and are no
|
||||
// longer exported — there is nothing left to assert on directly.
|
||||
|
||||
describe('Regex shape sanity', () => {
|
||||
test('PICK_RE matches only the literal --pick token', () => {
|
||||
assert.ok(PICK_RE.test('--pick foo'));
|
||||
assert.ok(!PICK_RE.test('--picky foo'));
|
||||
});
|
||||
|
||||
test('ECHO_FALLBACK_RE matches || echo with optional interior whitespace', () => {
|
||||
assert.ok(ECHO_FALLBACK_RE.test(['a ', '|', '|', ' echo b'].join('')));
|
||||
assert.ok(ECHO_FALLBACK_RE.test(['a ', '|', '|', ' echo b'].join('')));
|
||||
assert.ok(!ECHO_FALLBACK_RE.test(['a ', '|', '|', ' printf b'].join('')));
|
||||
});
|
||||
|
||||
test('CAT_LS_COMMAND_RE requires cat/ls immediately at a command-position anchor', () => {
|
||||
assert.ok(CAT_LS_COMMAND_RE.test('cat x'));
|
||||
assert.ok(CAT_LS_COMMAND_RE.test('$(cat x)'));
|
||||
|
||||
Reference in New Issue
Block a user