rungate 0.6.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 +81 -16
- package/lib/behavioral-cache.ts +150 -2
- 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 +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- 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 +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- 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/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- 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 +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -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/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -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-id-cross-tree.ts +19 -7
- 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 +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- 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/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 +241 -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-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- 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/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
package/lib/dev-liveness.ts
CHANGED
|
@@ -188,6 +188,186 @@ export function probeTarget(
|
|
|
188
188
|
return { kind: "probe", url, safeUrl: safeForRecord(url) };
|
|
189
189
|
}
|
|
190
190
|
|
|
191
|
+
/**
|
|
192
|
+
* Where to reach the test container, or why not (#312 SC-A15, harness half).
|
|
193
|
+
*
|
|
194
|
+
* `probeTarget` was written so "unconfigured is UNMEASURED, never DOWN" is
|
|
195
|
+
* decided once (SC-733). It covers `dev` and `prod`. The container is the
|
|
196
|
+
* third tier and never went through it: `workflows/ship.js` built its own URL
|
|
197
|
+
* at two sites, from `(container.hosts || [])[0]` and `container.port || 3000`.
|
|
198
|
+
*
|
|
199
|
+
* Nothing reached either site until now. `ProjectHarnessSchema` did not
|
|
200
|
+
* declare `container`, so the validator deleted the key and both sites took
|
|
201
|
+
* their no-container arm on every run that has ever happened. #307 SC-A1
|
|
202
|
+
* declared it, and SC-A15 is a consumer putting a value there — at which
|
|
203
|
+
* point the first consumer with a `rebuildCommand` and no `hosts` gets:
|
|
204
|
+
*
|
|
205
|
+
* curl -s -o /dev/null -w "%{http_code}" http://undefined:3000/
|
|
206
|
+
*
|
|
207
|
+
* interpolated into an agent prompt, no 200 back, and
|
|
208
|
+
* `prod.smoke = SKIP, smokeSkipReason = test container not running` written
|
|
209
|
+
* into the artefact. That reason is a positive claim about a container
|
|
210
|
+
* nothing contacted, and it is indistinguishable in the record from a probe
|
|
211
|
+
* that ran and found the container down. Every field of `ContainerSchema` is
|
|
212
|
+
* optional, so that config validates.
|
|
213
|
+
*
|
|
214
|
+
* So there are three outcomes and not two, and the difference between the two
|
|
215
|
+
* new ones is which verdict the run has earned:
|
|
216
|
+
*
|
|
217
|
+
* - `unconfigured` — no container. Nothing to measure; the run may SKIP.
|
|
218
|
+
* - `unmeasured` — a container is declared and the config does not say where
|
|
219
|
+
* to reach it. The run measured nothing and must not say otherwise; its
|
|
220
|
+
* caller records FAIL, because SKIP here reads exactly like success.
|
|
221
|
+
* - `probe` — a URL built from values that were all present and well-formed.
|
|
222
|
+
*
|
|
223
|
+
* No default host and no default port. `|| 3000` is the same instinct as the
|
|
224
|
+
* `?? "/health"` this module already refuses: a guessed port is answered by
|
|
225
|
+
* whatever else holds it, and the run reports on a container it never found.
|
|
226
|
+
*/
|
|
227
|
+
export type ContainerProbe =
|
|
228
|
+
| { kind: "unconfigured"; detail: string }
|
|
229
|
+
| { kind: "unmeasured"; detail: string }
|
|
230
|
+
| {
|
|
231
|
+
kind: "probe";
|
|
232
|
+
host: string;
|
|
233
|
+
port: number;
|
|
234
|
+
healthPath: string;
|
|
235
|
+
url: string;
|
|
236
|
+
safeUrl: string;
|
|
237
|
+
};
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* Hostname or IP literal, and nothing else.
|
|
241
|
+
*
|
|
242
|
+
* The host is interpolated into a `curl` command inside an agent prompt and
|
|
243
|
+
* is never shell-quoted there. This charset has no shell metacharacter, no
|
|
244
|
+
* `@` (so no userinfo can ride in) and no `:` (so no second port), which is
|
|
245
|
+
* also why `redactSecrets` has nothing to find in the authority half of the
|
|
246
|
+
* URL this builds. A host that does not match is not sanitised — it is
|
|
247
|
+
* refused, and the run says it was not probed.
|
|
248
|
+
*/
|
|
249
|
+
export const CONTAINER_HOST = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* A character in `healthPath` that means something to a shell (#1031).
|
|
253
|
+
*
|
|
254
|
+
* Same set as `SHELL_METACHARACTERS` in `lib/workflow-security.ts`, and
|
|
255
|
+
* deliberately so: that is the set this project already decided reaches a
|
|
256
|
+
* shell unsafely, and a second, kinder set here would be a second answer to
|
|
257
|
+
* the same question.
|
|
258
|
+
*
|
|
259
|
+
* ## Why `healthPath` needs this when the config file is trusted
|
|
260
|
+
*
|
|
261
|
+
* `.claude/rungate/config.json` IS trusted. It is the operator's own file,
|
|
262
|
+
* `scripts/resolve-config.ts` is the only thing that reads it, and
|
|
263
|
+
* `container.rebuildCommand` is arbitrary command execution by design — a
|
|
264
|
+
* consumer who puts a destructive command behind that key has configured
|
|
265
|
+
* their own run to do that. Gating a trusted file against its own author is
|
|
266
|
+
* theatre, and #1031 names it as the cheapest wrong fix on offer.
|
|
267
|
+
*
|
|
268
|
+
* But the value that reaches the shell is not that file. `workflows/ship.js`
|
|
269
|
+
* cannot read files — the Workflow sandbox has no module loading (#69) — so
|
|
270
|
+
* the block it hands this function is `setupResult.config.container`: the
|
|
271
|
+
* **setup agent's restatement** of a file ship.js never sees, filtered on
|
|
272
|
+
* the way back by a JSON schema that constrains types and no values, and
|
|
273
|
+
* produced in a prompt that also carries issue-authored text. ship.js
|
|
274
|
+
* already names that channel for its neighbouring fields — *the reply agrees
|
|
275
|
+
* with whatever was put in it*, the #530 shape — and routes `harnessSha`
|
|
276
|
+
* through `rookReviewSha` rather than interpolating it, for this reason.
|
|
277
|
+
*
|
|
278
|
+
* So the trusted object and the interpolated object are different objects,
|
|
279
|
+
* and `healthPath` is the one free-form component of the URL this builds.
|
|
280
|
+
* `host` is already charset-filtered above and `port` is already a number;
|
|
281
|
+
* without this rule `/h;id` is an absolute path that is not `//`, so it
|
|
282
|
+
* becomes a `probe` and `;id` runs.
|
|
283
|
+
*
|
|
284
|
+
* REFUSED as `unmeasured`, never sanitised: a quietly repaired path probes a
|
|
285
|
+
* URL nobody configured and records the answer as the container's.
|
|
286
|
+
*
|
|
287
|
+
* ## Why this is narrower than `SHELL_METACHARACTERS`
|
|
288
|
+
*
|
|
289
|
+
* That set refuses `?`, `#`, `*`, `[`, `~` and `!`, and a health path is
|
|
290
|
+
* allowed all of them: `/h?token=…` is a shape this module already supports
|
|
291
|
+
* on purpose — `safeForRecord` exists to redact exactly that query string,
|
|
292
|
+
* and `SC-2485` asserts it. Refusing `?` here would delete a documented
|
|
293
|
+
* consumer shape to block a glob that the quoting added by #1031 at both
|
|
294
|
+
* `curl` sites already makes inert.
|
|
295
|
+
*
|
|
296
|
+
* What stays refused is the set no URL path needs and that ends a quoted
|
|
297
|
+
* shell word or starts a substitution: `;` `&` `|` `$` `` ` `` `"` `'` `\`
|
|
298
|
+
* `<` `>` `{` `}`, whitespace, and control characters. Every payload #1031
|
|
299
|
+
* named — `/h;id`, `/$(id)`, a backtick, `/h'` — is in it.
|
|
300
|
+
*/
|
|
301
|
+
// eslint-disable-next-line no-control-regex
|
|
302
|
+
const CONTAINER_HEALTH_PATH_UNSAFE = /[;&|$`"'\\<>{}\s\u0000-\u001f]/;
|
|
303
|
+
|
|
304
|
+
export function containerProbeTarget(
|
|
305
|
+
container:
|
|
306
|
+
| { port?: unknown; healthPath?: unknown; hosts?: unknown; rebuildCommand?: unknown }
|
|
307
|
+
| null
|
|
308
|
+
| undefined,
|
|
309
|
+
): ContainerProbe {
|
|
310
|
+
if (!container || typeof container !== "object") {
|
|
311
|
+
return {
|
|
312
|
+
kind: "unconfigured",
|
|
313
|
+
detail: "no container is configured for this project",
|
|
314
|
+
};
|
|
315
|
+
}
|
|
316
|
+
const hosts = Array.isArray(container.hosts) ? container.hosts : [];
|
|
317
|
+
const host = hosts.find(
|
|
318
|
+
(h: unknown) => typeof h === "string" && CONTAINER_HOST.test(h),
|
|
319
|
+
) as string | undefined;
|
|
320
|
+
if (!host) {
|
|
321
|
+
return {
|
|
322
|
+
kind: "unmeasured",
|
|
323
|
+
detail:
|
|
324
|
+
"a container is configured and container.hosts names no host to reach it at, " +
|
|
325
|
+
"so nothing was probed. No host is guessed. This is UNMEASURED, not DOWN",
|
|
326
|
+
};
|
|
327
|
+
}
|
|
328
|
+
const port = container.port;
|
|
329
|
+
if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
|
|
330
|
+
return {
|
|
331
|
+
kind: "unmeasured",
|
|
332
|
+
detail:
|
|
333
|
+
`a container is configured at ${host} and container.port is not a port number, ` +
|
|
334
|
+
"so nothing was probed. No default port is invented: a guessed port is answered " +
|
|
335
|
+
"by whatever else holds it. This is UNMEASURED, not DOWN",
|
|
336
|
+
};
|
|
337
|
+
}
|
|
338
|
+
const raw = container.healthPath;
|
|
339
|
+
const healthPath = raw === undefined || raw === null || raw === "" ? "/" : raw;
|
|
340
|
+
// The value is never quoted back. It is the one free-form component here,
|
|
341
|
+
// it reaches a durable artefact, and naming the key is what a reader needs.
|
|
342
|
+
if (
|
|
343
|
+
typeof healthPath !== "string" ||
|
|
344
|
+
!healthPath.startsWith("/") ||
|
|
345
|
+
healthPath.startsWith("//")
|
|
346
|
+
) {
|
|
347
|
+
return {
|
|
348
|
+
kind: "unmeasured",
|
|
349
|
+
detail:
|
|
350
|
+
`a container is configured at ${host} port ${port} and container.healthPath is not ` +
|
|
351
|
+
"an absolute path, so nothing was probed. This is UNMEASURED, not DOWN",
|
|
352
|
+
};
|
|
353
|
+
}
|
|
354
|
+
// #1031 — see CONTAINER_HEALTH_PATH_UNSAFE. The refused value is NOT echoed
|
|
355
|
+
// into the detail: this string is interpolated into a `bun -e` program in an
|
|
356
|
+
// agent prompt and written to a durable artefact, which is the last place
|
|
357
|
+
// the thing we just refused should turn up.
|
|
358
|
+
if (healthPath.length > 200 || CONTAINER_HEALTH_PATH_UNSAFE.test(healthPath)) {
|
|
359
|
+
return {
|
|
360
|
+
kind: "unmeasured",
|
|
361
|
+
detail:
|
|
362
|
+
`a container is configured at ${host} port ${port} and container.healthPath carries ` +
|
|
363
|
+
"whitespace, a shell metacharacter or over 200 characters, so nothing was probed. " +
|
|
364
|
+
"It reaches a curl command an agent runs. This is UNMEASURED, not DOWN",
|
|
365
|
+
};
|
|
366
|
+
}
|
|
367
|
+
const url = `http://${host}:${port}${healthPath}`;
|
|
368
|
+
return { kind: "probe", host, port, healthPath, url, safeUrl: safeForRecord(url) };
|
|
369
|
+
}
|
|
370
|
+
|
|
191
371
|
export function livenessPlan(
|
|
192
372
|
acs: unknown,
|
|
193
373
|
dev: { apiBase?: string; healthPath?: string; start?: string } | undefined,
|
|
@@ -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
|
+
}
|