rungate 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +184 -88
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/owned-files.ts +42 -2
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +128 -73
- package/lib/scaffold/write-steps.ts +6 -4
- package/lib/scanner.ts +38 -12
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/suite-run-reading.ts +170 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/package.json +1 -1
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +4 -1
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
package/lib/create-sc.ts
CHANGED
|
@@ -9,7 +9,9 @@ import { join, dirname } from "path";
|
|
|
9
9
|
import { fileURLToPath } from "url";
|
|
10
10
|
|
|
11
11
|
import type { ScRegistry } from "./sc-ids";
|
|
12
|
-
import { isFixtureScId } from "./sc-ids";
|
|
12
|
+
import { isFixtureScId, scIdsSpelledInSource, SC_SOURCE_DIRS } from "./sc-ids";
|
|
13
|
+
import type { ScNamespaceReading, SourceReading } from "./sc-id-cross-tree";
|
|
14
|
+
import { readScNamespace } from "./sc-id-cross-tree";
|
|
13
15
|
import { tryLoadRungateConfig } from "./config-loader";
|
|
14
16
|
|
|
15
17
|
// ── Types ─────────────────────────────────────────────────────
|
|
@@ -267,6 +269,18 @@ export function listPatterns(): string {
|
|
|
267
269
|
* collision this function exists to prevent. The reservation is enforced
|
|
268
270
|
* against specs by SC-1524, not by making the allocator pretend.
|
|
269
271
|
*/
|
|
272
|
+
/**
|
|
273
|
+
* The ids a spec's own text spells, as one binding.
|
|
274
|
+
*
|
|
275
|
+
* The allocator counts them and the reading reports how many it counted; two
|
|
276
|
+
* scans of the same string would be two deciders that agree, and a reading
|
|
277
|
+
* whose numbers come from a different pattern than the allocation used is a
|
|
278
|
+
* reading of something else.
|
|
279
|
+
*/
|
|
280
|
+
function idsInSpecContent(specContent: string): string[] {
|
|
281
|
+
return [...specContent.matchAll(/SC-(\d+)/g)].map(m => m[0]);
|
|
282
|
+
}
|
|
283
|
+
|
|
270
284
|
export function nextSCNumber(
|
|
271
285
|
specContent: string,
|
|
272
286
|
reg?: ScRegistry,
|
|
@@ -277,15 +291,87 @@ export function nextSCNumber(
|
|
|
277
291
|
const n = Number(raw.replace(/^SC-[A-Z]?/, ""));
|
|
278
292
|
if (Number.isFinite(n)) ids.push(n);
|
|
279
293
|
};
|
|
280
|
-
const
|
|
281
|
-
let match;
|
|
282
|
-
while ((match = pattern.exec(specContent)) !== null) take(match[0]);
|
|
294
|
+
for (const raw of idsInSpecContent(specContent)) take(raw);
|
|
283
295
|
for (const id of reg?.declaredById.keys() ?? []) take(id);
|
|
284
296
|
for (const id of spelledInSource ?? []) if (!isFixtureScId(id)) take(id);
|
|
285
297
|
if (ids.length === 0) return 1;
|
|
286
298
|
return Math.max(...ids) + 1;
|
|
287
299
|
}
|
|
288
300
|
|
|
301
|
+
/**
|
|
302
|
+
* The next free SC number for a project, over every namespace this machine
|
|
303
|
+
* can see (#503).
|
|
304
|
+
*
|
|
305
|
+
* `nextSCNumber` answers the question for the arguments it is handed, and
|
|
306
|
+
* three widths of that question have each been wrong in turn: one spec's
|
|
307
|
+
* content (#392), the spec registry without test fixtures (#399), and the
|
|
308
|
+
* registry of whichever working tree the command ran in (#503). This is the
|
|
309
|
+
* composition, in one place, so a caller cannot assemble two of the three and
|
|
310
|
+
* believe it asked.
|
|
311
|
+
*
|
|
312
|
+
* It returns the reading alongside the number because the number is a FLOOR:
|
|
313
|
+
* a clone on another machine is outside anything this process can reach, and
|
|
314
|
+
* a caller that printed only the number would be claiming a guarantee the
|
|
315
|
+
* reading explicitly does not give.
|
|
316
|
+
*
|
|
317
|
+
* ## `reg` is REQUIRED, and was optional for two issues (#593)
|
|
318
|
+
*
|
|
319
|
+
* Omit it and `nextSCNumber` skips `reg.declaredById` entirely: the answer is
|
|
320
|
+
* assembled from the spec's own content, source-spelled fixtures and the
|
|
321
|
+
* cross-tree namespace, and the spec registry — the width #392 was filed
|
|
322
|
+
* over — is not consulted at all. The number comes back looking exactly like
|
|
323
|
+
* one that had asked everything, which is the composition failure the
|
|
324
|
+
* paragraph above says this function exists to make impossible. A caller
|
|
325
|
+
* with no registry to hand has `buildScRegistry([])`, which states "this
|
|
326
|
+
* tree declares nothing" instead of defaulting to it.
|
|
327
|
+
*
|
|
328
|
+
* The two readings agree whenever every spec-declared id is also spelled in
|
|
329
|
+
* a source file, which is most of the time and is why nothing noticed. They
|
|
330
|
+
* diverged the day a spec declared eight criteria no test mentioned yet.
|
|
331
|
+
*
|
|
332
|
+
* ## The reading names every leg, not just the cross-tree ones
|
|
333
|
+
*
|
|
334
|
+
* `readScNamespace` accounts for the worktrees and refs it read. The other
|
|
335
|
+
* three widths were invisible in the returned reading, so a CLI could print
|
|
336
|
+
* the number and a complete-looking account of where it came from while one
|
|
337
|
+
* of the legs behind it had never run. They are appended as sources of their
|
|
338
|
+
* own, with the count each contributed — `0` from a leg that was consulted
|
|
339
|
+
* and `0` from a leg that was skipped are the same number and opposite
|
|
340
|
+
* facts (`.claude/rules/config-access.md`).
|
|
341
|
+
*/
|
|
342
|
+
export function allocateScNumber(
|
|
343
|
+
root: string,
|
|
344
|
+
specContent: string,
|
|
345
|
+
reg: ScRegistry,
|
|
346
|
+
): { number: number; namespace: ScNamespaceReading } {
|
|
347
|
+
const namespace = readScNamespace(root);
|
|
348
|
+
const spelled = [...scIdsSpelledInSource(root).keys()];
|
|
349
|
+
const number = nextSCNumber(specContent, reg, [...spelled, ...namespace.ids.keys()]);
|
|
350
|
+
|
|
351
|
+
const legs: SourceReading[] = [
|
|
352
|
+
{
|
|
353
|
+
label: "the spec's own content",
|
|
354
|
+
kind: "spec-content",
|
|
355
|
+
status: "read",
|
|
356
|
+
found: new Set(idsInSpecContent(specContent)).size,
|
|
357
|
+
},
|
|
358
|
+
{
|
|
359
|
+
label: "spec registry (every declared id, checkbox and heading)",
|
|
360
|
+
kind: "registry",
|
|
361
|
+
status: "read",
|
|
362
|
+
found: reg.declaredById.size,
|
|
363
|
+
},
|
|
364
|
+
{
|
|
365
|
+
label: `SC ids spelled under ${SC_SOURCE_DIRS.join(", ")}`,
|
|
366
|
+
kind: "source-mentions",
|
|
367
|
+
status: "read",
|
|
368
|
+
found: new Set(spelled).size,
|
|
369
|
+
},
|
|
370
|
+
];
|
|
371
|
+
|
|
372
|
+
return { number, namespace: { ...namespace, sources: [...legs, ...namespace.sources] } };
|
|
373
|
+
}
|
|
374
|
+
|
|
289
375
|
/**
|
|
290
376
|
* Format an SC line for appending to a spec file.
|
|
291
377
|
*/
|
package/lib/doc-scan-targets.ts
CHANGED
|
@@ -393,6 +393,15 @@ export function planDocScan(projectPath: string): DocScanPlan {
|
|
|
393
393
|
if (real === null) { st.refused.push(path); continue; }
|
|
394
394
|
if (st.seen.has(real)) continue;
|
|
395
395
|
st.seen.add(real);
|
|
396
|
+
// A name is not a file type. `walkMarkdown` asks `statSync` before it
|
|
397
|
+
// decides; this loop asked only the suffix, so a DIRECTORY called
|
|
398
|
+
// `NOTES.md` at the project root was planned as a document and handed
|
|
399
|
+
// to `readFileSync`, which throws EISDIR — the plan claimed a file it
|
|
400
|
+
// could never read (#508). Nothing reports it either way: a directory
|
|
401
|
+
// with a markdown name carries no prose.
|
|
402
|
+
let isFile: boolean;
|
|
403
|
+
try { isFile = statSync(real).isFile(); } catch { continue; }
|
|
404
|
+
if (!isFile) continue;
|
|
396
405
|
if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
|
|
397
406
|
st.files.push(anchored(projectPath, st.rootReal, real));
|
|
398
407
|
}
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Moving an agent-authored evidence command from discovery to the state file,
|
|
3
|
+
* and recording every legitimate change made to one on the way (#614).
|
|
4
|
+
*
|
|
5
|
+
* ## The defect this module exists for
|
|
6
|
+
*
|
|
7
|
+
* `workflows/ship.js` persisted discovery's ACs by interpolating
|
|
8
|
+
* `JSON.stringify(discovery.acs…)` into a DOUBLE-QUOTED `bun -e "…"` shell
|
|
9
|
+
* string in the setup agent's prompt. Inside double quotes a shell expands
|
|
10
|
+
* `$1` to the empty string, `${VAR}` to the environment, and `$(cmd)` by
|
|
11
|
+
* RUNNING it. On run `wf_c92dd0a7-fe6` the command
|
|
12
|
+
*
|
|
13
|
+
* grep -rhcE '^export function localCalendarDay' lib | awk '{s+=$1} END {print s+0}'
|
|
14
|
+
*
|
|
15
|
+
* arrived in `workflow-state.json` as `awk '{s+=} END {print s+0}'` — an awk
|
|
16
|
+
* syntax error. The AC could never produce evidence, stayed PENDING, and took
|
|
17
|
+
* the verify gate down with four failures. The blast radius was every evidence
|
|
18
|
+
* command containing a `$`.
|
|
19
|
+
*
|
|
20
|
+
* The fix is to stop putting agent-authored text where a shell looks. The
|
|
21
|
+
* payload leaves the generator as a SINGLE-QUOTED argument — the one shell
|
|
22
|
+
* construct with no expansion inside it at all — and the `bun -e` program
|
|
23
|
+
* reads it out of `process.argv` instead of carrying it as program text.
|
|
24
|
+
*
|
|
25
|
+
* ## Why the provenance half is in the same module
|
|
26
|
+
*
|
|
27
|
+
* Three places legitimately rewrite an evidence command: discovery's path
|
|
28
|
+
* normaliser, discovery's evidence-type-ratio upgrade, and the git-ref
|
|
29
|
+
* qualification at the execution boundary (#118). Each used to overwrite
|
|
30
|
+
* `evidenceMethod.command` in place, so a reader of a broken command could not
|
|
31
|
+
* tell a repair from a corruption — which is exactly the question #614 took a
|
|
32
|
+
* run and a post-mortem to answer. `recordEvidenceRewrite` is the single site
|
|
33
|
+
* that changes a command, and it keeps the FIRST authored form.
|
|
34
|
+
*
|
|
35
|
+
* It belongs here because it is the same claim from the other side: the first
|
|
36
|
+
* half says nothing may change the command by accident, the second says
|
|
37
|
+
* everything that changes it on purpose must say so.
|
|
38
|
+
*
|
|
39
|
+
* `workflows/ship.js` cannot import (#69). It carries an inlined copy inside
|
|
40
|
+
* the `AC-PAYLOAD-TRANSPORT` markers, and `test/evidence-command-roundtrip.test.ts`
|
|
41
|
+
* runs both over one matrix so drift is red.
|
|
42
|
+
*/
|
|
43
|
+
import { shellSingleQuote } from "./phase2-decomposition";
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Where the payload arrives inside the `bun -e` program.
|
|
47
|
+
*
|
|
48
|
+
* `bun -e '<program>' a b` gives the program `process.argv[1] === "a"`.
|
|
49
|
+
*/
|
|
50
|
+
export const AC_PAYLOAD_ARGV_INDEX = 1;
|
|
51
|
+
|
|
52
|
+
/** One recorded change to an evidence command. */
|
|
53
|
+
export interface EvidenceRewrite {
|
|
54
|
+
/** The site that made the change, named so a reader can go and read it. */
|
|
55
|
+
by: string;
|
|
56
|
+
/** The command as it stood before this change. */
|
|
57
|
+
from: string;
|
|
58
|
+
/** The command as it stands after it. */
|
|
59
|
+
to: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The AC fields the setup step persists into workflow-state.json. */
|
|
63
|
+
export interface AcPayloadRecord {
|
|
64
|
+
id: unknown;
|
|
65
|
+
type: unknown;
|
|
66
|
+
statement: unknown;
|
|
67
|
+
threshold: unknown;
|
|
68
|
+
evidenceMethod: unknown;
|
|
69
|
+
specElement: unknown;
|
|
70
|
+
coversCriteria: unknown[];
|
|
71
|
+
contextFiles: unknown[];
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Project discovery's ACs onto the fields `writeACs` persists.
|
|
76
|
+
*
|
|
77
|
+
* Kept as a function rather than inlined at the two call sites because the
|
|
78
|
+
* two used to be two copies of the same object literal, and a field added to
|
|
79
|
+
* one of them would have been silently missing from the fix-acs fallback.
|
|
80
|
+
*/
|
|
81
|
+
export function acPayloadRecords(acs: unknown): AcPayloadRecord[] {
|
|
82
|
+
return (Array.isArray(acs) ? acs : []).map((ac: any) => ({
|
|
83
|
+
id: ac.id,
|
|
84
|
+
type: ac.type,
|
|
85
|
+
statement: ac.statement,
|
|
86
|
+
threshold: ac.threshold,
|
|
87
|
+
evidenceMethod: ac.evidenceMethod,
|
|
88
|
+
specElement: ac.specElement,
|
|
89
|
+
coversCriteria: ac.coversCriteria || [],
|
|
90
|
+
contextFiles: ac.contextFiles || [],
|
|
91
|
+
}));
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The payload exactly as it will be written to disk. */
|
|
95
|
+
export function acPayloadJson(acs: unknown): string {
|
|
96
|
+
return JSON.stringify(acPayloadRecords(acs));
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* The payload as a shell WORD, to sit after the closing quote of the
|
|
101
|
+
* `bun -e "…"` program.
|
|
102
|
+
*
|
|
103
|
+
* Single quotes are the one shell construct with no expansion inside them at
|
|
104
|
+
* all, so this is the only position in the command where agent-authored text
|
|
105
|
+
* is safe. `shellSingleQuote` closes, escapes and reopens on an apostrophe,
|
|
106
|
+
* which is the single character the construct cannot carry verbatim — and
|
|
107
|
+
* evidence commands are full of apostrophes, because that is how an awk or
|
|
108
|
+
* grep expression is quoted.
|
|
109
|
+
*
|
|
110
|
+
* ## Why an argument and not a file
|
|
111
|
+
*
|
|
112
|
+
* The obvious alternative — write the payload to `${WORK_DIR}/…json` and have
|
|
113
|
+
* the `bun -e` read it — was built first and does not work, for a reason
|
|
114
|
+
* worth recording rather than rediscovering. `initWorkflow` calls `beginRun`,
|
|
115
|
+
* whose whole job (#288) is to sweep the work directory into
|
|
116
|
+
* `previous-run-<id>/` so a dead run's artefacts cannot be read as this
|
|
117
|
+
* run's. A payload written before `initWorkflow` is archived by it, and the
|
|
118
|
+
* read that follows is an ENOENT; a payload written after it needs a third
|
|
119
|
+
* command in the agent's prompt. The argument has neither problem: one
|
|
120
|
+
* process, no new file in a swept directory, and no ordering to get wrong.
|
|
121
|
+
*/
|
|
122
|
+
export function acPayloadShellArgument(acs: unknown): string {
|
|
123
|
+
return shellSingleQuote(acPayloadJson(acs));
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The JavaScript expression that reads the payload back, for embedding in the
|
|
128
|
+
* `bun -e` program that calls `writeACs`.
|
|
129
|
+
*
|
|
130
|
+
* It contains no agent-authored text and no `$`, so it is safe inside the
|
|
131
|
+
* double-quoted shell string the setup step still is.
|
|
132
|
+
*/
|
|
133
|
+
export function acPayloadReadExpression(): string {
|
|
134
|
+
return `JSON.parse(process.argv[${AC_PAYLOAD_ARGV_INDEX}])`;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Change an evidence command, on the record.
|
|
139
|
+
*
|
|
140
|
+
* Returns true when the command actually changed. A no-op records nothing: a
|
|
141
|
+
* recorder that logged every call would leave `rewrites` non-empty on every
|
|
142
|
+
* AC and the field would stop meaning "this command was changed".
|
|
143
|
+
*
|
|
144
|
+
* `authoredCommand` is written once and never overwritten. A field holding
|
|
145
|
+
* "whatever it was one rewrite ago" cannot answer the question #614 asks,
|
|
146
|
+
* which is what the agent wrote.
|
|
147
|
+
*/
|
|
148
|
+
export function recordEvidenceRewrite(
|
|
149
|
+
evidenceMethod: { command?: string; authoredCommand?: string; rewrites?: EvidenceRewrite[] } | undefined | null,
|
|
150
|
+
by: string,
|
|
151
|
+
next: string,
|
|
152
|
+
): boolean {
|
|
153
|
+
if (!evidenceMethod || typeof evidenceMethod.command !== "string") return false;
|
|
154
|
+
const from = evidenceMethod.command;
|
|
155
|
+
if (from === next) return false;
|
|
156
|
+
if (evidenceMethod.authoredCommand === undefined) evidenceMethod.authoredCommand = from;
|
|
157
|
+
evidenceMethod.command = next;
|
|
158
|
+
evidenceMethod.rewrites = [...(evidenceMethod.rewrites || []), { by, from, to: next }];
|
|
159
|
+
return true;
|
|
160
|
+
}
|
|
@@ -57,6 +57,23 @@ export interface EvidencePrevalidationReading {
|
|
|
57
57
|
checkedAt: string;
|
|
58
58
|
/** Per-AC results. Empty — and only empty — when the verdict is UNMEASURED. */
|
|
59
59
|
acs: PrevalidationResult[];
|
|
60
|
+
/**
|
|
61
|
+
* The ids of the ACs classified `broken`, in the order they were measured.
|
|
62
|
+
*
|
|
63
|
+
* Derived from `acs`, never supplied — `EvidencePrevalidationSchema` refuses
|
|
64
|
+
* a reading whose `broken` disagrees with its own results, so this cannot
|
|
65
|
+
* drift into an independent claim.
|
|
66
|
+
*
|
|
67
|
+
* It exists because the gate's single refusal site,
|
|
68
|
+
* `prevalidationViolations` in gates/workflow.test.ts, names the ACs to fix
|
|
69
|
+
* out of exactly this key — and until #274 no writer produced it. Every
|
|
70
|
+
* genuine FAIL therefore refused with "no broken AC ids were recorded", which
|
|
71
|
+
* is true of the key and false of the reading: the per-AC results were right
|
|
72
|
+
* there under `acs`. Fail-closed, so nothing shipped that should not have,
|
|
73
|
+
* but a refusal the heal loop cannot act on costs a round and teaches
|
|
74
|
+
* nothing, which is part of how #261 cost two.
|
|
75
|
+
*/
|
|
76
|
+
broken: string[];
|
|
60
77
|
/** Why the reading is UNMEASURED. Null — and only null — when it is not. */
|
|
61
78
|
reason: string | null;
|
|
62
79
|
}
|
|
@@ -348,6 +365,7 @@ export async function measureEvidencePrevalidation(
|
|
|
348
365
|
verdict: "UNMEASURED",
|
|
349
366
|
checkedAt,
|
|
350
367
|
acs: [],
|
|
368
|
+
broken: [],
|
|
351
369
|
reason,
|
|
352
370
|
});
|
|
353
371
|
|
|
@@ -385,6 +403,10 @@ export async function measureEvidencePrevalidation(
|
|
|
385
403
|
verdict: broken.length > 0 ? "FAIL" : "PASS",
|
|
386
404
|
checkedAt,
|
|
387
405
|
acs: results,
|
|
406
|
+
// Mapped from the same filter the verdict is derived from, at the single
|
|
407
|
+
// site that derives it, so the verdict and the names it refuses under
|
|
408
|
+
// cannot disagree.
|
|
409
|
+
broken: broken.map((r) => r.id),
|
|
388
410
|
reason: null,
|
|
389
411
|
};
|
|
390
412
|
}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether `fallow` can be run without reaching the network (#581).
|
|
3
|
+
*
|
|
4
|
+
* `fallow` is an optional external tool and is NOT a declared dependency —
|
|
5
|
+
* not in `package.json`, not in `node_modules/.bin`, not on `PATH`, on this
|
|
6
|
+
* machine or on CI. So every bare `npx fallow` is a registry fetch.
|
|
7
|
+
*
|
|
8
|
+
* `lib/conformity.ts` learned that in its own words:
|
|
9
|
+
*
|
|
10
|
+
* > When it is absent, `npx fallow` does a registry fetch on every
|
|
11
|
+
* > invocation — four tests x one fetch each, each outliving bun's
|
|
12
|
+
* > per-test timeout. … Resolve it locally instead, with no network path.
|
|
13
|
+
*
|
|
14
|
+
* and then kept the fix to itself. `scripts/generate-code-map.ts` — the
|
|
15
|
+
* caller on the **scaffold** path, which runs once per consumer forever
|
|
16
|
+
* rather than four times in a suite — still spawned `npx fallow`
|
|
17
|
+
* unconditionally. So the fix landed in the cheap caller and not in the
|
|
18
|
+
* expensive one, and the cost of that is not a slow test: a consumer
|
|
19
|
+
* scaffolding behind a proxy, in an air-gapped CI, or on a bad connection
|
|
20
|
+
* gets a 30-second stall and then a silently degraded CODE-MAP, with nothing
|
|
21
|
+
* in the output saying a network call was attempted.
|
|
22
|
+
*
|
|
23
|
+
* It also made the suite non-deterministic. PR #580 — three state files, no
|
|
24
|
+
* code — went red on `SC-1665`, which asserts that `.fallow/cache.bin` was
|
|
25
|
+
* produced by both of two scaffold runs; when the fetch fails it is produced
|
|
26
|
+
* by neither. Reproduced with no repo change at all:
|
|
27
|
+
*
|
|
28
|
+
* npm_config_registry=http://127.0.0.1:1/ bun test test/scaffold-relative-root.test.ts
|
|
29
|
+
* error: .fallow/cache.bin is excluded but was not produced by both runs
|
|
30
|
+
*
|
|
31
|
+
* ## One binding
|
|
32
|
+
*
|
|
33
|
+
* This module exists rather than an export from `lib/conformity.ts` because
|
|
34
|
+
* conformity imports `bun:test` at module scope and so cannot be imported by
|
|
35
|
+
* a CLI. Same arrangement as `lib/git-dates.ts` (#508) and
|
|
36
|
+
* `lib/harness-identity.ts` (#380): one implementation, re-exported, because
|
|
37
|
+
* two answers to one question are behaviourally one and no test can tell
|
|
38
|
+
* them apart.
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
import { existsSync } from "fs";
|
|
42
|
+
import { join } from "path";
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Memoised PER ROOT.
|
|
46
|
+
*
|
|
47
|
+
* `runFallowCheck` is exported and consumer projects call it with their own
|
|
48
|
+
* root, so a single process can ask about several. A root-independent cache
|
|
49
|
+
* would answer for the wrong directory.
|
|
50
|
+
*/
|
|
51
|
+
const FALLOW_AVAILABLE = new Map<string, boolean>();
|
|
52
|
+
|
|
53
|
+
export function fallowAvailable(root: string): boolean {
|
|
54
|
+
const cached = FALLOW_AVAILABLE.get(root);
|
|
55
|
+
if (cached !== undefined) return cached;
|
|
56
|
+
const available = existsSync(join(root, "node_modules", ".bin", "fallow")) || Bun.which("fallow") !== null;
|
|
57
|
+
FALLOW_AVAILABLE.set(root, available);
|
|
58
|
+
return available;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Test seam: drop the memo so a case can change the answer. */
|
|
62
|
+
export function resetFallowAvailability(): void {
|
|
63
|
+
FALLOW_AVAILABLE.clear();
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Why a fallow-derived reading is missing, or null when it is not missing.
|
|
68
|
+
*
|
|
69
|
+
* Three outcomes, not two. `null` from the old `runFallow()` meant "not
|
|
70
|
+
* installed", "the spawn failed", "the output did not parse" and "it ran and
|
|
71
|
+
* found nothing" all at once, and a CODE-MAP written from it was
|
|
72
|
+
* byte-identical in every case — which is
|
|
73
|
+
* `.claude/rules/config-access.md`'s *Silent Default Substitution* with a
|
|
74
|
+
* document as the victim.
|
|
75
|
+
*/
|
|
76
|
+
export type FallowUnavailable =
|
|
77
|
+
| { kind: "not-installed"; reason: string }
|
|
78
|
+
| { kind: "run-failed"; reason: string };
|
|
79
|
+
|
|
80
|
+
export function fallowNotInstalled(): FallowUnavailable {
|
|
81
|
+
return {
|
|
82
|
+
kind: "not-installed",
|
|
83
|
+
reason:
|
|
84
|
+
"fallow is not installed (it is an optional tool, not a declared dependency) — " +
|
|
85
|
+
"no static analysis was run, and no registry fetch was attempted",
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* A tool's output, made safe to put in a document an agent reads.
|
|
91
|
+
*
|
|
92
|
+
* The `run-failed` reason quotes what fallow printed, and that string ends
|
|
93
|
+
* up inside CODE-MAP.md — which `.claude/rules/key-files.md` tells every
|
|
94
|
+
* agent to read to understand the codebase. So it is untrusted text on its
|
|
95
|
+
* way into a trusted document, and fallow's error text can quote the repo's
|
|
96
|
+
* own file names and contents.
|
|
97
|
+
*
|
|
98
|
+
* One line, an allowlist, and a cap. Not an escape routine: a denylist of
|
|
99
|
+
* markdown syntax is a detector narrower than what it detects, and the
|
|
100
|
+
* useful content of a tool error survives an allowlist intact.
|
|
101
|
+
*/
|
|
102
|
+
export function safeToolDetail(raw: string): string {
|
|
103
|
+
const firstLine = raw.split("\n")[0] ?? "";
|
|
104
|
+
// A RUN of disallowed characters collapses to one `?`, rather than one
|
|
105
|
+
// `?` each. Both are safe; the difference is whether a detail that was
|
|
106
|
+
// entirely unprintable comes back as `????????` — which carries no
|
|
107
|
+
// information and is indistinguishable from a tool that said something.
|
|
108
|
+
const cleaned = firstLine.replace(/[^A-Za-z0-9 .,:;()/'"=+-]+/g, "?").slice(0, 120).trim();
|
|
109
|
+
return /^[?\s]*$/.test(cleaned) ? "(no printable detail)" : cleaned;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export function fallowRunFailed(detail: string): FallowUnavailable {
|
|
113
|
+
return {
|
|
114
|
+
kind: "run-failed",
|
|
115
|
+
reason: `fallow is installed but the run did not produce a reading: ${safeToolDetail(detail)}`,
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* The line a generated document carries in place of a section it could not
|
|
121
|
+
* produce.
|
|
122
|
+
*
|
|
123
|
+
* UNMEASURED by name. An omitted section and a section reporting nothing
|
|
124
|
+
* wrong are the same absence to a reader, and the reader of a CODE-MAP is an
|
|
125
|
+
* agent deciding whether this project has dead code.
|
|
126
|
+
*/
|
|
127
|
+
export function fallowUnmeasuredNotice(u: FallowUnavailable): string {
|
|
128
|
+
return `## Code Health (fallow)\n\n**UNMEASURED** — ${u.reason}.`;
|
|
129
|
+
}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which recorded refusals are still true at the end of the run (#532).
|
|
3
|
+
*
|
|
4
|
+
* The ship gate RE-RUNS the verify checks. `runGateTests` spawns
|
|
5
|
+
* `bun test gates/ --test-name-pattern "schema|scope|verify|ship|B1|B2"` for
|
|
6
|
+
* the ship gate, so every `verify checks > …` name is measured a second
|
|
7
|
+
* time, later, against a tree the heal rounds have since changed.
|
|
8
|
+
*
|
|
9
|
+
* Measured on run `wf_e230fddc-a71`:
|
|
10
|
+
*
|
|
11
|
+
* | Check | `gates.verify.failures` | `gates.ship.failures` |
|
|
12
|
+
* |---|---|---|
|
|
13
|
+
* | `verify checks > tests-pass` | FAIL | FAIL |
|
|
14
|
+
* | `verify checks > evidence-prevalidation` | **FAIL** | **absent** |
|
|
15
|
+
* | `verify checks > tsc-pass` | FAIL | FAIL |
|
|
16
|
+
*
|
|
17
|
+
* `state.evidencePrevalidation` in that same file reads
|
|
18
|
+
* `{"verdict":"PASS", acs: [… all "ok" …]}`. The refusal was round one, a
|
|
19
|
+
* heal fixed it, the ship gate re-ran it and it passed — and the terminal
|
|
20
|
+
* report listed it anyway, because the report is the UNION of every gate's
|
|
21
|
+
* list rather than the latest reading of each check.
|
|
22
|
+
*
|
|
23
|
+
* The run returned 19 refusals. Several were already resolved, so the real
|
|
24
|
+
* count was smaller, and the one that actually blocked the run — a
|
|
25
|
+
* `SECURITY_REVIEW_STALE` — was buried among them. A report with false
|
|
26
|
+
* entries in it is a report nobody reads twice.
|
|
27
|
+
*
|
|
28
|
+
* ## Absence is not a pass
|
|
29
|
+
*
|
|
30
|
+
* The whole thing turns on one distinction, and getting it wrong is worse
|
|
31
|
+
* than the bug it fixes: a check missing from a later gate's FAILURES means
|
|
32
|
+
* either *it passed there* or *that gate never ran it*. Those are opposite
|
|
33
|
+
* facts and a failure list cannot tell them apart. Retiring on absence
|
|
34
|
+
* would silently drop every refusal a later gate's narrower pattern skipped.
|
|
35
|
+
*
|
|
36
|
+
* So retirement requires a positive witness — `checksRun`, the names the
|
|
37
|
+
* later gate reported a verdict for, recorded by `gates/orchestrator.ts`
|
|
38
|
+
* from the same `results` array the failures come from. A gate with no
|
|
39
|
+
* `checksRun` retires NOTHING. `null` and `[]` are different answers here
|
|
40
|
+
* and only one of them is a measurement
|
|
41
|
+
* (.claude/rules/config-access.md, Silent Default Substitution).
|
|
42
|
+
*
|
|
43
|
+
* ## Why this is duplicated into ship.js
|
|
44
|
+
*
|
|
45
|
+
* `workflows/ship.js` runs in a sandbox with no module loading (#69), so it
|
|
46
|
+
* cannot import this. It carries an inlined copy inside
|
|
47
|
+
* `REFUSAL-CURRENCY` markers, and `test/gate-refusal-currency.test.ts`
|
|
48
|
+
* extracts that copy, executes it, and runs both over one input matrix —
|
|
49
|
+
* the same technique `test/suite-measurement-parity.test.ts` uses for
|
|
50
|
+
* `suiteCurrency`, and for the same reason: two copies of a rule is a
|
|
51
|
+
* defect waiting for one of them to drift, and the drift is silent.
|
|
52
|
+
*/
|
|
53
|
+
|
|
54
|
+
/** What a gate run reported back: the names it measured and the ones it failed. */
|
|
55
|
+
export interface GateReport {
|
|
56
|
+
checksRun?: unknown;
|
|
57
|
+
failedChecks?: unknown;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** One recorded refusal. `check` is absent for refusals no gate produced. */
|
|
61
|
+
export interface RefusalEntry {
|
|
62
|
+
check?: unknown;
|
|
63
|
+
[k: string]: unknown;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The checks a gate ran and did NOT fail — the only thing that can retire an
|
|
68
|
+
* earlier refusal.
|
|
69
|
+
*
|
|
70
|
+
* `null` when the gate reported no `checksRun`, and that is the
|
|
71
|
+
* load-bearing return rather than an empty array: a caller has to be able
|
|
72
|
+
* to tell "this gate said nothing about what it ran" from "this gate ran
|
|
73
|
+
* nothing".
|
|
74
|
+
*/
|
|
75
|
+
export function resolvedCheckNames(report: GateReport | null | undefined): string[] | null {
|
|
76
|
+
if (!report || !Array.isArray(report.checksRun)) return null;
|
|
77
|
+
const failed = new Set(
|
|
78
|
+
(Array.isArray(report.failedChecks) ? report.failedChecks : []).filter(
|
|
79
|
+
(c: unknown): c is string => typeof c === "string" && c !== "",
|
|
80
|
+
),
|
|
81
|
+
);
|
|
82
|
+
return report.checksRun.filter(
|
|
83
|
+
(c: unknown): c is string => typeof c === "string" && c !== "" && !failed.has(c),
|
|
84
|
+
);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Remove, IN PLACE, every earlier refusal about a check this gate re-ran and
|
|
89
|
+
* did not reproduce. Returns the entries it removed.
|
|
90
|
+
*
|
|
91
|
+
* In place because the ledger is one array the whole run appends to, and
|
|
92
|
+
* returning a copy would leave the original to be reported by whichever
|
|
93
|
+
* reader got there first. The removed entries are returned rather than
|
|
94
|
+
* discarded: a refusal that was retired is a thing an operator may want to
|
|
95
|
+
* see, and silently shortening a list is how a report stops being checkable.
|
|
96
|
+
*/
|
|
97
|
+
export function retireSupersededRefusals(
|
|
98
|
+
entries: RefusalEntry[],
|
|
99
|
+
report: GateReport | null | undefined,
|
|
100
|
+
): RefusalEntry[] {
|
|
101
|
+
const resolved = resolvedCheckNames(report);
|
|
102
|
+
if (resolved === null || resolved.length === 0) return [];
|
|
103
|
+
const names = new Set(resolved);
|
|
104
|
+
const dropped: RefusalEntry[] = [];
|
|
105
|
+
for (let i = entries.length - 1; i >= 0; i--) {
|
|
106
|
+
const check = entries[i]?.check;
|
|
107
|
+
if (typeof check === "string" && check !== "" && names.has(check)) {
|
|
108
|
+
dropped.unshift(entries.splice(i, 1)[0]);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return dropped;
|
|
112
|
+
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The gate run's three nested time budgets, and the order they must be in (#550).
|
|
3
|
+
*
|
|
4
|
+
* A gate check is three processes deep, and each layer can kill the one
|
|
5
|
+
* inside it. Before this file the three numbers were written in three places
|
|
6
|
+
* by three issues and **two of the three orderings were backwards**:
|
|
7
|
+
*
|
|
8
|
+
* | Layer | Was | Where |
|
|
9
|
+
* |---|---|---|
|
|
10
|
+
* | the compiler `tsc-pass` spawns | 240000 | `gates/workflow.test.ts` |
|
|
11
|
+
* | the `test()` around that spawn | 5000 (bun's default) | nowhere — undeclared |
|
|
12
|
+
* | the whole `bun test gates/` run | 120000 | `gates/gate-executor.ts` |
|
|
13
|
+
*
|
|
14
|
+
* So the compiler was allowed four minutes by a call killed after five
|
|
15
|
+
* seconds, inside a run killed after two. `tsc-pass` **could not pass on any
|
|
16
|
+
* project whose typecheck takes longer than five seconds**, which is every
|
|
17
|
+
* project large enough to have a gate run. Observed live: the check printed
|
|
18
|
+
* `Type check PASS: bunx tsc --noEmit` to its own stdout and recorded FAIL,
|
|
19
|
+
* and the timeout line that said why was attributed to the NEXT check by the
|
|
20
|
+
* parser (the other half of #550).
|
|
21
|
+
*
|
|
22
|
+
* Nothing could say so, because a timeout and a genuine failure are the same
|
|
23
|
+
* red, and the 240000 beside the spawn reads as deliberate.
|
|
24
|
+
*
|
|
25
|
+
* **The rule is one line: each layer must strictly outlive the one inside
|
|
26
|
+
* it.** Equal is not enough — a spawn killed at the same instant as its test
|
|
27
|
+
* is a race, and which of the two messages you get is not decided by this
|
|
28
|
+
* repo.
|
|
29
|
+
*
|
|
30
|
+
* Declared here, once, so the ordering is a property of four exported
|
|
31
|
+
* constants rather than of four numbers nobody reads together. The numbers
|
|
32
|
+
* themselves are judgement, and the judgement is written down:
|
|
33
|
+
*
|
|
34
|
+
* - `EXEC_TIMEOUT_MS` — the `git`/shell helpers. Unchanged at 30s; these are
|
|
35
|
+
* local repository reads and one that takes longer is hung, not slow.
|
|
36
|
+
* - `TYPECHECK_TIMEOUT_MS` — 90s, LOWERED from 240s. 240 was never reachable,
|
|
37
|
+
* and a single check is not entitled to twice the whole gate's budget.
|
|
38
|
+
* - `GATE_TEST_TIMEOUT_MS` — 120s, the per-test default. Declared at file
|
|
39
|
+
* level with `setDefaultTimeout` and not as a per-test argument, because
|
|
40
|
+
* `}, 120000);` on `tsc-pass` alone covers exactly one check and the next
|
|
41
|
+
* spawning check added inherits nothing. A rule naming one test is a rule
|
|
42
|
+
* the next one evades.
|
|
43
|
+
* - `GATE_SUITE_TIMEOUT_MS` — 180s, RAISED from 120s, so the outer kill is
|
|
44
|
+
* above the per-test budget rather than below it.
|
|
45
|
+
*/
|
|
46
|
+
|
|
47
|
+
/** `exec`, `execArgv`, `execArgvOf` — local git and shell reads. */
|
|
48
|
+
export const EXEC_TIMEOUT_MS = 30_000;
|
|
49
|
+
|
|
50
|
+
/** `bunx tsc --noEmit`, the slowest single subprocess a check starts. */
|
|
51
|
+
export const TYPECHECK_TIMEOUT_MS = 90_000;
|
|
52
|
+
|
|
53
|
+
/** The per-test default for `gates/workflow.test.ts`. */
|
|
54
|
+
export const GATE_TEST_TIMEOUT_MS = 120_000;
|
|
55
|
+
|
|
56
|
+
/** The whole `bun test gates/` run, spawned by `runGateTests`. */
|
|
57
|
+
export const GATE_SUITE_TIMEOUT_MS = 180_000;
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The ordering, as a function so it can be driven over values that are not
|
|
61
|
+
* these ones — otherwise the check compares the constants against themselves
|
|
62
|
+
* and no mutation of them can be observed.
|
|
63
|
+
*/
|
|
64
|
+
export function gateTimeoutOrderingViolations(t: {
|
|
65
|
+
exec: number;
|
|
66
|
+
typecheck: number;
|
|
67
|
+
test: number;
|
|
68
|
+
suite: number;
|
|
69
|
+
}): string[] {
|
|
70
|
+
const layers: Array<[string, number, string, number]> = [
|
|
71
|
+
["the exec helpers", t.exec, "the typecheck spawn", t.typecheck],
|
|
72
|
+
["the typecheck spawn", t.typecheck, "the test around it", t.test],
|
|
73
|
+
["the test", t.test, "the gate suite run", t.suite],
|
|
74
|
+
];
|
|
75
|
+
return layers
|
|
76
|
+
.filter(([, inner, , outer]) => !(inner < outer))
|
|
77
|
+
.map(
|
|
78
|
+
([innerName, inner, outerName, outer]) =>
|
|
79
|
+
`${innerName} is allowed ${inner}ms inside ${outerName}'s ${outer}ms — the inner process ` +
|
|
80
|
+
`outlives the thing that started it, so it is killed before it can report (#550)`,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
@@ -65,7 +65,10 @@ export function generateAgentBriefs(scan: ProjectScan): Record<string, string> {
|
|
|
65
65
|
const harness = scan.harnessConfig;
|
|
66
66
|
const devUi = harness?.dev?.uiBase || null;
|
|
67
67
|
const devApi = harness?.dev?.apiBase || null;
|
|
68
|
-
|
|
68
|
+
// #488 — `scan.testCmd` already IS the decision: `testCommandDecision`
|
|
69
|
+
// puts `dev.testCmd` on its first rung, so re-asking here was a second
|
|
70
|
+
// ladder that could disagree with the first and never be noticed.
|
|
71
|
+
const testCmd = scan.testCmd || "bun test";
|
|
69
72
|
const typeCheck = harness?.dev?.typeCheck || "bunx tsc --noEmit";
|
|
70
73
|
const pages = harness?.pages || {};
|
|
71
74
|
const pagesTable = Object.keys(pages).length > 0
|