* test(#3885): failing-first coverage for the depth bound and the manufactured wave verdict ADR-3473 §8.5 says a swallowed failure may not become an authoritative-looking answer. Three families do exactly that today; this commit pins each one RED. Measured on this tree, 2026-08-27: intel query, .planning/intel/file-roles.json nested 12000 deep -> exit 1, "Error: Maximum call stack size exceeded" searchJsonEntries / matchesInValue carry no depth parameter at all. The MAX_JSON_SEARCH_DEPTH = 48 bound existed in the retired SDK lineage (sdk/src/query/intel.ts at 11918dcc3^) and the surviving .cts lineage never received it. same fixture nested 48 and 49 deep -> both return total=1 at exit 0, truncated=undefined Nothing distinguishes "searched to the bottom" from "stopped looking". query phase-plan-index, a plan whose depends_on names an unresolvable token -> warnings: ["Plan 03-02: declared wave: 2 but depends_on DAG places it in wave 1"] The token is never mentioned. computeDependencyLevels drops the edge with `if (!resolvedDep) continue;`, every plan becomes a root, and the tool then reports the author's correct wave: as the thing that is wrong. countPhasePlansAndSummaries with fs.readdirSync throwing EACCES -> hasContext:false, indistinguishable from a phase that simply has no CONTEXT.md. context_read_error is undefined. The shapes these tests assert against, chosen here so the implementation has a target rather than inventing one later: `truncated: boolean` on the intel query result, `unresolved: Array<{plan, token}>` from computeDependencyLevels, and `context_read_error: string | null` per analyzed phase. Deliberately green, and they must stay that way — each stops the fix from over-firing: depth 48 is found and NOT flagged truncated (the ceiling is inclusive) a shallow miss reports no truncation (noise control, N1) 10,000 siblings at depth 2 are unaffected (the bound is DEPTH, N2) a genuine wave: mismatch on a fully-resolved DAG still warns (N3) a genuinely missing directory is absent, not an error the emitted depends_on display mapping still passes an unresolved token through verbatim — already pinned by the existing #3785 test, so no duplicate was added T31 asserts at the consumer's output per ADR-3180 Decision 4(b): it runs the real CLI and reads the emitted JSON, because a unit assertion on computeDependencyLevels would have passed throughout #3427's life. Design: .gsd/phase/feat-3885-no-silent-swallow/40-design.md Test matrix: .gsd/phase/feat-3885-no-silent-swallow/50-test-matrix.md Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * enhance(#3885): no silent swallow, and no verdict manufactured from dropped data Implements ADR-3473 §8.5. A failure or a gap in the input stops being absorbed into an output that reads as authoritative. The recursion bound, restored but NOT verbatim (src/intel.cts) MAX_JSON_SEARCH_DEPTH = 48 is threaded through searchJsonEntries and matchesInValue, which carried no depth parameter at all. The bound existed in the retired SDK lineage (sdk/src/query/intel.ts at 11918dcc3^) and the surviving .cts lineage never received it — §8.3's "a consolidation may not delete an invariant along with the surface that held it", demonstrated. Measured before: a .planning/intel file nested 12000 deep exits 1 with "Error: Maximum call stack size exceeded". Reachable from a project document. The original returned a bare `false` at the ceiling. Restoring that verbatim would trade a crash for a silent "no match" when the truth is "I stopped looking" — the same class this epic exists to close, and ADR-3473 Decision 4 forbids it. So the bound carries a truncation signal: nesting 47 -> found, truncated false nesting 48 -> found, truncated false (the ceiling is inclusive) nesting 49 -> not found, truncated TRUE nesting 12000 -> exit 0, truncated TRUE, no RangeError A shallow document that simply has no match reports truncated FALSE — the flag means "I stopped early", never "I found nothing", or it would be noise. The bound is on DEPTH: 10,000 siblings at depth 2 are unaffected. The dropped edge is named, and stops being blamed on the author (src/phase.cts) computeDependencyLevels dropped every unresolvable depends_on token with a bare `continue`. Each drop makes a plan a root, so the whole phase collapses to wave 1 — and cmdPhasePlanIndex then reported the author's CORRECT wave: as the thing that was wrong. Before: warnings: ["Plan 03-02: declared wave: 2 but depends_on DAG places it in wave 1"] After: warnings: ["Plan 03-02: depends_on token \"nonexistent-token-3427\" does not resolve to any plan in this phase — edge dropped, wave placement for this plan may be unreliable"] The suppression is PER PLAN, never blanket: a plan with a fully-resolved DAG and a genuinely wrong wave: still gets the mismatch warning. resolveDependencyId stays two-tier — the shortFormToId third tier is §8.3/Phase 6's rule and is deliberately not built here. The emitted depends_on display mapping still passes an unresolved token through verbatim (#3785). No artifact from failed inputs (gsd-core/workflows/review.md, #3352) A failed lane leaves no result file, so "every lane failed" is exactly "the aggregate JSONL has zero lines" — the gate condition already existed as a byproduct. REVIEWS.md is no longer written in that case, and the commit step is skipped with it. A budget-SKIPPED lane also leaves no file and is NOT counted as a failure. Per-lane output and non-empty .err are preserved to .review-diagnostics/ before `rm -rf "{run_dir}"` destroys the only record that the lanes failed at all; the commit step names one file, never a glob, so the diagnostics are not swept in. Unreadable is not absent (roadmap.cts, gap-checker.cts, init.cts x2) Four callers collapsed an EACCES on a phase directory into [] and reported hasContext:false — byte-identical to a phase that simply has no CONTEXT.md. Each now names the directory it could not read. A genuinely missing directory stays absent rather than becoming an error, which is what keeps the fix from over-firing. Fatal errno folded into a retry set: audited, no defect found Reported as a verified negative rather than padded with a change. withPlanningLock was fixed by #1884/PR #3472; acquireStateLock by #3776; atomicRenameWithRetry and estimate-cli's renameWithRetry are correct by construction — bounded set {EPERM,EBUSY,EACCES}, bounded attempts, and they return or rethrow the final error rather than swallowing it. estimate-cli's sole caller surfaces that rethrow as write_error in its JSON output. Manufacturing a diff to make the checkbox look worked-on is the Goodhart outcome Decision 6 exists to prevent. Disclosed: R46 (the commit step names one file, never a glob) is a real regression guard but is NOT independently failing-first — the commit fence is byte-identical pre- and post-fix, so it only fails pre-fix through its shared extraction dependency. Recorded rather than claimed as fail-first. Design: .gsd/phase/feat-3885-no-silent-swallow/40-design.md Test matrix: .gsd/phase/feat-3885-no-silent-swallow/50-test-matrix.md Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3885): escape untrusted tokens, and stop cleanup destroying unpreserved evidence Two review findings, both real, both in my own change. An isolated adversarial review found the evidence-preservation block never checked mkdir/cp exit status while `rm -rf "{run_dir}"` ran unconditionally in a SEPARATE fenced block. A disk-full or unwritable phase directory therefore still destroyed the only copy of the failed lanes' output — reintroducing the exact #3352 data loss this item exists to stop, inside the fix for it. Preservation and cleanup are now one block, because each fenced block is a separate execution and a shell variable cannot carry between them. mkdir -p and each cp are exit-checked; cleanup runs only when preservation succeeded, and a failure warns naming the intact run directory. "Nothing to preserve" is not a failure and still cleans up. Driven three ways: success removes run_dir, failure leaves it intact with the warning, nothing-to-preserve removes it. The failure is induced by a file-vs-directory conflict rather than chmod 0o000, which root bypasses. The new unresolved-depends_on warning embedded a user-authored token verbatim: warnings: ["Plan 03-02: depends_on token \"evil Plan 03-01: FORGED WARNING\" does not resolve ..."] The JSON wire form is safe, and the security reviewer judged it non-exploitable for that reason. It is escaped anyway through formatDiagnosticToken — the helper #3884 added one phase earlier for exactly this class. warnings[] is an array a consumer naturally prints line by line, and not reusing the sibling fix is the generative-fix-divergence shape this epic exists to close. The same treatment is applied to context_read_error / phase_dir_read_error, which embed a phase directory path a repository can choose, and to the fs error message, which echoes the raw path itself. Known limit L5 recorded: the bound is on DEPTH only. A 300,000-element shallow array yields a 14.5MB reply with truncated:false. Correct per §8.5 and per negative space N2, disclosed rather than left to be discovered. Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3885): unreadable is not absent in intel.cts either, and a corrupt snapshot is not "no snapshot" Blocker from the round-2 isolated review, and it is my own inconsistency: this phase applied "unreadable is not absent" to phase directories and left it broken in the file it was already editing. chmod 000 .planning/intel/file-roles.json gsd-tools intel query <term> -> {"matches":[],"total":0,"truncated":false} exit 0 safeReadJson swallowed every read failure and returned null, so an EACCES was byte-indistinguishable from an absent file AND from a genuine no-match. Now it separates three states: ENOENT stays silently absent, because not every project has every intel file and intelQuery loops over all of them expecting misses; EACCES/EIO and malformed JSON are both surfaced naming the file. A corrupt intel file previously read as "no matches" too — same defect, same fix. Threading that outcome through the other three callers found something worse than the reported case. intelDiff returned no_baseline:true for a corrupt or unreadable snapshot — not a silent failure but an actively FALSE verdict, telling the caller they never took a snapshot when they did. That is §8.5's headline case, so it is fixed and tested rather than noted. intelStatus and intelApiSurface collapsed the same way; intelApiSurface additionally printed a "not yet populated" banner that was simply untrue. Every row is failing-first, including the absent-file ones — the field is new, so it does not exist pre-fix at all. Those rows are not pre-fix pins; they pin that the fix does not OVER-fire on the ordinary absent case, which is what would turn this into noise on every project lacking an intel file. IO failure is injected by monkeypatching fs and restoring in finally, never chmod 0o000 — root bypasses mode bits, so the reviewer's manual chmod repro is not reproducible as a test. Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3885): build the pathological intel fixture as text, not by stringifying a nested object The remote runner came back red on Linux with two failures, both T4: deeplyNestedIntelDoesNotOverflowTheStack, while the same test passed on macOS. The product was never at fault. writeNestedFixture(12000) built a 12,000-deep JavaScript OBJECT and then JSON.stringify'd it. JSON.stringify recurses once per level, so it overflowed the TEST PROCESS's stack — the error was thrown before the CLI was ever spawned. Linux's container stack is smaller than macOS's, which is the whole of the platform difference. Measured, with the same document built as JSON TEXT so nothing in the building process recurses: depth=100 rc=0 truncated=true depth=5000 rc=0 truncated=true depth=12000 rc=0 truncated=true depth=60000 rc=0 truncated=true V8 parses this shape iteratively; only stringify recurses. The bound works at every depth tried. The fixture is now built by string concatenation. That is also the more faithful input — a real deeply nested JSON document on disk is exactly what the bound guards, where a stringified object was only ever a way to produce one. The depth stays 12000. Lowering it would have made the test pass by weakening it to accommodate a fixture bug, and 12000 is a legitimate pathological input the product handles. T4 remains a genuine fail-first: rebuilt against the parent of the commit that added the bound, the string-built depth-12000 fixture still drives the CLI to rc=1 with "Error: Maximum call stack size exceeded". A comment records why the fixture is text, so it is not "simplified" back into a macOS-green / Linux-red test. Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3885): backfill the changeset PR number Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3885): normalize path separators before splicing into the workflow's bash CI red on one lane — test (windows-latest, 24, shard 3/3). macOS, Linux and the remote runner were all green. AssertionError: commit must name the single REVIEWS.md file; got: --files C:UsersRUNNER~1AppDataLocalTempgsd-3352-phasedir-mOKmuy/03-REVIEWS.md Every backslash in C:\Users\RUNNER~1\AppData\Local\Temp\... was eaten. The harness spliced an OS-native temp path into the extracted bash, and bash consumes \U, \A, \L and \T as escapes on an unquoted expansion. The same loss broke RUN_DIR, so "rm -rf" targeted a path that never existed and the run directory survived — which is the other two assertions. This is a fixture defect, not a product one, and that was checked rather than assumed. In production the phase directory is toPosixPath-normalized at every call site that serializes it (bin/lib/init.cjs:951, 1381, 1461, 1529, 1595), and the run directory is created by "mktemp -d" running inside the bash block itself (gsd-core/workflows/review.md:163), which emits POSIX-style output even under Git-Bash on Windows. Neither ever carries a backslash where the workflow reads it. The file's pre-existing #3034 harness splices raw native paths too, but only ever inside double-quoted assignments, so it never tripped this — my new harness followed that convention faithfully into the one place where it does not hold. Both now splice through toPosixPath from shell-command-projection, the established seam, which is a no-op on POSIX and mirrors what production does. No assertion was weakened. "commit must name the single REVIEWS.md file" and "the run dir must still be destroyed" still assert exactly that; only how the fixture supplies its path changed. Nothing is skipped on Windows — a t.skip() here would have hidden the question of whether the exposure was real, which is the question that mattered. Driven both ways: a synthetic C:\Users\RUNNER~1\... input reproduces the exact CI string when unfixed and yields C:/Users/RUNNER~1/... when fixed; a POSIX input produces a byte-identical shape, proving the normalization is idempotent. Refs #3885 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3885): stop the harness making the deleted run dir its own cwd Windows shard 3/3 stayed red after the separator fix, on two assertions the separator fix never touched: AssertionError: the run dir must still be destroyed AssertionError: nothing to preserve is not a failure — run dir must still be removed The separators were a real bug and fixing them fixed the --files assertion. They were not this bug, and two CI cycles went into the wrong axis before I stopped converting path forms and looked at what the harness actually does. runWriteReviewsFlow passed cwd: runDir to runHook, so the child bash process's working directory WAS the directory the block under test then removes with rm -rf "$RUN_DIR". POSIX allows a process to delete its own cwd — verified locally, cd "$d"; rm -rf "$d" removes it cleanly — and Windows does not: a live process's working directory cannot be removed. So on Windows the directory survived and both assertions failed, on macOS and Linux it vanished and they passed. Nothing to do with slashes. Harness-only. Production never cd's into the run directory; every reference is by absolute path, and RUN_DIR is created by mktemp -d inside the bash block itself (gsd-core/workflows/review.md:165) rather than injected. review.md is unchanged. Fix: the child now runs with its cwd in an unrelated temp directory that the block under test never deletes. Neither assertion was weakened, and nothing is skipped on Windows — the tests in this file carry no platform guard and run there unconditionally, which is how this surfaced at all. Honest limit: the Windows failure mode cannot be reproduced on macOS, because POSIX permits the very thing Windows refuses. The diagnosis is grounded in that documented divergence and in the fact that only the Windows lane failed, but the green outcome on windows-latest is unverified until CI runs it. Refs #3885 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
@@ -20,7 +20,7 @@ import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import io = require('./io.cjs');
|
||||
const { output, error } = io;
|
||||
const { output, error, formatDiagnosticToken } = io;
|
||||
import { escapeRegex } from './pattern.cjs';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import planningWorkspace = require('./planning-workspace.cjs');
|
||||
@@ -67,6 +67,14 @@ interface GapResult {
|
||||
table: string;
|
||||
summary: string;
|
||||
counts: GapCounts;
|
||||
/**
|
||||
* #3885 (ADR-3473 §8.5): null when the phase directory is genuinely absent
|
||||
* (guarded by `fs.existsSync` before the read, so readdirSync is never even
|
||||
* attempted) or was read successfully. A message naming the phase directory
|
||||
* when it EXISTS but `readdirSync` failed (EACCES/EIO/...) — never
|
||||
* collapsed to the same `[]` an absent directory produces.
|
||||
*/
|
||||
phase_dir_read_error: string | null;
|
||||
}
|
||||
|
||||
interface RunGapAnalysisOptions {
|
||||
@@ -338,6 +346,7 @@ function runGapAnalysis(cwd: string, phaseDir: string, options: RunGapAnalysisOp
|
||||
table: '',
|
||||
summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
|
||||
counts: { total: 0, covered: 0, uncovered: 0 },
|
||||
phase_dir_read_error: null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -364,9 +373,16 @@ function runGapAnalysis(cwd: string, phaseDir: string, options: RunGapAnalysisOp
|
||||
// Read the phase directory once; reuse the listing for both context detection
|
||||
// and plan-file enumeration (avoids redundant readdirSync calls).
|
||||
let phaseDirFiles: string[] = [];
|
||||
// #3885 (ADR-3473 §8.5): the existsSync guard above already means a catch
|
||||
// here is NEVER "genuinely absent" (ENOENT) — this directory exists, so any
|
||||
// failure to list it is a real read error (EACCES/EIO/...) and must be
|
||||
// named, not folded into the same `[]` an absent directory produces.
|
||||
let phaseDirReadError: string | null = null;
|
||||
try {
|
||||
if (fs.existsSync(absPhaseDir)) phaseDirFiles = fs.readdirSync(absPhaseDir);
|
||||
} catch { /* unreadable */ }
|
||||
} catch (err) {
|
||||
phaseDirReadError = `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}: ${formatDiagnosticToken((err as Error)?.message ?? String(err))}`;
|
||||
}
|
||||
|
||||
// #3511-class: scope the raw listing to this phase dir before the
|
||||
// phase-numbered -CONTEXT.md predicate. `phaseDirFiles` itself stays raw —
|
||||
@@ -433,6 +449,7 @@ function runGapAnalysis(cwd: string, phaseDir: string, options: RunGapAnalysisOp
|
||||
table: formatGapTable(rows) + '\n' + coverageSummary + '\n\n' + mismatchMsg,
|
||||
summary: coverageSummary + '; extracted 0 of N — possible format mismatch',
|
||||
counts: { total: rows.length, covered, uncovered },
|
||||
phase_dir_read_error: phaseDirReadError,
|
||||
};
|
||||
}
|
||||
return {
|
||||
@@ -441,6 +458,7 @@ function runGapAnalysis(cwd: string, phaseDir: string, options: RunGapAnalysisOp
|
||||
table: mismatchMsg,
|
||||
summary: 'extracted 0 of N — possible format mismatch',
|
||||
counts: { total: 0, covered: 0, uncovered: 0 },
|
||||
phase_dir_read_error: phaseDirReadError,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -458,6 +476,7 @@ function runGapAnalysis(cwd: string, phaseDir: string, options: RunGapAnalysisOp
|
||||
table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
|
||||
summary: 'no requirements or decisions to check',
|
||||
counts: { total: 0, covered: 0, uncovered: 0 },
|
||||
phase_dir_read_error: phaseDirReadError,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -478,6 +497,7 @@ function runGapAnalysis(cwd: string, phaseDir: string, options: RunGapAnalysisOp
|
||||
table: formatGapTable(rows) + '\n' + summary + '\n',
|
||||
summary,
|
||||
counts: { total: rows.length, covered, uncovered },
|
||||
phase_dir_read_error: phaseDirReadError,
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
33
src/init.cts
33
src/init.cts
@@ -81,7 +81,7 @@ const {
|
||||
import verifyCommandGrounding = require('./verify-command-grounding.cjs');
|
||||
const { harvestPriorVerifyCommands } = verifyCommandGrounding;
|
||||
|
||||
const { output, error, ERROR_REASON } = io;
|
||||
const { output, error, ERROR_REASON, formatDiagnosticToken } = io;
|
||||
const { loadConfig, loadConfigResolved } = configLoader;
|
||||
const { resolveModelInternal, resolveGranularityInternal, assertValidGranularityOverride } = modelResolver;
|
||||
const { findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocator;
|
||||
@@ -1214,8 +1214,21 @@ function cmdInitPlanPhase(
|
||||
if (patternsFile) {
|
||||
result['patterns_path'] = toPosixPath(path.join(phaseDirFull, patternsFile));
|
||||
}
|
||||
} catch {
|
||||
/* intentionally empty */
|
||||
} catch (err) {
|
||||
// #3885 (ADR-3473 §8.5): this branch means `phaseInfo['directory']` was
|
||||
// set (the phase was already resolved to an on-disk directory) yet
|
||||
// `readdirSync` still failed — ENOENT here would be a genuine race
|
||||
// (the directory vanished between resolution and this read) and stays
|
||||
// a silent degrade like the prior behavior; any other errno
|
||||
// (EACCES/EIO/...) is an unreadable-not-absent directory and must be
|
||||
// named, or every conditional field this block sets (context_path,
|
||||
// research_path, verification_path, uat_path, reviews_path,
|
||||
// patterns_path) silently reads as "none of these exist".
|
||||
const code = (err as NodeJS.ErrnoException)?.code;
|
||||
if (code !== 'ENOENT') {
|
||||
result['context_read_error'] =
|
||||
`Could not read phase directory ${formatDiagnosticToken(phaseDirFull)}: ${formatDiagnosticToken((err as Error)?.message ?? String(err))}`;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2091,8 +2104,18 @@ function cmdInitPhaseOp(cwd: string, phase: string, raw: boolean): void {
|
||||
if (reviewsFile) {
|
||||
result['reviews_path'] = toPosixPath(path.join(phaseDirFull, reviewsFile));
|
||||
}
|
||||
} catch {
|
||||
/* intentionally empty */
|
||||
} catch (err) {
|
||||
// #3885 (ADR-3473 §8.5): see the parallel site in cmdInitPlanPhase —
|
||||
// ENOENT here is a genuine race (directory vanished after resolution)
|
||||
// and stays a silent degrade; any other errno (EACCES/EIO/...) means
|
||||
// the directory exists but could not be read, and must be named rather
|
||||
// than silently reported the same as "none of context_path/
|
||||
// research_path/verification_path/uat_path/reviews_path exist".
|
||||
const code = (err as NodeJS.ErrnoException)?.code;
|
||||
if (code !== 'ENOENT') {
|
||||
result['context_read_error'] =
|
||||
`Could not read phase directory ${formatDiagnosticToken(phaseDirFull)}: ${formatDiagnosticToken((err as Error)?.message ?? String(err))}`;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
176
src/intel.cts
176
src/intel.cts
@@ -21,6 +21,9 @@ import { platformWriteSync, platformReadSync, platformEnsureDir } from './shell-
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import capabilityStateMod = require('./capability-state.cjs');
|
||||
const { isCapabilityActive } = capabilityStateMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import ioMod = require('./io.cjs');
|
||||
const { formatDiagnosticToken } = ioMod;
|
||||
|
||||
// ─── Constants ───────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -34,6 +37,17 @@ const INTEL_FILES: Record<string, string> = {
|
||||
stack: 'stack.json',
|
||||
};
|
||||
|
||||
/**
|
||||
* ADR-3473 §8.5 / #3885: recursion bound for the intel JSON search walk.
|
||||
* Restored from the retired SDK lineage (`sdk/src/query/intel.ts` at `11918dcc3^`),
|
||||
* lost in the ADR-0174 consolidation. Unlike the original, hitting the ceiling is
|
||||
* NOT reported as a silent "no match" — the walk that stops early sets a
|
||||
* `truncated` flag threaded back up to `intelQuery`'s result (Decision 4: a
|
||||
* routine that discards an input says so). The bound is on DEPTH only; breadth
|
||||
* (sibling count at any given depth) is unaffected.
|
||||
*/
|
||||
const MAX_JSON_SEARCH_DEPTH = 48;
|
||||
|
||||
// ─── Internal helpers ────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
@@ -93,14 +107,39 @@ interface IntelData {
|
||||
|
||||
/**
|
||||
* Safely read and parse a JSON intel file.
|
||||
* Returns null if file doesn't exist or can't be parsed.
|
||||
*
|
||||
* Returns null for THREE distinct on-disk states, only one of which is a
|
||||
* "quiet" case (#3885, ADR-3473 §8.5):
|
||||
* - ABSENT (ENOENT, via platformReadSync returning null): silent — not
|
||||
* every project has every intel file, and callers already loop over
|
||||
* the full INTEL_FILES set expecting misses. Never pushed to `errors`.
|
||||
* - UNREADABLE (EACCES/EIO/... — platformReadSync rethrows anything that
|
||||
* isn't ENOENT): surfaced, naming the file, when `errors` is supplied.
|
||||
* - MALFORMED (JSON.parse throws on a file that WAS read successfully):
|
||||
* also surfaced, naming the file — a corrupt intel file used to read
|
||||
* identically to "no matches", which is the same defect one layer down.
|
||||
*
|
||||
* `errors` is an optional accumulator so callers that want to thread the
|
||||
* outcome into their own result shape can pass an array and read it back
|
||||
* after the call; callers that omit it keep the prior fold-to-null shape.
|
||||
*/
|
||||
function safeReadJson(filePath: string): IntelData | null {
|
||||
function safeReadJson(filePath: string, errors?: string[]): IntelData | null {
|
||||
let raw: string | null;
|
||||
try {
|
||||
raw = platformReadSync(filePath);
|
||||
} catch (err) {
|
||||
if (errors) {
|
||||
errors.push(`Could not read ${formatDiagnosticToken(filePath)}: ${formatDiagnosticToken((err as Error)?.message ?? String(err))}`);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
if (raw === null) return null; // ENOENT — genuinely absent, not an error.
|
||||
try {
|
||||
const raw = platformReadSync(filePath);
|
||||
if (raw === null) return null;
|
||||
return JSON.parse(raw) as IntelData;
|
||||
} catch {
|
||||
} catch (err) {
|
||||
if (errors) {
|
||||
errors.push(`Could not parse ${formatDiagnosticToken(filePath)}: ${formatDiagnosticToken((err as Error)?.message ?? String(err))}`);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -124,18 +163,34 @@ interface SearchMatch {
|
||||
value: unknown;
|
||||
}
|
||||
|
||||
interface SearchWalkResult {
|
||||
matches: SearchMatch[];
|
||||
truncated: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mutable walk state shared across one searchJsonEntries invocation's
|
||||
* recursive matchesInValue calls. Set to true the moment ANY branch of the
|
||||
* walk actually hits MAX_JSON_SEARCH_DEPTH and stops recursing further —
|
||||
* never inferred from an empty result (a shallow miss must not set this).
|
||||
*/
|
||||
interface SearchWalkState {
|
||||
truncated: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Search for a term (case-insensitive) in a JSON object's keys and string values.
|
||||
* Returns an array of matching entries.
|
||||
* Returns matching entries plus whether the walk hit MAX_JSON_SEARCH_DEPTH.
|
||||
*/
|
||||
function searchJsonEntries(data: IntelData, term: string): SearchMatch[] {
|
||||
if (!data || typeof data !== 'object') return [];
|
||||
function searchJsonEntries(data: IntelData, term: string): SearchWalkResult {
|
||||
if (!data || typeof data !== 'object') return { matches: [], truncated: false };
|
||||
|
||||
const entries = data.entries || data;
|
||||
if (!entries || typeof entries !== 'object') return [];
|
||||
if (!entries || typeof entries !== 'object') return { matches: [], truncated: false };
|
||||
|
||||
const lowerTerm = term.toLowerCase();
|
||||
const matches: SearchMatch[] = [];
|
||||
const state: SearchWalkState = { truncated: false };
|
||||
|
||||
for (const [key, value] of Object.entries(entries)) {
|
||||
if (key === '_meta') continue;
|
||||
@@ -146,27 +201,42 @@ function searchJsonEntries(data: IntelData, term: string): SearchMatch[] {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check string value match (recursive for objects)
|
||||
if (matchesInValue(value, lowerTerm)) {
|
||||
// Check string value match (recursive for objects/arrays, bounded by depth)
|
||||
if (matchesInValue(value, lowerTerm, 0, state)) {
|
||||
matches.push({ key, value });
|
||||
}
|
||||
}
|
||||
|
||||
return matches;
|
||||
return { matches, truncated: state.truncated };
|
||||
}
|
||||
|
||||
/**
|
||||
* Recursively check if a term appears in any string value.
|
||||
*
|
||||
* `depth` counts container unwraps already performed (starts at 0 for the
|
||||
* entry's own value). Strings never fail the ceiling check themselves — only
|
||||
* a container (object/array) refuses to recurse one level deeper once
|
||||
* `depth > MAX_JSON_SEARCH_DEPTH`, at which point `state.truncated` is set so
|
||||
* the caller can report "I stopped looking" rather than a bare "no match".
|
||||
* The bound is on nesting depth only, never on sibling breadth.
|
||||
*/
|
||||
function matchesInValue(value: unknown, lowerTerm: string): boolean {
|
||||
function matchesInValue(value: unknown, lowerTerm: string, depth: number, state: SearchWalkState): boolean {
|
||||
if (typeof value === 'string') {
|
||||
return value.toLowerCase().includes(lowerTerm);
|
||||
}
|
||||
if (Array.isArray(value)) {
|
||||
return value.some(v => matchesInValue(v, lowerTerm));
|
||||
if (depth > MAX_JSON_SEARCH_DEPTH) {
|
||||
state.truncated = true;
|
||||
return false;
|
||||
}
|
||||
return value.some(v => matchesInValue(v, lowerTerm, depth + 1, state));
|
||||
}
|
||||
if (value && typeof value === 'object') {
|
||||
return Object.values(value).some(v => matchesInValue(v, lowerTerm));
|
||||
if (depth > MAX_JSON_SEARCH_DEPTH) {
|
||||
state.truncated = true;
|
||||
return false;
|
||||
}
|
||||
return Object.values(value).some(v => matchesInValue(v, lowerTerm, depth + 1, state));
|
||||
}
|
||||
return false;
|
||||
}
|
||||
@@ -177,6 +247,26 @@ interface IntelQueryResult {
|
||||
matches: Array<{ source: string; entries: SearchMatch[] }>;
|
||||
term: string;
|
||||
total: number;
|
||||
/**
|
||||
* True iff ANY searched intel file's walk hit MAX_JSON_SEARCH_DEPTH and
|
||||
* stopped early. Never true merely because nothing was found (a shallow
|
||||
* miss is not a truncation) — always present as a boolean, never undefined.
|
||||
*/
|
||||
truncated: boolean;
|
||||
/**
|
||||
* #3885 (ADR-3473 §8.5): one diagnostic string per intel file that was
|
||||
* present on disk but could not be read (EACCES/EIO/...) or could not be
|
||||
* parsed (malformed JSON) — each naming the file via formatDiagnosticToken.
|
||||
* A file that is simply ABSENT (ENOENT) never contributes an entry here;
|
||||
* that is the normal, expected case (not every project has every intel
|
||||
* file). Always present as an array, never undefined — empty when every
|
||||
* searched file was either absent or read cleanly, mirroring `truncated`'s
|
||||
* always-present convention. Plural (unlike `context_read_error`'s
|
||||
* singular nullable-string shape in roadmap.cts/init.cts) because a single
|
||||
* query fans out across every file in INTEL_FILES and more than one can
|
||||
* independently fail.
|
||||
*/
|
||||
read_errors: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -188,27 +278,38 @@ function intelQuery(term: string, planningDir: string): IntelQueryResult | Disab
|
||||
|
||||
const matches: Array<{ source: string; entries: SearchMatch[] }> = [];
|
||||
let total = 0;
|
||||
let truncated = false;
|
||||
const readErrors: string[] = [];
|
||||
|
||||
// Search all JSON intel files
|
||||
for (const [_key, filename] of Object.entries(INTEL_FILES)) {
|
||||
const filePath = intelFilePath(planningDir, filename);
|
||||
const data = safeReadJson(filePath);
|
||||
const data = safeReadJson(filePath, readErrors);
|
||||
if (!data) continue;
|
||||
|
||||
const found = searchJsonEntries(data, term);
|
||||
const { matches: found, truncated: fileTruncated } = searchJsonEntries(data, term);
|
||||
if (fileTruncated) truncated = true;
|
||||
if (found.length > 0) {
|
||||
matches.push({ source: filename, entries: found });
|
||||
total += found.length;
|
||||
}
|
||||
}
|
||||
|
||||
return { matches, term, total };
|
||||
return { matches, term, total, truncated, read_errors: readErrors };
|
||||
}
|
||||
|
||||
interface IntelStatusFileEntry {
|
||||
exists: boolean;
|
||||
updated_at: string | null;
|
||||
stale: boolean;
|
||||
/**
|
||||
* #3885 (ADR-3473 §8.5): non-null iff the file exists but could not be
|
||||
* read or parsed — naming the file. `stale` still defaults to true in
|
||||
* that case (an unknown-freshness file is conservatively treated as
|
||||
* stale, unchanged from prior behaviour), but this field says WHY rather
|
||||
* than leaving the reader to assume the file was simply never refreshed.
|
||||
*/
|
||||
read_error: string | null;
|
||||
}
|
||||
|
||||
interface IntelStatusResult {
|
||||
@@ -233,7 +334,7 @@ function intelStatus(planningDir: string): IntelStatusResult | DisabledResponse
|
||||
const exists = fs.existsSync(filePath);
|
||||
|
||||
if (!exists) {
|
||||
files[filename] = { exists: false, updated_at: null, stale: true };
|
||||
files[filename] = { exists: false, updated_at: null, stale: true, read_error: null };
|
||||
overallStale = true;
|
||||
continue;
|
||||
}
|
||||
@@ -241,7 +342,8 @@ function intelStatus(planningDir: string): IntelStatusResult | DisabledResponse
|
||||
let updatedAt: string | null = null;
|
||||
|
||||
// All intel files are JSON — read _meta.updated_at
|
||||
const data = safeReadJson(filePath);
|
||||
const readErrors: string[] = [];
|
||||
const data = safeReadJson(filePath, readErrors);
|
||||
if (data && data._meta && data._meta.updated_at) {
|
||||
updatedAt = data._meta.updated_at;
|
||||
}
|
||||
@@ -253,7 +355,7 @@ function intelStatus(planningDir: string): IntelStatusResult | DisabledResponse
|
||||
}
|
||||
|
||||
if (stale) overallStale = true;
|
||||
files[filename] = { exists: true, updated_at: updatedAt, stale };
|
||||
files[filename] = { exists: true, updated_at: updatedAt, stale, read_error: readErrors[0] ?? null };
|
||||
}
|
||||
|
||||
return { files, overall_stale: overallStale };
|
||||
@@ -268,14 +370,20 @@ interface IntelDiffResult {
|
||||
/**
|
||||
* Show changes since the last full refresh by comparing file hashes.
|
||||
*/
|
||||
function intelDiff(planningDir: string): IntelDiffResult | { no_baseline: true } | DisabledResponse {
|
||||
function intelDiff(planningDir: string): IntelDiffResult | { no_baseline: true; read_error: string | null } | DisabledResponse {
|
||||
if (!isIntelCapabilityActive(planningDir)) return disabledResponse();
|
||||
|
||||
const snapshotPath = intelFilePath(planningDir, '.last-refresh.json');
|
||||
const snapshot = safeReadJson(snapshotPath);
|
||||
const readErrors: string[] = [];
|
||||
const snapshot = safeReadJson(snapshotPath, readErrors);
|
||||
|
||||
if (!snapshot) {
|
||||
return { no_baseline: true };
|
||||
// #3885 (ADR-3473 §8.5): `no_baseline: true` stays true for BOTH a
|
||||
// genuinely-never-snapshotted project (ENOENT, read_error stays null)
|
||||
// AND a present-but-unreadable/malformed snapshot — collapsing those
|
||||
// two into a bare `no_baseline: true` would manufacture "you've never
|
||||
// run a refresh" out of a read failure. `read_error` names which one.
|
||||
return { no_baseline: true, read_error: readErrors[0] ?? null };
|
||||
}
|
||||
|
||||
const prevHashes = (snapshot.hashes as Record<string, string> | undefined) || {};
|
||||
@@ -457,6 +565,12 @@ interface IntelApiSurfaceResult {
|
||||
written: string;
|
||||
symbolCount: number;
|
||||
stale: boolean;
|
||||
/**
|
||||
* #3885 (ADR-3473 §8.5): non-null iff api-map.json exists but could not
|
||||
* be read or parsed — naming the file. Null when api-map.json is simply
|
||||
* absent (the normal "not yet populated" case) or was read cleanly.
|
||||
*/
|
||||
read_error: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -472,7 +586,9 @@ function intelApiSurface(planningDir: string): IntelApiSurfaceResult | DisabledR
|
||||
const apiMapPath = path.join(intelPath, INTEL_FILES.apis);
|
||||
const outputPath = path.join(intelPath, 'API-SURFACE.md');
|
||||
|
||||
const data = safeReadJson(apiMapPath);
|
||||
const readErrors: string[] = [];
|
||||
const data = safeReadJson(apiMapPath, readErrors);
|
||||
const readError = readErrors[0] ?? null;
|
||||
const entries = (data && data.entries && typeof data.entries === 'object')
|
||||
? Object.entries(data.entries)
|
||||
: [];
|
||||
@@ -493,7 +609,13 @@ function intelApiSurface(planningDir: string): IntelApiSurfaceResult | DisabledR
|
||||
lines.push('');
|
||||
|
||||
if (symbolCount === 0) {
|
||||
lines.push('> **Incomplete:** api-map.json has no entries (intel extraction is regex/JS-only or not yet populated).');
|
||||
if (readError) {
|
||||
// #3885: a read/parse failure is NOT "not yet populated" — say so,
|
||||
// rather than manufacturing the wrong reason for the empty surface.
|
||||
lines.push(`> **Incomplete:** ${readError}`);
|
||||
} else {
|
||||
lines.push('> **Incomplete:** api-map.json has no entries (intel extraction is regex/JS-only or not yet populated).');
|
||||
}
|
||||
lines.push('> Treat absence here as "unknown", not "does not exist".');
|
||||
lines.push('');
|
||||
} else {
|
||||
@@ -517,7 +639,7 @@ function intelApiSurface(planningDir: string): IntelApiSurfaceResult | DisabledR
|
||||
|
||||
platformWriteSync(outputPath, lines.join('\n'));
|
||||
|
||||
return { written: outputPath, symbolCount, stale };
|
||||
return { written: outputPath, symbolCount, stale, read_error: readError };
|
||||
}
|
||||
|
||||
interface IntelPatchMetaResult {
|
||||
|
||||
@@ -20,7 +20,7 @@ import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
|
||||
import ioMod = require('./io.cjs');
|
||||
const { output, error, ERROR_REASON } = ioMod;
|
||||
const { output, error, ERROR_REASON, formatDiagnosticToken } = ioMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import stateContract = require('./state-contract.cjs');
|
||||
const { publishStateContract } = stateContract;
|
||||
@@ -634,17 +634,26 @@ function computeDependencyLevels(
|
||||
rawPlans: RawPlan[],
|
||||
planMap: Map<string, RawPlan>,
|
||||
canonicalToId: Map<string, string>,
|
||||
): { level: Map<string, number>; visited: number; order: string[] } {
|
||||
): { level: Map<string, number>; visited: number; order: string[]; unresolved: Array<{ plan: string; token: string }> } {
|
||||
const level = new Map<string, number>();
|
||||
const inDeg = new Map<string, number>();
|
||||
const adj = new Map<string, string[]>();
|
||||
// #3427 / ADR-3473 §8.5: a depends_on token that resolves via neither
|
||||
// planMap nor canonicalToId is a dropped edge. Naming it here (rather than
|
||||
// silently `continue`-ing past it) lets cmdPhasePlanIndex surface the
|
||||
// token's own warning instead of manufacturing a wave-mismatch verdict from
|
||||
// the resulting damaged graph (#3427).
|
||||
const unresolved: Array<{ plan: string; token: string }> = [];
|
||||
|
||||
for (const p of rawPlans) {
|
||||
if (!inDeg.has(p.id)) inDeg.set(p.id, 0);
|
||||
if (!adj.has(p.id)) adj.set(p.id, []);
|
||||
for (const dep of p.dependsOn) {
|
||||
const resolvedDep = resolveDependencyId(dep, planMap, canonicalToId);
|
||||
if (!resolvedDep) continue;
|
||||
if (!resolvedDep) {
|
||||
unresolved.push({ plan: p.id, token: String(dep) });
|
||||
continue;
|
||||
}
|
||||
if (!adj.has(resolvedDep)) adj.set(resolvedDep, []);
|
||||
(adj.get(resolvedDep) as string[]).push(p.id);
|
||||
inDeg.set(p.id, (inDeg.get(p.id) ?? 0) + 1);
|
||||
@@ -679,7 +688,7 @@ function computeDependencyLevels(
|
||||
}
|
||||
}
|
||||
|
||||
return { level, visited, order: queue };
|
||||
return { level, visited, order: queue, unresolved };
|
||||
}
|
||||
|
||||
function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
|
||||
@@ -858,7 +867,7 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
|
||||
rawPlans.map((p) => [extractCanonicalPlanId(p.id).toLowerCase(), p.id]),
|
||||
);
|
||||
|
||||
const { level, visited, order } = computeDependencyLevels(rawPlans, planMap, canonicalToId);
|
||||
const { level, visited, order, unresolved } = computeDependencyLevels(rawPlans, planMap, canonicalToId);
|
||||
|
||||
if (visited < rawPlans.length) {
|
||||
const cycleNodes = rawPlans.filter((p) => !level.has(p.id)).map((p) => p.id);
|
||||
@@ -894,6 +903,20 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
|
||||
let hasCheckpoints = false;
|
||||
const warnings: string[] = [];
|
||||
|
||||
// #3427 / ADR-3473 §8.5: name every dropped depends_on edge (plan AND
|
||||
// token) rather than letting it silently collapse the plan to a DAG root.
|
||||
// A plan with at least one unresolved token gets ITS OWN warning here and
|
||||
// the wave-mismatch verdict below is suppressed for that plan ONLY — a
|
||||
// plan with no dropped edges and a genuinely wrong `wave:` still warns
|
||||
// (N3, D6, T25).
|
||||
const plansWithUnresolvedTokens = new Set<string>();
|
||||
for (const { plan, token } of unresolved) {
|
||||
plansWithUnresolvedTokens.add(plan);
|
||||
warnings.push(
|
||||
`Plan ${plan}: depends_on token ${formatDiagnosticToken(token)} does not resolve to any plan in this phase — edge dropped, wave placement for this plan may be unreliable`,
|
||||
);
|
||||
}
|
||||
|
||||
for (const rawPlan of rawPlans) {
|
||||
if (!rawPlan.autonomous) {
|
||||
hasCheckpoints = true;
|
||||
@@ -911,7 +934,17 @@ function cmdPhasePlanIndex(cwd: string, phase: string, raw: boolean): void {
|
||||
|
||||
const computedWave = (level.get(rawPlan.id) ?? 0) + levelOffset;
|
||||
const effectiveWave = computedWave;
|
||||
if (rawPlan.declaredWave !== null && rawPlan.declaredWave !== computedWave) {
|
||||
// #3427 (D5/N3): suppress the wave-mismatch verdict for a plan that has
|
||||
// at least one unresolved depends_on token — its own dropped-edge
|
||||
// warning above already explains the degraded wave placement, so the
|
||||
// mismatch here would blame the author for a DAG the tool itself
|
||||
// couldn't build. A plan with NO unresolved tokens still gets a genuine
|
||||
// mismatch reported (N3, T25) — the suppression is per-plan, never blanket.
|
||||
if (
|
||||
rawPlan.declaredWave !== null &&
|
||||
rawPlan.declaredWave !== computedWave &&
|
||||
!plansWithUnresolvedTokens.has(rawPlan.id)
|
||||
) {
|
||||
warnings.push(
|
||||
`Plan ${rawPlan.id}: declared wave: ${rawPlan.declaredWave} but depends_on DAG places it in wave ${computedWave}`,
|
||||
);
|
||||
|
||||
@@ -13,7 +13,7 @@ import { escapeRegex } from './pattern.cjs';
|
||||
import { splitLines, detectEol, joinLines } from './text-lines.cjs';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import ioMod = require('./io.cjs');
|
||||
const { output, error } = ioMod;
|
||||
const { output, error, formatDiagnosticToken } = ioMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import phaseIdMod = require('./phase-id.cjs');
|
||||
const { normalizePhaseName, phaseMarkdownRegexSource, matchPhaseDirs, stripProjectCodePrefix, OPTIONAL_PHASE_TAG_SOURCE, roadmapPhaseLookupSources, isSentinelPhaseId, scopeToPhase } = phaseIdMod;
|
||||
@@ -58,6 +58,15 @@ interface PhasePlansAndSummaries {
|
||||
summaryCount: number;
|
||||
hasContext: boolean;
|
||||
hasResearch: boolean;
|
||||
/**
|
||||
* #3885 (ADR-3473 §8.5): null when the phase directory's readdirSync
|
||||
* succeeded OR was genuinely absent (ENOENT — a real "not built yet"
|
||||
* answer, not an error). A message naming the phase directory when
|
||||
* readdirSync failed for any other reason (EACCES/EIO/...), so an
|
||||
* unreadable directory is never silently reported the same as one that was
|
||||
* successfully read and genuinely has no CONTEXT.md.
|
||||
*/
|
||||
contextReadError: string | null;
|
||||
}
|
||||
|
||||
interface PhaseSearchResult {
|
||||
@@ -118,7 +127,20 @@ function countPhasePlansAndSummaries(phaseDir: string): PhasePlansAndSummaries {
|
||||
// hasContext and hasResearch are not plan-scan concerns — read the directory
|
||||
// once and share the listing for all non-plan metadata that cmdRoadmapAnalyze needs.
|
||||
let phaseFiles: string[] = [];
|
||||
try { phaseFiles = fs.readdirSync(phaseDir); } catch { /* empty */ }
|
||||
// #3885 (ADR-3473 §8.5): distinguish "genuinely absent" (ENOENT) from
|
||||
// "could not read" (EACCES/EIO/...) — the collapse of both to an empty
|
||||
// listing is exactly the defect class this item closes. Mirrors
|
||||
// core-utils.cts's getPhaseFileStats / phase-locator.cts's
|
||||
// listMilestonePhaseDirs SCOPE.UNREADABLE discriminator.
|
||||
let contextReadError: string | null = null;
|
||||
try {
|
||||
phaseFiles = fs.readdirSync(phaseDir);
|
||||
} catch (err) {
|
||||
const code = (err as NodeJS.ErrnoException)?.code;
|
||||
if (code !== 'ENOENT') {
|
||||
contextReadError = `Could not read phase directory ${formatDiagnosticToken(phaseDir)}: ${formatDiagnosticToken((err as Error)?.message ?? String(err))}`;
|
||||
}
|
||||
}
|
||||
// #3511: scope the raw listing to this phase dir before the
|
||||
// phase-numbered-artifact predicates (hasContext/hasResearch) — planCount/
|
||||
// summaryCount above stay on scanPhasePlans's own unscoped listing since a
|
||||
@@ -130,6 +152,7 @@ function countPhasePlansAndSummaries(phaseDir: string): PhasePlansAndSummaries {
|
||||
summaryCount,
|
||||
hasContext: findContextMdIn(scopedFiles) !== null,
|
||||
hasResearch: scopedFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
|
||||
contextReadError,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -364,6 +387,8 @@ type AnalyzePhase = {
|
||||
has_research: boolean;
|
||||
disk_status: string;
|
||||
roadmap_complete: boolean;
|
||||
/** #3885 (ADR-3473 §8.5): see PhasePlansAndSummaries.contextReadError. */
|
||||
context_read_error: string | null;
|
||||
};
|
||||
|
||||
/**
|
||||
@@ -417,6 +442,10 @@ function collectAnalyzePhases(content: string, phasesDir: string, phaseDirNames:
|
||||
let summaryCount = 0;
|
||||
let hasContext = false;
|
||||
let hasResearch = false;
|
||||
// #3885 (ADR-3473 §8.5): null unless dirMatch resolves and its readdirSync
|
||||
// hit a non-ENOENT error — no directory at all is `disk_status:
|
||||
// 'no_directory'`, a real (if uninteresting) answer, not a read error.
|
||||
let contextReadError: string | null = null;
|
||||
|
||||
// DEAD catch removed (#2245 audit): matchPhaseDirs(...) is a pure
|
||||
// array lookup on an already-resolved string array, and
|
||||
@@ -432,6 +461,7 @@ function collectAnalyzePhases(content: string, phasesDir: string, phaseDirNames:
|
||||
summaryCount = counts.summaryCount;
|
||||
hasContext = counts.hasContext;
|
||||
hasResearch = counts.hasResearch;
|
||||
contextReadError = counts.contextReadError;
|
||||
|
||||
// ADR-3180 §7.4 (issue #3186, disk-strict, #3168 fix): route "is this
|
||||
// phase complete" through the canonical owner (`isPhaseComplete`),
|
||||
@@ -478,6 +508,7 @@ function collectAnalyzePhases(content: string, phasesDir: string, phaseDirNames:
|
||||
has_research: hasResearch,
|
||||
disk_status: diskStatus,
|
||||
roadmap_complete: roadmapComplete,
|
||||
context_read_error: contextReadError,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -494,12 +525,18 @@ function collectAnalyzePhases(content: string, phasesDir: string, phaseDirNames:
|
||||
let tSummaryCount = 0;
|
||||
let tHasContext = false;
|
||||
let tHasResearch = false;
|
||||
let tContextReadError: string | null = null;
|
||||
if (dirMatchA) {
|
||||
const counts = countPhasePlansAndSummaries(path.join(phasesDir, dirMatchA));
|
||||
tPlanCount = counts.planCount;
|
||||
tSummaryCount = counts.summaryCount;
|
||||
tHasContext = fs.existsSync(path.join(phasesDir, dirMatchA, 'CONTEXT.md'));
|
||||
tHasResearch = fs.existsSync(path.join(phasesDir, dirMatchA, 'RESEARCH.md'));
|
||||
// #3885 (ADR-3473 §8.5): reuse the SAME countPhasePlansAndSummaries call's
|
||||
// discriminator — this row's hasContext/hasResearch are read via a direct
|
||||
// existsSync (which cannot itself distinguish EACCES from absent), but
|
||||
// an unreadable phase directory is still surfaced via the sibling call.
|
||||
tContextReadError = counts.contextReadError;
|
||||
}
|
||||
phases.push({
|
||||
number: tr.id,
|
||||
@@ -513,6 +550,7 @@ function collectAnalyzePhases(content: string, phasesDir: string, phaseDirNames:
|
||||
has_research: tHasResearch,
|
||||
disk_status: dirMatchA ? 'ok' : 'no_directory',
|
||||
roadmap_complete: false,
|
||||
context_read_error: tContextReadError,
|
||||
});
|
||||
}
|
||||
return phases;
|
||||
|
||||
Reference in New Issue
Block a user