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
@@ -0,0 +1,193 @@
1
+ /**
2
+ * #804 — how close the suite runs to the budget, read from reports that exist.
3
+ *
4
+ * `lib/junit-checks.ts` has held the two readings this needs since #621:
5
+ * `timeoutProximityViolations` names every case the budget killed and every
6
+ * case that finished inside the band below it, and `durationCoverageViolations`
7
+ * answers the prior question of whether the reading read anything. Both are
8
+ * correct. Neither has ever run against this repository's suite.
9
+ *
10
+ * Measured 2026-10-20 on `1222742b`: `SUITE_JUNIT_REPORT`, the environment
11
+ * variable `test/test-timeout-population.test.ts` takes its live population
12
+ * from, appears five times in the tree and all five are inside that file —
13
+ * four are the function that reads it, and the fifth is the env of the mutant
14
+ * spawn in its own battery. No workflow sets it; `.github/workflows/ci.yml`
15
+ * ran `bun test --shard=N/4` with no reporter, so the report was never
16
+ * written. Both live cases printed
17
+ *
18
+ * [#621] UNMEASURED proximity: no suite JUnit report was provided …
19
+ *
20
+ * on every run, including every CI run, and passed. That is why #804 and #805
21
+ * both arrived as a red `main` rather than as a warning: the instrument that
22
+ * exists to say "this case is at 97% of its budget" had no input.
23
+ *
24
+ * ## Why this is a binding and not a second ratchet
25
+ *
26
+ * #804 proposes building a ratchet. Building one would be the fourth shape in
27
+ * `.claude/rules/checks-must-be-able-to-fail.md` — two deciders answering one
28
+ * question about one input are behaviourally ONE decider, and no behavioural
29
+ * test can tell them apart. So this composes the two existing readings and
30
+ * adds no comparison of its own. What is new here is a population to read.
31
+ *
32
+ * A `bun test` run cannot read its own JUnit report: the file is written when
33
+ * the run ends. So the reading cannot live inside the suite it measures, and
34
+ * this is called afterwards, over the report `bunfig.toml` now declares.
35
+ *
36
+ * ## The band, and why it is not 1%
37
+ *
38
+ * `test/test-timeout-population.test.ts` uses `WITHIN = 0.01`, which is right
39
+ * for what that file claims — "within one percent of the timeout" is #621's
40
+ * AC-3b, stated in those words. It is not a useful warning: against a 5000ms
41
+ * budget it fires at 4950ms, which is 50ms of notice. #804 asks for red
42
+ * "before the suite is", so `DEFAULT_WITHIN` is 0.2 — a case at 80% of its
43
+ * budget is reported, and the scan this issue was filed about would have been
44
+ * named at 3482ms rather than killed at 5005ms.
45
+ *
46
+ * Both numbers are declared, neither is derived from the other, and they
47
+ * answer different questions. That is not the duplication the paragraph above
48
+ * refuses: there is still exactly one implementation of the comparison.
49
+ */
50
+ import {
51
+ bunfigTestTimeoutMs,
52
+ durationCoverageViolations,
53
+ readJunitDurations,
54
+ timeoutProximityViolations,
55
+ type JunitDurationReading,
56
+ } from "./junit-checks";
57
+
58
+ /**
59
+ * 20% of the budget. See the header — 1% is 50ms of notice against the
60
+ * default, which is a warning that arrives after the thing it warns about.
61
+ */
62
+ export const DEFAULT_WITHIN = 0.2;
63
+
64
+ export interface SuiteMarginReading {
65
+ /**
66
+ * The ONE discriminator. `reasons` and `violations` are projections of the
67
+ * same walk and cannot disagree with it — a second boolean beside this
68
+ * would always agree with it, which is two deciders wearing one answer.
69
+ */
70
+ reading: "MEASURED" | "UNMEASURED";
71
+ /** Why it is UNMEASURED. Empty exactly when it is not. */
72
+ reasons: string[];
73
+ /** Cases at or past the band, and cases the budget killed. */
74
+ violations: string[];
75
+ /** Testcases with a readable duration, summed across every report. */
76
+ examined: number;
77
+ /** Reports whose duration list could be read at all. */
78
+ readable: number;
79
+ reports: number;
80
+ /** The budget compared against, or null when none could be read. */
81
+ timeoutMs: number | null;
82
+ withinFraction: number;
83
+ }
84
+
85
+ /**
86
+ * Compose the two existing readings over N reports.
87
+ *
88
+ * FAILS CLOSED. Every path that cannot positively establish that a budget was
89
+ * read and that at least one testcase duration was examined returns
90
+ * UNMEASURED with reasons. There is no path that returns a clean MEASURED
91
+ * from a reading of nothing — `0`, `{}` and silence are indistinguishable
92
+ * from success (`.claude/rules/config-access.md`, Silent Default
93
+ * Substitution), and an empty report satisfies a proximity check by having
94
+ * nothing in it.
95
+ *
96
+ * `read` is injected so a case can force an unreadable report without owning
97
+ * a filesystem. An omitted report is still read, so the seam cannot quietly
98
+ * drop one.
99
+ */
100
+ export function suiteMarginReading(opts: {
101
+ reports: string[];
102
+ bunfigSource: string | null;
103
+ withinFraction?: number;
104
+ read?: (path: string) => JunitDurationReading;
105
+ }): SuiteMarginReading {
106
+ const withinFraction = opts.withinFraction ?? DEFAULT_WITHIN;
107
+ const read = opts.read ?? readJunitDurations;
108
+ const reasons: string[] = [];
109
+ const violations: string[] = [];
110
+
111
+ const timeoutMs = opts.bunfigSource === null ? null : bunfigTestTimeoutMs(opts.bunfigSource);
112
+ if (timeoutMs === null) {
113
+ reasons.push(
114
+ "no [test] timeout is declared in bunfig.toml, so there is no budget to compare against — " +
115
+ "a proximity reading needs the number the runner would kill at, and defaulting to bun's " +
116
+ "built-in 5000 here would be a second declaring position for it (#621, #804)",
117
+ );
118
+ }
119
+
120
+ if (opts.reports.length === 0) {
121
+ reasons.push(
122
+ "no JUnit report was named — nothing was read, which is not the same fact as nothing being " +
123
+ "close to its budget (#804)",
124
+ );
125
+ }
126
+
127
+ let examined = 0;
128
+ let readable = 0;
129
+ for (const path of opts.reports) {
130
+ const reading = read(path);
131
+ violations.push(...durationCoverageViolations(reading, path));
132
+ if (reading.durations === null) continue;
133
+ readable += 1;
134
+ examined += reading.count;
135
+ if (timeoutMs !== null) {
136
+ violations.push(...timeoutProximityViolations(reading, timeoutMs, withinFraction));
137
+ }
138
+ }
139
+
140
+ // Asked AFTER the walk, because the walk is what establishes it. A report
141
+ // that exists, parses, and holds no testcase is the shape #621 warns about:
142
+ // zero durations compared against any budget is perfect agreement.
143
+ if (examined === 0 && opts.reports.length > 0) {
144
+ reasons.push(
145
+ `${opts.reports.length} report(s) named and ${readable} readable, but no testcase duration was ` +
146
+ "read from any of them — a comparison over an empty population passes by having nothing in " +
147
+ "it (#621, #804)",
148
+ );
149
+ }
150
+
151
+ return {
152
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
153
+ reasons,
154
+ violations,
155
+ examined,
156
+ readable,
157
+ reports: opts.reports.length,
158
+ timeoutMs,
159
+ withinFraction,
160
+ };
161
+ }
162
+
163
+ /**
164
+ * Whether the caller must refuse, as ONE binding.
165
+ *
166
+ * UNMEASURED refuses with the violations rather than beside them, and that is
167
+ * the decision this function exists to hold in one place. A reading that could
168
+ * not be taken is not a reading that passed — the whole of #804 is a check
169
+ * printing UNMEASURED on every run and nobody acting on it, so the version of
170
+ * this that exits 0 on UNMEASURED reproduces the defect it was written for.
171
+ */
172
+ export function suiteMarginRefusal(reading: SuiteMarginReading): string | null {
173
+ if (reading.reading === "UNMEASURED") {
174
+ return `UNMEASURED: ${reading.reasons.join("; ")}`;
175
+ }
176
+ if (reading.violations.length > 0) {
177
+ return `${reading.violations.length} case(s) at or past ${reading.withinFraction * 100}% of the ${reading.timeoutMs}ms budget`;
178
+ }
179
+ return null;
180
+ }
181
+
182
+ /** The sentence a caller prints instead of the verdict on its own. */
183
+ export function describeSuiteMargin(reading: SuiteMarginReading): string {
184
+ const head =
185
+ reading.reading === "UNMEASURED"
186
+ ? `UNMEASURED: the suite's margin against its budget was not read.`
187
+ : reading.violations.length === 0
188
+ ? `MEASURED: ${reading.examined} testcase(s) across ${reading.readable} report(s), none within ` +
189
+ `${reading.withinFraction * 100}% of the ${reading.timeoutMs}ms budget.`
190
+ : `${reading.violations.length} case(s) within ${reading.withinFraction * 100}% of the ` +
191
+ `${reading.timeoutMs}ms budget, of ${reading.examined} examined across ${reading.readable} report(s).`;
192
+ return [head, ...reading.reasons.map(r => ` - ${r}`), ...reading.violations.map(v => ` - ${v}`)].join("\n");
193
+ }