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.
Files changed (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -15,12 +15,14 @@
15
15
  */
16
16
 
17
17
  import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
18
+
19
+ import { walkTestFiles } from "../lib/walk-test-files";
18
20
  import { commentMask, enclosingComment, stripJsComments } from "../lib/strip-js-comments";
19
- import { commentClaimForm, type ClaimForm } from "../lib/sc-claim-forms";
21
+ import { commentClaimForm, titleCall, type ClaimForm } from "../lib/sc-claim-forms";
20
22
  import { join } from "path";
21
23
  import { execSync } from "child_process";
22
24
  import { matchPattern, isBehavioralSC, type ParsedSC } from "../lib/conformity";
23
- import { readFreshCache } from "../lib/behavioral-cache";
25
+ import { behavioralCachePath, readFreshCache } from "../lib/behavioral-cache";
24
26
  import { detectDrift } from "./detect-sc-drift";
25
27
  import {
26
28
  ambiguityOf,
@@ -32,6 +34,7 @@ import {
32
34
  requiresQualification,
33
35
  scDeclarationPattern,
34
36
  scMentionPattern as scIdMentionPattern,
37
+ unenumeratedScRegistry,
35
38
  type ScRegistry,
36
39
  } from "../lib/sc-ids";
37
40
 
@@ -55,13 +58,28 @@ export interface UncheckedSC {
55
58
  * Built from the same spec scan `findUncheckedSCs` walks, so the ids a test
56
59
  * can be credited for and the ids a spec declares are the same set by
57
60
  * construction rather than by two regexes agreeing.
61
+ *
62
+ * ## An absent `specs/` is UNENUMERATED, not "declares nothing" (#606)
63
+ *
64
+ * This is the one producer feeding `allocateScNumber` in the live CLI
65
+ * (`scripts/create-sc.ts`), and it returned `buildScRegistry([])` for a tree
66
+ * with no `specs/` at all. That registry says "this tree declares nothing",
67
+ * which the allocator then reported as a consulted width contributing zero
68
+ * ids. A fix on the reading side alone cannot see this: the registry leg
69
+ * would faithfully report an enumeration flag nobody had ever set wrong.
58
70
  */
59
71
  export function readScRegistry(specsDir?: string): ScRegistry {
60
72
  const dir = specsDir || SPECS_DIR;
61
- if (!existsSync(dir)) return buildScRegistry([]);
73
+ if (!existsSync(dir)) return unenumeratedScRegistry(`${dir} does not exist`);
62
74
  const specs: Array<{ file: string; content: string }> = [];
63
- for (const file of new Bun.Glob("**/*.md").scanSync({ cwd: dir, absolute: false })) {
64
- specs.push({ file, content: readFileSync(join(dir, file), "utf-8") });
75
+ try {
76
+ for (const file of new Bun.Glob("**/*.md").scanSync({ cwd: dir, absolute: false })) {
77
+ specs.push({ file, content: readFileSync(join(dir, file), "utf-8") });
78
+ }
79
+ } catch (err) {
80
+ // A directory that exists and cannot be listed or read. Same fact as an
81
+ // absent one from the allocator's side, and a different reason.
82
+ return unenumeratedScRegistry(`${dir} could not be enumerated: ${(err as Error).message}`);
65
83
  }
66
84
  return buildScRegistry(specs);
67
85
  }
@@ -101,8 +119,6 @@ export function findUncheckedSCs(specsDir?: string): UncheckedSC[] {
101
119
  */
102
120
  export const scMentionPattern = oneScMentionPattern;
103
121
 
104
- /** Opens a `describe`/`test`/`it` title, allowing `.each(...)`, `.only`, `.skip`. */
105
- const TITLE_CALL = /\b(?:describe|test|it)\s*(?:\.\w+\s*(?:\([^)]*\))?\s*)*\(\s*$/;
106
122
 
107
123
  /**
108
124
  * The success criteria a source file CLAIMS to cover (#149).
@@ -189,7 +205,7 @@ export interface ClaimSite {
189
205
  * Where it was written. A comment is a claim for an unambiguous id and is
190
206
  * NOT enough for an ambiguous one — see `findTestFilesForSCs`.
191
207
  */
192
- kind: "comment" | "title" | "bare";
208
+ kind: "comment" | "title" | "unrun-title" | "bare";
193
209
  /**
194
210
  * For a comment, WHICH structural declaring form it occupies, or `null` for
195
211
  * a bare mention inside running prose (#360). Always `null` for the other
@@ -243,7 +259,15 @@ export function coverageClaimSites(source: string): ClaimSite[] {
243
259
  while (open > 0 && !/['"`]/.test(codeOnly[open])) open--;
244
260
  if (!/['"`]/.test(codeOnly[open] ?? "")) continue;
245
261
 
246
- if (TITLE_CALL.test(codeOnly.slice(Math.max(0, open - 120), open))) add(id, at, "title");
262
+ // A title is a declaring position; a title that never runs is a
263
+ // declaration of INTENT (#574). `test.todo("SC-N: …")` is the honest way
264
+ // to write down work you have not done, and crediting it ticked 37
265
+ // criteria whose only test was the word todo. Kept as a site rather than
266
+ // dropped, so the sync can report it as UNMEASURED — dropping it would
267
+ // make "nobody wrote this test" look like "nobody mentioned this id".
268
+ const call = titleCall(codeOnly.slice(Math.max(0, open - 120), open));
269
+ if (call === "runs") add(id, at, "title");
270
+ else if (call === "never-runs") add(id, at, "unrun-title");
247
271
  }
248
272
 
249
273
  return claims;
@@ -307,6 +331,9 @@ export function findTestFilesForSCs(
307
331
  const dir = testDir || TEST_DIR;
308
332
  const out = new Map<string, ScCredit[]>();
309
333
  if (!existsSync(dir)) return out;
334
+ // Tree-wide, and taken before any file is read: whether a criterion has a
335
+ // running test anywhere is not a question a single file can answer (#810).
336
+ const intended = new Set(intendedOnly(dir).keys());
310
337
 
311
338
  const wanted = new Map<string, string[]>();
312
339
  for (const sc of scs) {
@@ -315,7 +342,7 @@ export function findTestFilesForSCs(
315
342
  wanted.set(sc.id, specs);
316
343
  }
317
344
 
318
- for (const file of readdirSync(dir).filter(f => f.endsWith(".test.ts"))) {
345
+ for (const file of walkTestFiles(dir)) {
319
346
  const source = readFileSync(join(dir, file), "utf-8");
320
347
  const credits: ScCredit[] = [];
321
348
  for (const { id, at, kind, form } of coverageClaimSites(source)) {
@@ -324,6 +351,25 @@ export function findTestFilesForSCs(
324
351
  // project declares coverage and where it explains itself, and a bare id
325
352
  // inside a running sentence is a citation.
326
353
  if (kind === "comment" && !form) continue;
354
+ // #574. The direction this is allowed to be wrong in is toward NOT
355
+ // crediting, and a todo is the clearest case there is: nothing can go
356
+ // red, so nothing can be measured.
357
+ if (kind === "unrun-title") continue;
358
+ // #810. That refusal was per-POSITION, so it dropped the todo's own
359
+ // claim and then accepted a comment in ANOTHER file for the same id —
360
+ // two statements about one criterion, and the weaker one decided. A
361
+ // todo is a statement about execution; a comment is not. `intendedOnly`
362
+ // is the one binding that answers it, so there is one thing to mutate.
363
+ //
364
+ // Deliberately NOT `kind === "comment" && intended.has(id)`. The first
365
+ // draft was, it reads as the narrower and therefore safer form, and it
366
+ // is unreachable: `intendedOnly` excludes any id with a running title,
367
+ // so the only kinds that can reach here for an id it names are the ones
368
+ // the conjunct would have admitted anyway. Measured — the battery row
369
+ // for widening it to this was 0 of 10, which is the fourth shape in
370
+ // `.claude/rules/checks-must-be-able-to-fail.md` and the reason AC-2
371
+ // had no witness until the conjunct came out.
372
+ if (intended.has(id)) continue;
327
373
  for (const specFile of wanted.get(id) ?? []) {
328
374
  if (requiresQualification(id, reg) && !(kind === "title" && isQualifiedBy(source, at, specFile))) continue;
329
375
  if (!credits.some(c => c.id === id && c.specFile === specFile)) {
@@ -336,6 +382,60 @@ export function findTestFilesForSCs(
336
382
  return out;
337
383
  }
338
384
 
385
+ /**
386
+ * Ids whose only declaring position in the test tree is a title that never
387
+ * runs (#574), with the files that name them.
388
+ *
389
+ * An id that ALSO has a running title anywhere is not here: the question is
390
+ * whether anything can measure it, not whether a todo exists. That
391
+ * distinction is the whole report — otherwise every criterion with a todo
392
+ * beside a real test would be listed as unmeasured and the list would be
393
+ * ignored within a week.
394
+ *
395
+ * ## A declaring comment used to count as measurement, and it does not (#810)
396
+ *
397
+ * It was the natural reading and it is wrong in one direction only, which is
398
+ * why nobody noticed: a comment is where this project DECLARES coverage, so a
399
+ * declaring comment plus a todo read as "somebody wrote the test and left a
400
+ * stale todo beside it". The population it actually describes is the
401
+ * opposite — a file about something else quoting the criterion as fixture
402
+ * input, in a docstring, on its own line, which is a declaring form.
403
+ *
404
+ * Measured on this tree at the time of #810: **five** ids were in that state
405
+ * and **zero** of them had a running title. Four were `SC-1930`, `SC-1940`,
406
+ * `SC-1943` and `SC-1944`, cited by `audit-specs-fallback-scope.test.ts` and
407
+ * `audit-specs-rewrite-fidelity.test.ts` — both tests of the spec-rewriting
408
+ * tool, neither a test of a rule-lifecycle criterion. `sync-sc-status.ts`
409
+ * ticked all four, and the tick then broke the citing file's own premise,
410
+ * which asserts the spec still reads `- [ ] SC-1940: …`.
411
+ *
412
+ * So the comparison this makes is between a statement about EXECUTION and a
413
+ * statement about intent. A comment is neither, and crediting it here made
414
+ * `SC-1957`'s invariant — *"an id is reported unmeasured AND credited by a
415
+ * test claim"* — true by construction: an id with a declaring comment could
416
+ * not enter this report, so the two readings could not disagree. Narrowing
417
+ * `measured` is what gives that case something to see.
418
+ */
419
+ export function intendedOnly(testDir: string): Map<string, string[]> {
420
+ const out = new Map<string, string[]>();
421
+ if (!existsSync(testDir)) return out;
422
+ const measured = new Set<string>();
423
+ const intended = new Map<string, string[]>();
424
+ for (const file of walkTestFiles(testDir)) {
425
+ for (const site of coverageClaimSites(readFileSync(join(testDir, file), "utf-8"))) {
426
+ if (site.kind === "unrun-title") {
427
+ const files = intended.get(site.id) ?? [];
428
+ if (!files.includes(file)) files.push(file);
429
+ intended.set(site.id, files);
430
+ } else if (site.kind === "title") {
431
+ measured.add(site.id);
432
+ }
433
+ }
434
+ }
435
+ for (const [id, files] of intended) if (!measured.has(id)) out.set(id, files);
436
+ return out;
437
+ }
438
+
339
439
  /**
340
440
  * Mentions that look like claims and are not credited, with why (#330).
341
441
  *
@@ -468,9 +568,10 @@ export function checkConformitySCs(uncheckedSCs: UncheckedSC[], root: string): C
468
568
  const failing = new Set<string>();
469
569
  const unmatchable = new Set<string>();
470
570
 
471
- // Read behavioral cache for behavioral SCs
472
- const cachePath = join(root, ".rungate", "behavioral-results.json");
473
- const behavioralCache = readFreshCache(cachePath);
571
+ // Read behavioral cache for behavioral SCs. Same binding the conformity
572
+ // suite asserts through, so the tick-decider and the gate cannot disagree
573
+ // about where the evidence lives (#328).
574
+ const behavioralCache = readFreshCache(behavioralCachePath(root));
474
575
 
475
576
  for (const sc of uncheckedSCs) {
476
577
  const statement = sc.statement || "";
@@ -621,7 +722,7 @@ if (isDirectExecution) {
621
722
  // Mentions that look like claims and are not credited. Visible on purpose:
622
723
  // under-crediting is the safe direction and still a measurement error.
623
724
  const unqualified = new Map<string, string>();
624
- for (const file of readdirSync(TEST_DIR).filter(f => f.endsWith(".test.ts"))) {
725
+ for (const file of walkTestFiles(TEST_DIR)) {
625
726
  for (const u of unqualifiedClaims(readFileSync(join(TEST_DIR, file), "utf-8"), registry)) {
626
727
  unqualified.set(`${file} ${u.id}`, ` ${file}: ${u.id} — ${u.reason}`);
627
728
  }
@@ -631,6 +732,18 @@ if (isDirectExecution) {
631
732
  for (const line of [...unqualified.values()].sort()) console.log(line);
632
733
  }
633
734
 
735
+ // #574. A criterion whose only test is a `.todo` is UNMEASURED, and
736
+ // UNMEASURED has to be loud: `0`, `{}`, `null` and silence are all
737
+ // indistinguishable from success. Reported by name, with the file, so the
738
+ // list is a backlog rather than a number.
739
+ const intended = intendedOnly(TEST_DIR);
740
+ if (intended.size > 0) {
741
+ console.log(`\n⚠️ UNMEASURED: ${intended.size} SC(s) named only by a test that never runs:`);
742
+ for (const [id, files] of [...intended].sort()) {
743
+ console.log(` ${id}: ${files.join(", ")} — a .todo or .skip title is a declaration of intent, not coverage`);
744
+ }
745
+ }
746
+
634
747
  // Step 3: Run hand-written tests — scope by spec file
635
748
  const passingSCs = new Set<string>();
636
749
  const failingSCs = new Set<string>();
@@ -17,6 +17,7 @@ import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
17
17
  import { collectSpecFiles } from "../lib/spec-files";
18
18
  import { resolve, join } from "path";
19
19
  import { harnessRootFor } from "../lib/paths";
20
+ import { localCalendarDay } from "../lib/local-calendar-day";
20
21
 
21
22
  /**
22
23
  * Where this script reads specs and writes tests (#141).
@@ -208,7 +209,7 @@ function generateTest(claims: Claim[]): string {
208
209
  `// AUTO-GENERATED by scripts/sync-spec-tests.ts — do not edit manually`,
209
210
  `// Regenerate: bun scripts/sync-spec-tests.ts`,
210
211
  `// Source: specs/ (every spec with testable: true)`,
211
- `// Generated: ${new Date().toISOString().split("T")[0]}`,
212
+ `// Generated: ${localCalendarDay()}`,
212
213
  ``,
213
214
  `import { test, expect, describe } from "bun:test";`,
214
215
  `import { readFileSync } from "fs";`,