rungate 0.3.0 → 0.4.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.
@@ -0,0 +1,197 @@
1
+ /**
2
+ * Dependency order for decomposed sub-issues (#189).
3
+ *
4
+ * `workflows/ship.js` asked the decomposer for "sub-issues in dependency order
5
+ * (foundations first)", gave it nowhere in the schema to record the answer,
6
+ * and dispatched every sub-issue at once. The ordering was produced, accepted
7
+ * and discarded — #166's shape exactly: **an instruction the agent can follow
8
+ * perfectly without its output changing anything.**
9
+ *
10
+ * ## The run this comes from
11
+ *
12
+ * `wf_92dbb346-949` (#105) decomposed into four sub-issues with genuinely
13
+ * disjoint file claims, which is all `ship.js` validated. The dependency was
14
+ * not in the files — it was in the API. Sub-issue 1 was building
15
+ * `harnessRootFor()` in `lib/paths.ts`; sub-issue 4 needed to call it and
16
+ * could not see sub-issue 1, so it wrote its own:
17
+ *
18
+ * | worktree | signature | behaviour |
19
+ * |---|---|---|
20
+ * | `-5` | `harnessRootFor(root: string)` | resolves the root the caller names |
21
+ * | `-8` | `harnessRootFor(dir: string)` | walks up looking for `HARNESS.md` |
22
+ *
23
+ * Two functions, one name, one file, opposite contracts. Both defensible,
24
+ * both carefully commented, neither author aware of the other. Eight agents,
25
+ * 77 minutes, four worktrees of good work that cannot be combined.
26
+ *
27
+ * ## Why file-disjointness is the wrong test
28
+ *
29
+ * File overlap detects MERGE conflicts. It does not detect SEMANTIC
30
+ * dependencies, and two sub-issues can hold disjoint files and still be
31
+ * ordered whenever one creates something the other consumes: a function, an
32
+ * exported type, a config key one writes and the other reads, a test helper,
33
+ * a CLI flag. The overlap check stays — it catches a different thing and both
34
+ * are needed (#189 AC-3).
35
+ *
36
+ * ## The direction this is allowed to be wrong in
37
+ *
38
+ * Toward REFUSING, never toward running anyway. A cycle, a reference to a
39
+ * sub-issue that does not exist, and a self-dependency all refuse. Falling
40
+ * back to parallel on a dependency it could not read is the fail-open shape
41
+ * `.claude/rules/checks-must-be-able-to-fail.md` opens with, and it would
42
+ * reproduce `wf_92dbb346-949` exactly while reporting that it had scheduled
43
+ * the work.
44
+ */
45
+
46
+ export interface WaveSubIssue {
47
+ title: string;
48
+ /** Titles of sub-issues that must finish first. Absent means none. */
49
+ dependsOn?: string[] | null;
50
+ }
51
+
52
+ export interface WavePlan {
53
+ /** Indexes into the input array, grouped. Everything in a wave is parallel. */
54
+ waves: number[][];
55
+ /** One line per wave that is not the first, saying what it waited for. */
56
+ reasons: string[];
57
+ /** Non-null when no order exists; `waves` is empty and nothing may run. */
58
+ refusal: string | null;
59
+ }
60
+
61
+ /** Titles are matched after trimming and case-folding; agents are inconsistent. */
62
+ function key(title: unknown): string {
63
+ return String(title ?? "").trim().toLowerCase();
64
+ }
65
+
66
+ /**
67
+ * Group sub-issues into waves. Everything in a wave runs concurrently; wave
68
+ * N+1 does not start until wave N is done.
69
+ *
70
+ * Kahn's algorithm, with every failure mode a refusal rather than a dropped
71
+ * edge:
72
+ *
73
+ * - a `dependsOn` naming a sub-issue that is not in the list — the agent
74
+ * invented a dependency or misspelled one, and ignoring it would schedule
75
+ * the work as if the dependency did not exist
76
+ * - a self-dependency, which can never be satisfied
77
+ * - two sub-issues with the same title, because then an edge has two possible
78
+ * targets and picking one is a guess
79
+ * - a cycle, named by the sub-issues still unscheduled
80
+ *
81
+ * The all-independent case returns ONE wave containing everything, which is
82
+ * the positive control: a scheduler that serialised everything would satisfy
83
+ * every ordering case and throw away the whole benefit of decomposition
84
+ * (#189 AC-1).
85
+ */
86
+ export function dependencyWaves(subIssues: readonly WaveSubIssue[] | null | undefined): WavePlan {
87
+ const list = Array.isArray(subIssues) ? subIssues : [];
88
+ if (list.length === 0) return { waves: [], reasons: [], refusal: null };
89
+
90
+ const byTitle = new Map<string, number>();
91
+ for (let i = 0; i < list.length; i++) {
92
+ const k = key(list[i]?.title);
93
+ if (!k) {
94
+ return {
95
+ waves: [],
96
+ reasons: [],
97
+ refusal: `sub-issue ${i + 1} has no title, so nothing can declare a dependency on it (#189)`,
98
+ };
99
+ }
100
+ if (byTitle.has(k)) {
101
+ return {
102
+ waves: [],
103
+ reasons: [],
104
+ refusal:
105
+ `two sub-issues are both titled ${JSON.stringify(String(list[i]!.title).trim())} — a dependency ` +
106
+ `naming that title has two possible targets and picking one is a guess (#189)`,
107
+ };
108
+ }
109
+ byTitle.set(k, i);
110
+ }
111
+
112
+ const needs: number[][] = list.map(() => []);
113
+ for (let i = 0; i < list.length; i++) {
114
+ for (const raw of list[i]?.dependsOn ?? []) {
115
+ const k = key(raw);
116
+ if (!k) continue;
117
+ const target = byTitle.get(k);
118
+ if (target === undefined) {
119
+ return {
120
+ waves: [],
121
+ reasons: [],
122
+ refusal:
123
+ `sub-issue ${JSON.stringify(String(list[i]!.title).trim())} depends on ` +
124
+ `${JSON.stringify(String(raw).trim())}, which is not one of the sub-issues — ` +
125
+ `scheduling around a dependency this run cannot see is how ${"wf_92dbb346-949"} ` +
126
+ `produced two functions with one name (#189)`,
127
+ };
128
+ }
129
+ if (target === i) {
130
+ return {
131
+ waves: [],
132
+ reasons: [],
133
+ refusal:
134
+ `sub-issue ${JSON.stringify(String(list[i]!.title).trim())} depends on itself (#189)`,
135
+ };
136
+ }
137
+ if (!needs[i]!.includes(target)) needs[i]!.push(target);
138
+ }
139
+ }
140
+
141
+ const waves: number[][] = [];
142
+ const reasons: string[] = [];
143
+ const done = new Set<number>();
144
+
145
+ while (done.size < list.length) {
146
+ const ready = [];
147
+ for (let i = 0; i < list.length; i++) {
148
+ if (done.has(i)) continue;
149
+ if (needs[i]!.every(d => done.has(d))) ready.push(i);
150
+ }
151
+ if (ready.length === 0) {
152
+ const stuck = list
153
+ .map((s, i) => (done.has(i) ? null : String(s.title).trim()))
154
+ .filter(Boolean);
155
+ return {
156
+ waves: [],
157
+ reasons: [],
158
+ refusal:
159
+ `the dependsOn graph has a cycle — ${JSON.stringify(stuck)} can never start, because each ` +
160
+ `waits on another of them. Refusing rather than falling back to parallel: a fallback would ` +
161
+ `run exactly the schedule this field exists to prevent, and report that it had ordered the ` +
162
+ `work (#189)`,
163
+ };
164
+ }
165
+ if (waves.length > 0) {
166
+ const waited = [...new Set(ready.flatMap(i => needs[i]!))]
167
+ .map(d => String(list[d]!.title).trim())
168
+ .sort();
169
+ reasons.push(
170
+ `wave ${waves.length + 1} (${ready.map(i => String(list[i]!.title).trim()).join(", ")}) ` +
171
+ `waited for ${waited.join(", ")} — a declared dependsOn, not a file overlap`,
172
+ );
173
+ }
174
+ waves.push(ready);
175
+ for (const i of ready) done.add(i);
176
+ }
177
+
178
+ return { waves, reasons, refusal: null };
179
+ }
180
+
181
+ /**
182
+ * Was this plan serialised, and how much?
183
+ *
184
+ * A run that quietly takes four times as long is a bug report nobody files
185
+ * (#189 AC-5), so the dispatcher logs this whether or not anything waited.
186
+ */
187
+ export function wavePlanSummary(plan: WavePlan, total: number): string {
188
+ if (plan.refusal) return plan.refusal;
189
+ if (plan.waves.length <= 1) {
190
+ return `${total} sub-issue(s) declared no dependsOn — dispatching all of them concurrently`;
191
+ }
192
+ return (
193
+ `${total} sub-issues in ${plan.waves.length} dependency waves ` +
194
+ `(${plan.waves.map(w => w.length).join(" then ")}) — this run is serialised by ` +
195
+ `${plan.waves.length - 1} barrier(s) and will take correspondingly longer`
196
+ );
197
+ }
@@ -0,0 +1,190 @@
1
+ /**
2
+ * Which gate checks cannot fail, and which of those meant to (#183, #176).
3
+ *
4
+ * #176 found three checks in `gates/workflow.test.ts` that were satisfied by
5
+ * configuration or by nothing at all. `tsc-pass` was the clearest: two early
6
+ * returns and an empty tail, no `expect`, no `tsc` invocation, no baseline
7
+ * comparison. It had been counted as a passing gate check for its whole life.
8
+ *
9
+ * #183 is the audit of the rest of that list, and the thing worth building is
10
+ * not a one-time report. **Nothing in the repo could tell a check that is
11
+ * deliberately a warning from a check whose assertion was forgotten**, and
12
+ * that is exactly the gap `tsc-pass` lived in. Three checks are warn-only
13
+ * today; two say so in their own comments and one does not.
14
+ *
15
+ * So the audit is a binding instead of a paragraph: every check with no
16
+ * assertion must be named here with a reason, and every name here must still
17
+ * be a check with no assertion. Both directions fail. Adding an `expect` to a
18
+ * warn-tier check means deleting its entry in the same commit, and adding a
19
+ * check with no assertion means either writing the reason down or writing the
20
+ * assertion.
21
+ */
22
+
23
+ /** One `test(...)` in a gate suite, with the body a brace matcher found. */
24
+ export interface GateCheck {
25
+ /** The first argument to `test(...)`, as written. */
26
+ name: string;
27
+ /** 1-indexed line of the `test(` call. */
28
+ line: number;
29
+ /** Everything between the callback's braces. */
30
+ body: string;
31
+ /** Does any `expect(` appear in the body? */
32
+ hasAssertion: boolean;
33
+ }
34
+
35
+ /**
36
+ * Checks that intentionally only warn, each with the reason.
37
+ *
38
+ * A reason is required because the entry is the documentation. "It is on the
39
+ * list" is the same non-answer as a green check that never looked.
40
+ */
41
+ export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze({
42
+ "quinn-container-port: Quinn tested the container, not the dev server":
43
+ "#344 — turning this into a refusal changes what blocks live runs and needs its own " +
44
+ "measurement. The fix there was that it stops being WRONG (it compared against one " +
45
+ "consumer's literal port); making it block is a separate decision.",
46
+ "spec-decision-compliance: AC language aligns with spec decisions":
47
+ "#409 Decision #9 placed this in the WARN tier explicitly: it matches AC prose against " +
48
+ "regex anti-patterns, and a regex over prose is not a basis for refusing a run.",
49
+ "outcome-evidence-behavioral: OUTCOME AC evidence is not just a number":
50
+ "#183 — reported, not fixed. This one is NOT a documented decision like the two above; " +
51
+ "it is `tsc-pass`'s shape with a console.warn where the assertion should be, and the " +
52
+ "sibling check `outcome-acs-no-skip` two tests above it does assert. Tightening it is a " +
53
+ "behaviour change to a live gate and belongs to its own issue.",
54
+ "ac-issue-alignment: ACs cover goal keywords":
55
+ "#183 — reported, not fixed. Found by this audit, not by #176. ADR-009 C4 asks that ACs " +
56
+ "cover the goal's keywords; the body computes a coverage ratio and warns under 50%. A " +
57
+ "stopword-filtered substring match is not a basis for refusing a run, but nothing said " +
58
+ "so until this entry, which is the whole point of the list.",
59
+ });
60
+
61
+ /**
62
+ * The stub a `describe` block substitutes when there is no workflow state.
63
+ *
64
+ * Not a check and not a warn-tier check — a placeholder so bun does not report
65
+ * an empty describe. It is separated out rather than allowlisted because the
66
+ * property that matters is different: a stub must have an EMPTY body. A stub
67
+ * that grew logic would be a check that runs only when nothing is being gated.
68
+ */
69
+ export const STANDALONE_STUB_NAME = "skipped — no active workflow (standalone run)";
70
+
71
+ /**
72
+ * `expect(` — and `expect<T>(`, which the first draft of this regex missed.
73
+ *
74
+ * It reported `workflow-state.json validates` as having no assertion when the
75
+ * assertion is on the line below, written `expect<boolean>(...)` to widen a
76
+ * narrowed type. A detector that misses a form in its own tree is the second
77
+ * shape in `.claude/rules/checks-must-be-able-to-fail.md`, so the generic form
78
+ * is a case in the test rather than a note here.
79
+ */
80
+ const ASSERTION = /\bexpect\s*(?:<[^>()]*>)?\s*\(/;
81
+
82
+ /** `(`/`[`/`{` depth-aware scan that skips strings, templates and comments. */
83
+ function matchingParen(source: string, openAt: number): number {
84
+ let depth = 0;
85
+ for (let i = openAt; i < source.length; i++) {
86
+ const c = source[i];
87
+ const next = source[i + 1];
88
+ if (c === "/" && next === "/") {
89
+ const nl = source.indexOf("\n", i);
90
+ i = nl === -1 ? source.length : nl;
91
+ continue;
92
+ }
93
+ if (c === "/" && next === "*") {
94
+ const close = source.indexOf("*/", i + 2);
95
+ i = close === -1 ? source.length : close + 1;
96
+ continue;
97
+ }
98
+ if (c === '"' || c === "'" || c === "`") {
99
+ const quote = c;
100
+ i++;
101
+ for (; i < source.length; i++) {
102
+ if (source[i] === "\\") { i++; continue; }
103
+ if (source[i] === quote) break;
104
+ // A `${` inside a template can itself contain the quote character, so
105
+ // the expression is skipped as a unit rather than scanned for one.
106
+ if (quote === "`" && source[i] === "$" && source[i + 1] === "{") {
107
+ let d = 1;
108
+ i += 2;
109
+ for (; i < source.length && d > 0; i++) {
110
+ if (source[i] === "{") d++;
111
+ else if (source[i] === "}") d--;
112
+ }
113
+ i--;
114
+ }
115
+ }
116
+ continue;
117
+ }
118
+ if (c === "(" || c === "[" || c === "{") depth++;
119
+ else if (c === ")" || c === "]" || c === "}") {
120
+ depth--;
121
+ if (depth === 0) return i;
122
+ }
123
+ }
124
+ return -1;
125
+ }
126
+
127
+ /**
128
+ * Every `test("...", ...)` in a suite source, with its body.
129
+ *
130
+ * Brace-matched rather than indentation-matched. An indentation heuristic was
131
+ * the first attempt and it found 27 of 79 — it stopped at the first `});` that
132
+ * happened to sit at the right column, which in a file of nested `describe`
133
+ * blocks is almost immediately. A parser that silently sees a third of its
134
+ * input is the defect this whole file is about, so `parsesEveryCheck` below is
135
+ * asserted by the test rather than assumed here.
136
+ */
137
+ export function gateChecks(source: string): GateCheck[] {
138
+ const checks: GateCheck[] = [];
139
+ const re = /(^|\n)(\s*)test\(\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/g;
140
+ let m: RegExpExecArray | null;
141
+ while ((m = re.exec(source)) !== null) {
142
+ const name = (m[3] ?? m[4] ?? m[5])!;
143
+ const callAt = m.index + m[1]!.length + m[2]!.length;
144
+ const openAt = source.indexOf("(", callAt);
145
+ const closeAt = matchingParen(source, openAt);
146
+ if (closeAt === -1) continue;
147
+ const call = source.slice(openAt, closeAt);
148
+ // The body is everything after the first `=> {` or `function () {` inside
149
+ // the call. Taking the whole call would count an `expect` in the test's
150
+ // own name or options object as an assertion.
151
+ const arrow = call.indexOf("=> {");
152
+ const body = arrow === -1 ? call : call.slice(arrow + 4);
153
+ checks.push({
154
+ name,
155
+ line: source.slice(0, callAt).split("\n").length,
156
+ body,
157
+ hasAssertion: ASSERTION.test(body),
158
+ });
159
+ re.lastIndex = closeAt;
160
+ }
161
+ return checks;
162
+ }
163
+
164
+ /** Checks with no `expect(` anywhere in the body, in source order. */
165
+ export function checksWithoutAssertions(source: string): GateCheck[] {
166
+ return gateChecks(source).filter(c => !c.hasAssertion && c.name !== STANDALONE_STUB_NAME);
167
+ }
168
+
169
+ /** The standalone placeholders, so their emptiness can be asserted. */
170
+ export function standaloneStubs(source: string): GateCheck[] {
171
+ return gateChecks(source).filter(c => c.name === STANDALONE_STUB_NAME);
172
+ }
173
+
174
+ /**
175
+ * Reads a field off `environments` that something other than a measurement
176
+ * writes — #176's second shape.
177
+ *
178
+ * Returns one entry per `sf("environments")?.<env>?.<field>` read, so the
179
+ * audit can name the writer of each. Text, deliberately: the point is to
180
+ * enumerate the reads so a human checks each writer, not to decide which are
181
+ * honest. A detector that tried to decide would be the narrower-than-what-it-
182
+ * detects shape in `.claude/rules/checks-must-be-able-to-fail.md`.
183
+ */
184
+ export function environmentVerdictReads(source: string): string[] {
185
+ const out = new Set<string>();
186
+ for (const m of source.matchAll(/sf\("environments"\)\?\.(\w+)\?\.(\w+)/g)) {
187
+ out.add(`${m[1]}.${m[2]}`);
188
+ }
189
+ return [...out].sort();
190
+ }
@@ -12,6 +12,7 @@ import { join } from "path";
12
12
  import type { ProjectScan } from "./types";
13
13
  import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
14
14
  import { isHarnessItself } from "../harness-identity";
15
+ import { typecheckDecision } from "../typescript-project";
15
16
 
16
17
  /**
17
18
  * Build the AGENTS.md frontmatter block.
@@ -102,11 +103,15 @@ export function generateAgentsMd(scan: ProjectScan): string {
102
103
  // without a tsconfig.json that command prints help and exits 1. Every project
103
104
  // scaffolded by rungate — including rungate — documented a type check that
104
105
  // had never checked anything (#65/#76).
105
- const typecheckRow = !existsSync(join(scan.root, "tsconfig.json"))
106
- ? ""
107
- : existsSync(join(scan.root, "scripts", "typecheck.ts"))
108
- ? `\n| Type check | \`bun scripts/typecheck.ts\` |`
109
- : `\n| Type check | \`bunx tsc --noEmit\` |`;
106
+ //
107
+ // #87 — which command, and whether there is one, is `typecheckDecision`'s to
108
+ // answer. This site had its own copy of the ladder and a third site had a
109
+ // different one again, so a project with its own `typecheck` script was
110
+ // documented as running `bunx tsc --noEmit` instead.
111
+ const typecheckCommand = typecheckDecision(scan.root).command;
112
+ const typecheckRow = typecheckCommand
113
+ ? `\n| Type check | \`${typecheckCommand}\` |`
114
+ : "";
110
115
 
111
116
  // The command that reproduces CI locally. Worth a row only where the script
112
117
  // exists: a documented command that is not present is how the type check row