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.
Files changed (113) 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 +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
package/lib/compliance.ts CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from "fs";
12
12
  import { join, relative } from "path";
13
- import { probeExternalTool } from "./tool-probe";
13
+ import { probeExternalTool, type ToolProbe, type ToolProbeOutcome } from "./tool-probe";
14
14
 
15
15
  // ── Types ──────────────────────────────────────────────────
16
16
 
@@ -31,6 +31,47 @@ export interface FileScore {
31
31
  reporailsFindings: number;
32
32
  reporailsQuality: number | null;
33
33
  findings: InstructionFinding[];
34
+ /**
35
+ * Which tools READ this file — not which found something in it (#755).
36
+ *
37
+ * A file on the surface gets a `FileScore` whether or not any tool ever
38
+ * looked at it, so `findings.length` is the only per-file evidence the
39
+ * report used to carry, and it cannot tell three states apart: the tool
40
+ * ran and found nothing, the tool ran and returned nothing because it
41
+ * broke, and the file genuinely improved. All three are zero findings.
42
+ * This is the reading the count is not.
43
+ */
44
+ scoredBy: ComplianceTool[];
45
+ }
46
+
47
+ /** The external tools Layer 1 scores with, in the order they are reported. */
48
+ export const COMPLIANCE_TOOLS = ["agnix", "reporails"] as const;
49
+
50
+ export type ComplianceTool = (typeof COMPLIANCE_TOOLS)[number];
51
+
52
+ /** A tool that did not answer, as the report names it. */
53
+ export interface UnmeasuredTool {
54
+ /** The tool's name in this report — not the command line it was probed with. */
55
+ tool: ComplianceTool;
56
+ outcome: ToolProbeOutcome;
57
+ /** The probe's own one-liner, carried through unedited. */
58
+ reason: string;
59
+ }
60
+
61
+ /**
62
+ * Whether this report measured what it claims to have measured.
63
+ *
64
+ * A scan that one of its two tools sat out is not a scan with a slightly
65
+ * smaller finding count — it is a scan of an unknown fraction of the surface,
66
+ * and the number it would print is indistinguishable from the number a clean
67
+ * run prints. `UNMEASURED` is the only value that is not.
68
+ */
69
+ export interface ComplianceReading {
70
+ reading: "MEASURED" | "UNMEASURED";
71
+ /** Every tool that did not answer, in probe order. Empty exactly when MEASURED. */
72
+ unmeasured: UnmeasuredTool[];
73
+ /** Names every tool that did not answer and why. Null exactly when MEASURED. */
74
+ reason: string | null;
34
75
  }
35
76
 
36
77
  export interface ComplianceReport {
@@ -42,6 +83,13 @@ export interface ComplianceReport {
42
83
  totalFindings: number;
43
84
  highCount: number;
44
85
  toolsAvailable: { agnix: boolean; reporails: boolean };
86
+ /**
87
+ * The whole probe per tool — outcome and reason, not just the boolean.
88
+ * `toolsAvailable` above is a projection of these and stays for the callers
89
+ * that only ever wanted "can I run this".
90
+ */
91
+ toolProbes: Record<ComplianceTool, ToolProbe>;
92
+ reading: ComplianceReading;
45
93
  }
46
94
 
47
95
  // ── Tool Runners ───────────────────────────────────────────
@@ -201,11 +249,121 @@ export function collectComplianceSurface(root: string, surface?: string[]): stri
201
249
  // wanted — the difference is that it is now a projection of a reading that
202
250
  // still knows which of the three happened.
203
251
 
252
+ /** How each tool is asked whether it is there. */
253
+ const COMPLIANCE_TOOL_PROBE_ARGV: Record<ComplianceTool, string[]> = {
254
+ agnix: ["agnix", "--version"],
255
+ reporails: ["npx", "@reporails/cli", "version"],
256
+ };
257
+
258
+ /**
259
+ * The single seam between this module and the outside world (#597).
260
+ *
261
+ * Every availability question Layer 1 asks is asked here, once per tool, and
262
+ * `probeExternalTool` is called from nowhere else in this file — two deciders
263
+ * that agree are behaviourally one, and a second probe would survive any
264
+ * mutation of this one.
265
+ *
266
+ * A caller may supply a reading per tool. That is how a test forces a tool
267
+ * absent or errored without mutating `PATH`, which is both unavailable to a
268
+ * test running in-process and a global mutation that leaks into whatever else
269
+ * the suite is doing. An injected tool overrides; an omitted one still spawns,
270
+ * so the seam cannot silently drop a tool it was not told about.
271
+ */
272
+ export function probeComplianceTools(
273
+ injected?: Partial<Record<ComplianceTool, ToolProbe>>,
274
+ ): Record<ComplianceTool, ToolProbe> {
275
+ const probes = {} as Record<ComplianceTool, ToolProbe>;
276
+ for (const tool of COMPLIANCE_TOOLS) {
277
+ const given = injected?.[tool];
278
+ if (given) {
279
+ probes[tool] = given;
280
+ continue;
281
+ }
282
+ const [command, ...args] = COMPLIANCE_TOOL_PROBE_ARGV[tool];
283
+ probes[tool] = probeExternalTool(command, args);
284
+ }
285
+ return probes;
286
+ }
287
+
288
+ /**
289
+ * Turns the probes into the report's own verdict about itself.
290
+ *
291
+ * One binding, so there is one thing to mutate, and so no branch can decide
292
+ * separately that a report is clean enough to print a number.
293
+ */
294
+ export function complianceReading(
295
+ probes: Record<ComplianceTool, ToolProbe>,
296
+ ): ComplianceReading {
297
+ const unmeasured: UnmeasuredTool[] = [];
298
+ for (const tool of COMPLIANCE_TOOLS) {
299
+ const probe = probes[tool];
300
+ if (probe.available) continue;
301
+ unmeasured.push({ tool, outcome: probe.outcome, reason: probe.reason });
302
+ }
303
+
304
+ if (unmeasured.length === 0) {
305
+ return { reading: "MEASURED", unmeasured: [], reason: null };
306
+ }
307
+
308
+ // Name every one of them. A warning that does not say what was missing is a
309
+ // warning nobody can act on, and "a tool was unavailable" does not tell an
310
+ // operator whether to install something or to look at a stderr line.
311
+ const named = unmeasured.map(u => `${u.tool} (${u.outcome}): ${u.reason}`).join("; ");
312
+ return {
313
+ reading: "UNMEASURED",
314
+ unmeasured,
315
+ reason:
316
+ `UNMEASURED: ${unmeasured.length} of ${COMPLIANCE_TOOLS.length} compliance tools did not ` +
317
+ `answer — ${named}. The quality score is withheld rather than averaged over the tools ` +
318
+ `that did, because a surface nobody scored has not passed and a number would say it had.`,
319
+ };
320
+ }
321
+
322
+ /**
323
+ * The surface's quality score, or nothing when the reading says nothing was
324
+ * measured.
325
+ *
326
+ * Averaging whatever came back is the shape this exists to refuse: with one
327
+ * tool silent the mean is taken over the files the other tool happened to
328
+ * reach, and it prints as an ordinary number beside an ordinary PASS.
329
+ */
330
+ export function overallQualityOf(
331
+ fileScores: FileScore[],
332
+ reading: ComplianceReading,
333
+ ): number | null {
334
+ if (reading.reading === "UNMEASURED") return null;
335
+ const scored = fileScores.filter(f => f.reporailsQuality !== null);
336
+ if (scored.length === 0) return null;
337
+ return scored.reduce((sum, f) => sum + f.reporailsQuality!, 0) / scored.length;
338
+ }
339
+
340
+ /**
341
+ * The tools that read one file, from a per-tool reading of whether they did.
342
+ *
343
+ * One binding, so a case can mutate the thing that decides coverage rather
344
+ * than a boolean each caller re-derives. The two tools report their having
345
+ * read a file by different routes and neither is a finding count:
346
+ *
347
+ * - agnix is run ONCE over the whole surface, and `runAgnixBatch` returns
348
+ * `null` when it produced nothing parseable. A batch that parsed read every
349
+ * file in it, including the clean ones it says nothing about.
350
+ * - RepoRails is run per file and returns a quality score for each, so its
351
+ * receipt is per file: an entry exists or it does not.
352
+ */
353
+ export function scoredByOf(read: Record<ComplianceTool, boolean>): ComplianceTool[] {
354
+ return COMPLIANCE_TOOLS.filter(tool => read[tool]);
355
+ }
356
+
204
357
  // ── Layer 1: Template Compliance ───────────────────────────
205
358
 
206
359
  export interface TemplateComplianceOpts {
207
360
  surface?: string[];
208
361
  writeReport?: boolean;
362
+ /**
363
+ * Readings to use instead of spawning. Per tool — an omitted tool is still
364
+ * probed for real.
365
+ */
366
+ probes?: Partial<Record<ComplianceTool, ToolProbe>>;
209
367
  }
210
368
 
211
369
  export async function runTemplateCompliance(
@@ -214,19 +372,24 @@ export async function runTemplateCompliance(
214
372
  ): Promise<ComplianceReport> {
215
373
  const files = collectComplianceSurface(root, opts?.surface);
216
374
 
217
- const agnixProbe = probeExternalTool("agnix", ["--version"]);
218
- const reporailsProbe = probeExternalTool("npx", ["@reporails/cli", "version"]);
219
- const agnixAvailable = agnixProbe.available;
220
- const reporailsAvailable = reporailsProbe.available;
375
+ const toolProbes = probeComplianceTools(opts?.probes);
376
+ const reading = complianceReading(toolProbes);
377
+ const agnixAvailable = toolProbes.agnix.available;
378
+ const reporailsAvailable = toolProbes.reporails.available;
221
379
 
222
380
  // agnix: batch mode works fine for file attribution
223
381
  const agnixByFile = new Map<string, AgnixDiagnostic[]>();
224
382
  // RepoRails: per-file mode — batch drops findings for small files
225
383
  const rrByFile = new Map<string, { quality: number | null; findings: RepoRailsFinding[] }>();
226
384
 
227
- if (agnixAvailable) {
385
+ // Whether the batch answered at all. `agnixAvailable` says the probe found
386
+ // the binary; this says the run over this surface produced a reading.
387
+ let agnixRead = false;
388
+
389
+ if (agnixAvailable && files.length > 0) {
228
390
  const results = runAgnixBatch(files);
229
391
  if (results) {
392
+ agnixRead = true;
230
393
  for (const d of results) {
231
394
  const key = d.file;
232
395
  if (!agnixByFile.has(key)) agnixByFile.set(key, []);
@@ -291,6 +454,7 @@ export async function runTemplateCompliance(
291
454
  reporailsFindings: findings.filter(f => f.source === "reporails").length,
292
455
  reporailsQuality,
293
456
  findings,
457
+ scoredBy: scoredByOf({ agnix: agnixRead, reporails: rrData !== undefined }),
294
458
  });
295
459
  }
296
460
 
@@ -300,20 +464,17 @@ export async function runTemplateCompliance(
300
464
  0,
301
465
  );
302
466
 
303
- const qualityScores = fileScores.filter(f => f.reporailsQuality !== null);
304
- const overallQuality = qualityScores.length > 0
305
- ? qualityScores.reduce((sum, f) => sum + f.reporailsQuality!, 0) / qualityScores.length
306
- : null;
307
-
308
467
  const report: ComplianceReport = {
309
468
  timestamp: new Date().toISOString(),
310
469
  layer: "template",
311
470
  surface: files.map(f => relative(root, f)),
312
471
  files: fileScores,
313
- overallQuality,
472
+ overallQuality: overallQualityOf(fileScores, reading),
314
473
  totalFindings,
315
474
  highCount,
316
475
  toolsAvailable: { agnix: agnixAvailable, reporails: reporailsAvailable },
476
+ toolProbes,
477
+ reading,
317
478
  };
318
479
 
319
480
  if (opts?.writeReport !== false) {
@@ -325,12 +486,15 @@ export async function runTemplateCompliance(
325
486
  );
326
487
  }
327
488
 
328
- if (!agnixAvailable) {
329
- console.warn("WARN TOOL-NOT-INSTALLED-agnix: agnix not found — install globally or via npm");
330
- }
331
- if (!reporailsAvailable) {
332
- console.warn("WARN TOOL-NOT-INSTALLED-reporails: @reporails/cli not found — install via npm");
489
+ // SC-183 keeps its marker, but only for the state it describes: a tool that
490
+ // ran and failed is not one that is missing, and telling an operator to
491
+ // install something already installed is the advice the collapsed boolean
492
+ // used to give.
493
+ for (const u of reading.unmeasured) {
494
+ if (u.outcome !== "absent") continue;
495
+ console.warn(`WARN TOOL-NOT-INSTALLED-${u.tool}: ${u.reason} — install it, then re-run`);
333
496
  }
497
+ if (reading.reason) console.warn(`WARN COMPLIANCE-${reading.reason}`);
334
498
 
335
499
  return report;
336
500
  }
@@ -350,6 +514,16 @@ export async function runGeneratedCompliance(
350
514
  `FAIL: Scaffold degraded instruction quality from ${baselineReport.overallQuality.toFixed(1)} to ${report.overallQuality.toFixed(1)}`
351
515
  );
352
516
  }
517
+ } else if (baselineReport) {
518
+ // A comparison that could not be made is not a comparison that passed.
519
+ // Both sides are reported, because "which one had no number" is the first
520
+ // thing anyone reading this will want to know.
521
+ console.warn(
522
+ `WARN COMPLIANCE-UNMEASURED: the Layer 2 degradation check did not run — ` +
523
+ `baseline ${baselineReport.reading.reading}/${baselineReport.overallQuality ?? "no score"}, ` +
524
+ `generated ${report.reading.reading}/${report.overallQuality ?? "no score"}` +
525
+ (report.reading.reason ? ` — ${report.reading.reason}` : ""),
526
+ );
353
527
  }
354
528
 
355
529
  const outDir = join(root, ".rungate");
@@ -119,6 +119,33 @@ export const DEFAULT_TEST_TIMEOUT = 120000;
119
119
  */
120
120
  export const RUNGATE_CONFIG_RELATIVE_PATH = join(".claude", "rungate", "config.json");
121
121
 
122
+ /**
123
+ * Every path a project's rungate config can occupy, in POSIX form, newest
124
+ * layout first (#505).
125
+ *
126
+ * Slash-separated and not `join`ed, because the one consumer outside this
127
+ * module compares them against `.gitignore` patterns and `git check-ignore`
128
+ * output, both of which are POSIX whatever the platform. A `path.join` here
129
+ * would produce backslashes on Windows and silently stop matching.
130
+ *
131
+ * It exists because a question about the config's LOCATION is the same
132
+ * question `resolveConfig` answers, and ADR-002 D1 centralises that for a
133
+ * reason — a second list is a second answer to drift from, and this one is
134
+ * consulted by a step that EDITS the project's ignore rules. A stale entry
135
+ * there does not produce a wrong reading; it produces a config file the
136
+ * project cannot commit.
137
+ */
138
+ export const RUNGATE_CONFIG_IGNORE_PATHS = [
139
+ ".claude/rungate/config.json",
140
+ ".claude/rungate.json",
141
+ ] as const;
142
+
143
+ /** The directory both of the above sit in. */
144
+ export const RUNGATE_CONFIG_PARENT_DIR = ".claude";
145
+
146
+ /** The directory layout's own directory, POSIX form, for the same consumer. */
147
+ export const RUNGATE_CONFIG_DIR = ".claude/rungate";
148
+
122
149
  /**
123
150
  * The resolution (ADR-002 D2(a)). `absent` is TRUTHY and carries no `.test`,
124
151
  * so the four sites that wrote `config?.test?.command || fallback` cannot
@@ -136,7 +163,18 @@ export type ConfigResolution =
136
163
  }
137
164
  | { status: "absent" };
138
165
 
139
- const DIRECTORY_CONFIG_FILES = ["config.json", "roles.json", "hooks.json", "compliance.json"];
166
+ /**
167
+ * The files the directory layout is made of.
168
+ *
169
+ * Exported because the scaffold's `.gitignore` negation has to name each one
170
+ * (#505): the negation re-includes `.claude/rungate/` and then re-excludes
171
+ * its contents, so a config file this list does not carry is a config file
172
+ * the project cannot commit — and losing `roles.json` to a branch switch is
173
+ * the same defect as losing `config.json`. One list, in the module that
174
+ * knows where the config lives, or the two drift and the symptom is a file
175
+ * that silently stops being version-controlled.
176
+ */
177
+ export const DIRECTORY_CONFIG_FILES = ["config.json", "roles.json", "hooks.json", "compliance.json"];
140
178
 
141
179
  /**
142
180
  * ADR-002 D3. `dev.*` is the authored canonical shape; `test.command` keeps