rungate 0.5.0 → 0.7.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/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- 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 +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,432 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The other half of #523: is the list of "fields that must be stable" still true?
|
|
3
|
+
*
|
|
4
|
+
* `lib/discovery-stability.ts` compares k recorded runs over
|
|
5
|
+
* `STABLE_DISCOVERY_FIELDS`. That list was not written by taste — it was
|
|
6
|
+
* derived from one criterion, stated on #523 before any code:
|
|
7
|
+
*
|
|
8
|
+
* **A discovery field is required to be stable exactly when something
|
|
9
|
+
* downstream BRANCHES on it.**
|
|
10
|
+
*
|
|
11
|
+
* The same comment named the consequence and did not build it:
|
|
12
|
+
*
|
|
13
|
+
* *"The list is derivable, so it can be a test rather than a document.
|
|
14
|
+
* Something walking the branch points in `workflows/ship.js` and comparing
|
|
15
|
+
* them to the declared stable set would catch a new branch on a field
|
|
16
|
+
* nobody declared stable — which is the failure mode a hand-maintained
|
|
17
|
+
* list has."*
|
|
18
|
+
*
|
|
19
|
+
* This module is that walk. Without it the comparator has a hole that is
|
|
20
|
+
* invisible from inside itself: add `if (discovery.riskTier === 'HIGH')` to
|
|
21
|
+
* the workflow tomorrow and every test in `test/discovery-stability.test.ts`
|
|
22
|
+
* stays green, because every one of them reads the declared list, the schema,
|
|
23
|
+
* or synthetic states — never the workflow. The measurement would go on
|
|
24
|
+
* reporting "8 fields observed, 0 varied" while the field that actually
|
|
25
|
+
* decides the run was not among them. A list that can only be checked against
|
|
26
|
+
* itself is a document.
|
|
27
|
+
*
|
|
28
|
+
* ## The two readings, and what varies between them
|
|
29
|
+
*
|
|
30
|
+
* Reading A is the DECLARATION: `STABLE_DISCOVERY_FIELDS` plus `NOT_ASSERTED`,
|
|
31
|
+
* hand-written in `lib/discovery-stability.ts`.
|
|
32
|
+
*
|
|
33
|
+
* Reading B is the CODE: the conditions in `workflows/ship.js`, parsed, and
|
|
34
|
+
* the discovery properties read inside them.
|
|
35
|
+
*
|
|
36
|
+
* They have different producers and different inputs, which is the whole
|
|
37
|
+
* point — a determinism check that builds the same thing twice with the same
|
|
38
|
+
* code is 0 red against the mutation it exists to catch. Editing either side
|
|
39
|
+
* alone changes the result here: a new branch grows B, deleting an entry
|
|
40
|
+
* shrinks A, and `auditBranchCoverage` reports the disagreement either way.
|
|
41
|
+
*
|
|
42
|
+
* What this asserts is therefore (c): **a refusal when the two readings
|
|
43
|
+
* disagree.** Not a shape, not an order. No model is called and nothing here
|
|
44
|
+
* can red on a model-day.
|
|
45
|
+
*
|
|
46
|
+
* ## Why an empty reading is refused rather than counted as agreement
|
|
47
|
+
*
|
|
48
|
+
* A census that finds nothing agrees with every possible list. If the
|
|
49
|
+
* extractor breaks — the workflow stops parsing, the discovery object is
|
|
50
|
+
* renamed, acorn changes a node name — the honest result is UNMEASURED, not
|
|
51
|
+
* "no undeclared fields". Both the empty-source and the zero-branch-point
|
|
52
|
+
* cases leave through `refuse()`, which is guarded by the single exported
|
|
53
|
+
* `BRANCH_CENSUS_REFUSE` constant so a test can zero it and show each negative
|
|
54
|
+
* case passing only because the refusal fired
|
|
55
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
56
|
+
*/
|
|
57
|
+
|
|
58
|
+
import { parse } from "acorn";
|
|
59
|
+
|
|
60
|
+
import { NOT_ASSERTED, STABLE_DISCOVERY_FIELDS, type StableField } from "./discovery-stability";
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The one switch every refusal goes through. Declared on a single line and
|
|
64
|
+
* assigned exactly once, so a mutant copy with `= 0` neutralises ALL refusals
|
|
65
|
+
* and no branch can quietly bypass the mutation by raising directly.
|
|
66
|
+
*/
|
|
67
|
+
export const BRANCH_CENSUS_REFUSE = 1;
|
|
68
|
+
|
|
69
|
+
/** Raised by every refusal in this module. */
|
|
70
|
+
export class BranchCensusRefusal extends Error {
|
|
71
|
+
constructor(reason: string) {
|
|
72
|
+
super(`branch census REFUSED: ${reason}`);
|
|
73
|
+
this.name = "BranchCensusRefusal";
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function refuse(reason: string): never | void {
|
|
78
|
+
if (BRANCH_CENSUS_REFUSE) throw new BranchCensusRefusal(reason);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The identifiers the workflow holds DISCOVERY's model output in.
|
|
83
|
+
*
|
|
84
|
+
* `discovery` is the object `workflows/ship.js` parses the discovery agent's
|
|
85
|
+
* JSON into; `disc` is the short alias the same file uses in a few helpers.
|
|
86
|
+
* A rename that misses this list drops the census to zero branch points,
|
|
87
|
+
* which is refused rather than reported as agreement.
|
|
88
|
+
*/
|
|
89
|
+
export const DISCOVERY_ROOTS = ["discovery", "disc"] as const;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Where a read of a discovery field decides what the run does.
|
|
93
|
+
*
|
|
94
|
+
* Keyed by acorn node type, valued by the property holding the deciding
|
|
95
|
+
* expression. A read anywhere else in the program — interpolated into a
|
|
96
|
+
* prompt, logged, copied into the state file — is not a branch and is not
|
|
97
|
+
* the subject of #523's criterion.
|
|
98
|
+
*/
|
|
99
|
+
export const CONDITION_POSITIONS: Record<string, readonly string[]> = {
|
|
100
|
+
IfStatement: ["test"],
|
|
101
|
+
ConditionalExpression: ["test"],
|
|
102
|
+
SwitchStatement: ["discriminant"],
|
|
103
|
+
SwitchCase: ["test"],
|
|
104
|
+
WhileStatement: ["test"],
|
|
105
|
+
DoWhileStatement: ["test"],
|
|
106
|
+
ForStatement: ["test"],
|
|
107
|
+
/**
|
|
108
|
+
* `a && b` / `a || c` / `a ?? b`: the LEFT operand decides whether the right
|
|
109
|
+
* one is evaluated, so it is a branch wherever it appears. The right operand
|
|
110
|
+
* is not — it is the consequent.
|
|
111
|
+
*/
|
|
112
|
+
LogicalExpression: ["left"],
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
export interface BranchPoint {
|
|
116
|
+
/** The discovery property the condition reads, e.g. `ceremonyTier`. */
|
|
117
|
+
field: string;
|
|
118
|
+
/** The root identifier it was read off — one of `DISCOVERY_ROOTS`. */
|
|
119
|
+
root: string;
|
|
120
|
+
/** The acorn construct that makes it a branch, e.g. `IfStatement.test`. */
|
|
121
|
+
construct: string;
|
|
122
|
+
/** 1-based line in the source, so a finding can be opened. */
|
|
123
|
+
line: number;
|
|
124
|
+
/** The condition text, collapsed and clipped. Evidence, not decoration. */
|
|
125
|
+
snippet: string;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
type AstNode = { type: string; start: number; end: number; [k: string]: unknown };
|
|
129
|
+
|
|
130
|
+
function isNode(value: unknown): value is AstNode {
|
|
131
|
+
return (
|
|
132
|
+
typeof value === "object" &&
|
|
133
|
+
value !== null &&
|
|
134
|
+
typeof (value as AstNode).type === "string" &&
|
|
135
|
+
typeof (value as AstNode).start === "number" &&
|
|
136
|
+
typeof (value as AstNode).end === "number"
|
|
137
|
+
);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* acorn options, matching `lib/reachability.ts`: `workflows/ship.js` is a
|
|
142
|
+
* module body the Workflow runtime wraps in an async function before running,
|
|
143
|
+
* so it legitimately contains top-level `return` and `await`. Both options
|
|
144
|
+
* only widen what PARSES.
|
|
145
|
+
*/
|
|
146
|
+
const PARSE_OPTIONS = {
|
|
147
|
+
ecmaVersion: "latest",
|
|
148
|
+
sourceType: "module",
|
|
149
|
+
allowReturnOutsideFunction: true,
|
|
150
|
+
allowAwaitOutsideFunction: true,
|
|
151
|
+
allowHashBang: true,
|
|
152
|
+
} as const;
|
|
153
|
+
|
|
154
|
+
function children(node: AstNode): AstNode[] {
|
|
155
|
+
const out: AstNode[] = [];
|
|
156
|
+
for (const value of Object.values(node)) {
|
|
157
|
+
if (Array.isArray(value)) {
|
|
158
|
+
for (const child of value) if (isNode(child)) out.push(child);
|
|
159
|
+
} else if (isNode(value)) {
|
|
160
|
+
out.push(value);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
return out;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function walk(node: AstNode, visit: (n: AstNode) => void): void {
|
|
167
|
+
visit(node);
|
|
168
|
+
for (const child of children(node)) walk(child, visit);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* The discovery property a member expression reads, or null.
|
|
173
|
+
*
|
|
174
|
+
* Only the FIRST property off the root is returned: `discovery.sizing` and
|
|
175
|
+
* `discovery.sizing.predicted` both census as `sizing`, because the criterion
|
|
176
|
+
* is about which model-authored field decides the run, and the declaration
|
|
177
|
+
* side maps its own finer state paths onto these names through `readAs`.
|
|
178
|
+
* Computed access (`discovery[k]`) yields no name and is reported separately.
|
|
179
|
+
*/
|
|
180
|
+
function rootedRead(node: AstNode): { root: string; field: string } | null {
|
|
181
|
+
if (node.type !== "MemberExpression") return null;
|
|
182
|
+
const object = node.object as AstNode | undefined;
|
|
183
|
+
const property = node.property as AstNode | undefined;
|
|
184
|
+
if (!isNode(object) || !isNode(property)) return null;
|
|
185
|
+
if (object.type !== "Identifier") return null;
|
|
186
|
+
const root = String((object as unknown as { name: string }).name);
|
|
187
|
+
if (!(DISCOVERY_ROOTS as readonly string[]).includes(root)) return null;
|
|
188
|
+
if (node.computed === true) return null;
|
|
189
|
+
if (property.type !== "Identifier") return null;
|
|
190
|
+
return { root, field: String((property as unknown as { name: string }).name) };
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function lineOf(source: string, offset: number): number {
|
|
194
|
+
let line = 1;
|
|
195
|
+
for (let i = 0; i < offset && i < source.length; i++) if (source[i] === "\n") line++;
|
|
196
|
+
return line;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function clip(text: string, max = 110): string {
|
|
200
|
+
const flat = text.replace(/\s+/g, " ").trim();
|
|
201
|
+
return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Every discovery property read inside a condition, one entry per read.
|
|
206
|
+
*
|
|
207
|
+
* REFUSES when the source does not parse, and when the walk finds no branch
|
|
208
|
+
* point at all — see the module header for why an empty census is not
|
|
209
|
+
* agreement.
|
|
210
|
+
*/
|
|
211
|
+
export function extractDiscoveryBranchPoints(source: string): BranchPoint[] {
|
|
212
|
+
let program: AstNode;
|
|
213
|
+
try {
|
|
214
|
+
program = parse(source, PARSE_OPTIONS) as unknown as AstNode;
|
|
215
|
+
} catch (err) {
|
|
216
|
+
refuse(`the source does not parse as JavaScript: ${(err as Error).message}`);
|
|
217
|
+
return [];
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
const found: BranchPoint[] = [];
|
|
221
|
+
walk(program, node => {
|
|
222
|
+
const positions = CONDITION_POSITIONS[node.type];
|
|
223
|
+
if (!positions) return;
|
|
224
|
+
for (const position of positions) {
|
|
225
|
+
const condition = node[position];
|
|
226
|
+
if (!isNode(condition)) continue;
|
|
227
|
+
walk(condition, inner => {
|
|
228
|
+
const read = rootedRead(inner);
|
|
229
|
+
if (!read) return;
|
|
230
|
+
found.push({
|
|
231
|
+
field: read.field,
|
|
232
|
+
root: read.root,
|
|
233
|
+
construct: `${node.type}.${position}`,
|
|
234
|
+
line: lineOf(source, inner.start),
|
|
235
|
+
snippet: clip(source.slice(condition.start, condition.end)),
|
|
236
|
+
});
|
|
237
|
+
});
|
|
238
|
+
}
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
if (found.length === 0) {
|
|
242
|
+
refuse(
|
|
243
|
+
`no condition in this source reads any of [${DISCOVERY_ROOTS.join(", ")}]. ` +
|
|
244
|
+
`A census that finds nothing agrees with every possible list, so this is UNMEASURED, ` +
|
|
245
|
+
`not "no undeclared fields".`,
|
|
246
|
+
);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
return found;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/* ────────────────────────── the declaration side ────────────────────────── */
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* A declaration entry that names which workflow-source property it covers.
|
|
256
|
+
*
|
|
257
|
+
* `STABLE_DISCOVERY_FIELDS` speaks in STATE paths (`sizing.ceremonyTier`) and
|
|
258
|
+
* the workflow speaks in DISCOVERY-object properties (`discovery.ceremonyTier`)
|
|
259
|
+
* — `workflows/ship.js` flattens one into the other when it writes the state
|
|
260
|
+
* file. `readAs` is that mapping, declared rather than guessed: a path with no
|
|
261
|
+
* `readAs` covers nothing, so adding an entry does not silently excuse a
|
|
262
|
+
* branch.
|
|
263
|
+
*/
|
|
264
|
+
export interface SourceMapped {
|
|
265
|
+
path: string;
|
|
266
|
+
readAs?: readonly string[];
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** The discovery properties a declaration list claims to cover. */
|
|
270
|
+
export function coveredFields(entries: readonly SourceMapped[]): Set<string> {
|
|
271
|
+
const out = new Set<string>();
|
|
272
|
+
for (const entry of entries) for (const name of entry.readAs ?? []) out.add(name);
|
|
273
|
+
return out;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Branched on, and NOT MEASURABLE — the third register, and the one this
|
|
278
|
+
* census produced.
|
|
279
|
+
*
|
|
280
|
+
* `filesToModify` and `scopeOut` both meet #523's criterion outright: the run
|
|
281
|
+
* takes a different path on each of them. Neither is in
|
|
282
|
+
* `WorkflowStateSchema`. They exist inside a run and are gone when it ends, so
|
|
283
|
+
* no comparison over recorded run states can read them in either direction —
|
|
284
|
+
* a declared path for one would resolve to `undefined` in every run, which is
|
|
285
|
+
* perfectly stable and completely uninformative.
|
|
286
|
+
*
|
|
287
|
+
* They are therefore recorded as **UNMEASURED, not as excluded**. The
|
|
288
|
+
* distinction is the point: `NOT_ASSERTED` means "we looked and decided not
|
|
289
|
+
* to", this means "we could not look". A reading nobody could take is not a
|
|
290
|
+
* reading that passed.
|
|
291
|
+
*
|
|
292
|
+
* The excuse is itself checked. `test/discovery-branch-coverage.test.ts`
|
|
293
|
+
* asserts every entry here is genuinely ABSENT from the real
|
|
294
|
+
* `WorkflowStateSchema` — so the day somebody persists `filesToModify`, this
|
|
295
|
+
* entry becomes false and reddens, forcing the field into
|
|
296
|
+
* `STABLE_DISCOVERY_FIELDS` where it now belongs. An excuse that cannot go
|
|
297
|
+
* stale is a comment.
|
|
298
|
+
*/
|
|
299
|
+
export const BRANCHED_BUT_UNPERSISTED: { field: string; reason: string }[] = [
|
|
300
|
+
{
|
|
301
|
+
field: "filesToModify",
|
|
302
|
+
reason:
|
|
303
|
+
"`workflows/ship.js:3841` branches the M-size decomposition on `(discovery.filesToModify || []).length >= 3`, and `:2964` feeds its contents to `scopeContradiction`, which REFUSES the run. Both are decisions, so the criterion is met — but `WorkflowStateSchema` has no `filesToModify`, so a k-run series cannot observe it. Measuring this needs the field persisted first.",
|
|
304
|
+
},
|
|
305
|
+
{
|
|
306
|
+
field: "scopeOut",
|
|
307
|
+
reason:
|
|
308
|
+
"`workflows/ship.js:2961` passes it to `deniedFiles`, whose result decides an early return and then a refusal; `:3837` recomputes the denied list that bounds the sub-issues. Same position as `filesToModify` — a real branch on model-authored content, absent from `WorkflowStateSchema`, therefore unobservable rather than stable.",
|
|
309
|
+
},
|
|
310
|
+
];
|
|
311
|
+
|
|
312
|
+
export interface CoverageFinding {
|
|
313
|
+
field: string;
|
|
314
|
+
points: BranchPoint[];
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
export interface CoverageReport {
|
|
318
|
+
/** Every branch point the walk found, in source order. */
|
|
319
|
+
points: BranchPoint[];
|
|
320
|
+
/** Distinct discovery properties branched on. */
|
|
321
|
+
branchedFields: string[];
|
|
322
|
+
/**
|
|
323
|
+
* Branched on, and classified by neither list. THE FINDING: the run takes a
|
|
324
|
+
* different path on this field and nobody has said whether it is allowed to
|
|
325
|
+
* vary.
|
|
326
|
+
*/
|
|
327
|
+
undeclared: CoverageFinding[];
|
|
328
|
+
/**
|
|
329
|
+
* Declared stable with a `branchedOnBy` justification, but no condition in
|
|
330
|
+
* the workflow reads it any more. The justification has gone stale — the
|
|
331
|
+
* other direction of the same rot.
|
|
332
|
+
*/
|
|
333
|
+
staleJustification: string[];
|
|
334
|
+
/** Branched on and deliberately excluded, with the reason already on record. */
|
|
335
|
+
excluded: string[];
|
|
336
|
+
/**
|
|
337
|
+
* Branched on, meets the criterion, and the state file does not carry it —
|
|
338
|
+
* so no series can measure it. UNMEASURED, never counted as stable.
|
|
339
|
+
*/
|
|
340
|
+
unmeasurable: string[];
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Compare the two readings and report every disagreement, in both directions.
|
|
345
|
+
*
|
|
346
|
+
* REFUSES when the declaration covers nothing: a `readAs`-less list excuses
|
|
347
|
+
* no branch and would report every field in the workflow as a finding, which
|
|
348
|
+
* reads as a catastrophic result rather than as a broken instrument.
|
|
349
|
+
*/
|
|
350
|
+
export function auditBranchCoverage(
|
|
351
|
+
points: BranchPoint[],
|
|
352
|
+
stable: readonly SourceMapped[] = STABLE_DISCOVERY_FIELDS as readonly StableField[] as readonly SourceMapped[],
|
|
353
|
+
notAsserted: readonly SourceMapped[] = NOT_ASSERTED as readonly SourceMapped[],
|
|
354
|
+
unpersisted: readonly { field: string }[] = BRANCHED_BUT_UNPERSISTED,
|
|
355
|
+
): CoverageReport {
|
|
356
|
+
const stableFields = coveredFields(stable);
|
|
357
|
+
const excludedFields = coveredFields(notAsserted);
|
|
358
|
+
const unpersistedFields = new Set(unpersisted.map(u => u.field));
|
|
359
|
+
if (stableFields.size === 0 && excludedFields.size === 0) {
|
|
360
|
+
refuse(
|
|
361
|
+
"neither declaration list maps to a single workflow property, so every branch would " +
|
|
362
|
+
"report as undeclared. That is a broken mapping, not a finding.",
|
|
363
|
+
);
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
const byField = new Map<string, BranchPoint[]>();
|
|
367
|
+
for (const point of points) {
|
|
368
|
+
const list = byField.get(point.field);
|
|
369
|
+
if (list) list.push(point);
|
|
370
|
+
else byField.set(point.field, [point]);
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
const branchedFields = [...byField.keys()].sort();
|
|
374
|
+
const undeclared: CoverageFinding[] = [];
|
|
375
|
+
const excluded: string[] = [];
|
|
376
|
+
const unmeasurable: string[] = [];
|
|
377
|
+
for (const field of branchedFields) {
|
|
378
|
+
if (stableFields.has(field)) continue;
|
|
379
|
+
if (excludedFields.has(field)) {
|
|
380
|
+
excluded.push(field);
|
|
381
|
+
continue;
|
|
382
|
+
}
|
|
383
|
+
if (unpersistedFields.has(field)) {
|
|
384
|
+
unmeasurable.push(field);
|
|
385
|
+
continue;
|
|
386
|
+
}
|
|
387
|
+
undeclared.push({ field, points: byField.get(field) ?? [] });
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
const staleJustification = [...stableFields].filter(f => !byField.has(f)).sort();
|
|
391
|
+
|
|
392
|
+
return { points, branchedFields, undeclared, staleJustification, excluded, unmeasurable };
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/** The finding, as text. Never a verdict a gate silently consumes. */
|
|
396
|
+
export function formatCoverageReport(report: CoverageReport): string {
|
|
397
|
+
const lines = [
|
|
398
|
+
`Discovery branch-point census (#523)`,
|
|
399
|
+
``,
|
|
400
|
+
`${report.points.length} branch read(s) over ${report.branchedFields.length} field(s): ${report.branchedFields.join(", ")}`,
|
|
401
|
+
``,
|
|
402
|
+
];
|
|
403
|
+
if (report.undeclared.length === 0) {
|
|
404
|
+
lines.push(`No undeclared branched field. Every field a condition reads is classified.`);
|
|
405
|
+
} else {
|
|
406
|
+
lines.push(`UNDECLARED — branched on, classified by neither list:`);
|
|
407
|
+
for (const finding of report.undeclared) {
|
|
408
|
+
lines.push(` ${finding.field}`);
|
|
409
|
+
for (const point of finding.points) {
|
|
410
|
+
lines.push(` line ${point.line} [${point.construct}] ${point.snippet}`);
|
|
411
|
+
}
|
|
412
|
+
}
|
|
413
|
+
}
|
|
414
|
+
if (report.staleJustification.length > 0) {
|
|
415
|
+
lines.push(
|
|
416
|
+
``,
|
|
417
|
+
`STALE — declared stable, but no condition reads them any more: ${report.staleJustification.join(", ")}`,
|
|
418
|
+
);
|
|
419
|
+
}
|
|
420
|
+
if (report.unmeasurable.length > 0) {
|
|
421
|
+
lines.push(
|
|
422
|
+
``,
|
|
423
|
+
`UNMEASURED — branched on, but the state file does not carry them, so no series ` +
|
|
424
|
+
`can read them: ${report.unmeasurable.join(", ")}. This is not a clean result for ` +
|
|
425
|
+
`those fields; it is the absence of one.`,
|
|
426
|
+
);
|
|
427
|
+
}
|
|
428
|
+
if (report.excluded.length > 0) {
|
|
429
|
+
lines.push(``, `Branched and deliberately not asserted: ${report.excluded.join(", ")}`);
|
|
430
|
+
}
|
|
431
|
+
return lines.join("\n");
|
|
432
|
+
}
|