rungate 0.5.0 → 0.6.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 (55) hide show
  1. package/lib/agents-md-sections.ts +144 -0
  2. package/lib/branch-diff.ts +139 -0
  3. package/lib/bun-version.ts +268 -0
  4. package/lib/ci-checkout.ts +1 -1
  5. package/lib/compliance.ts +13 -11
  6. package/lib/config-loader.ts +12 -0
  7. package/lib/conformity.ts +184 -88
  8. package/lib/context-docs.ts +143 -28
  9. package/lib/create-brief.ts +2 -1
  10. package/lib/create-sc.ts +90 -4
  11. package/lib/doc-scan-targets.ts +9 -0
  12. package/lib/evidence-command-transport.ts +160 -0
  13. package/lib/evidence-prevalidator.ts +22 -0
  14. package/lib/fallow-availability.ts +129 -0
  15. package/lib/gate-refusal-currency.ts +112 -0
  16. package/lib/gate-timeouts.ts +82 -0
  17. package/lib/generators/agent-briefs.ts +4 -1
  18. package/lib/generators/agents-md.ts +71 -23
  19. package/lib/generators/code-map.ts +2 -1
  20. package/lib/generators/types.ts +8 -0
  21. package/lib/git-dates.ts +55 -0
  22. package/lib/junit-checks.ts +484 -0
  23. package/lib/local-calendar-day.ts +78 -0
  24. package/lib/project-state-shape.ts +59 -0
  25. package/lib/promote-outputs.ts +6 -2
  26. package/lib/report-provenance.ts +156 -0
  27. package/lib/sc-claim-forms.ts +75 -0
  28. package/lib/sc-id-cross-tree.ts +311 -0
  29. package/lib/scaffold/ai-review-step.ts +180 -0
  30. package/lib/scaffold/owned-files.ts +42 -2
  31. package/lib/scaffold/rehearsal.ts +205 -71
  32. package/lib/scaffold/steps.ts +128 -73
  33. package/lib/scaffold/write-steps.ts +6 -4
  34. package/lib/scanner.ts +38 -12
  35. package/lib/spec-listing.ts +148 -0
  36. package/lib/spec-requirements.ts +209 -0
  37. package/lib/suite-run-reading.ts +170 -0
  38. package/lib/test-command.ts +133 -0
  39. package/lib/test-suite-lock.ts +166 -10
  40. package/lib/tool-probe.ts +120 -0
  41. package/lib/tracked-vs-ignored.ts +234 -0
  42. package/lib/validators/spec-validators.ts +3 -2
  43. package/package.json +1 -1
  44. package/scripts/audit-specs.ts +247 -12
  45. package/scripts/audit-transcript.ts +2 -1
  46. package/scripts/convert-spec.ts +2 -1
  47. package/scripts/create-sc.ts +17 -7
  48. package/scripts/create-spec.ts +2 -1
  49. package/scripts/create-success.ts +2 -1
  50. package/scripts/extract-constraints.ts +90 -19
  51. package/scripts/generate-code-map.ts +53 -12
  52. package/scripts/scaffold-project.ts +4 -1
  53. package/scripts/split-spec.ts +2 -1
  54. package/scripts/sync-sc-status.ts +57 -5
  55. package/scripts/sync-spec-tests.ts +2 -1
@@ -10,6 +10,14 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from "fs";
12
12
  import { join, basename } from "path";
13
+ import { localCalendarDay } from "../lib/local-calendar-day";
14
+ import {
15
+ fallowAvailable,
16
+ fallowNotInstalled,
17
+ fallowRunFailed,
18
+ fallowUnmeasuredNotice,
19
+ type FallowUnavailable,
20
+ } from "../lib/fallow-availability";
13
21
 
14
22
  const projectPath = process.argv[2];
15
23
  if (!projectPath || !existsSync(projectPath)) {
@@ -18,7 +26,7 @@ if (!projectPath || !existsSync(projectPath)) {
18
26
  }
19
27
 
20
28
  const projectName = basename(projectPath);
21
- const today = new Date().toISOString().split("T")[0];
29
+ const today = localCalendarDay();
22
30
 
23
31
  // ── Fallow analysis ──────────────────────────────────────────
24
32
 
@@ -30,16 +38,38 @@ interface FallowData {
30
38
  elapsed: number;
31
39
  }
32
40
 
33
- function runFallow(): FallowData | null {
41
+ /**
42
+ * Three outcomes, not two (#581).
43
+ *
44
+ * This returned `null` for "not installed", "the spawn failed", "the output
45
+ * did not parse" and — through `||` in the summary table below — "it ran and
46
+ * found zero". A CODE-MAP written from any of them was byte-identical, so a
47
+ * reader could not tell a project with no dead code from a project nobody
48
+ * looked at.
49
+ */
50
+ type FallowOutcome = { data: FallowData } | { unavailable: FallowUnavailable };
51
+
52
+ function runFallow(): FallowOutcome {
53
+ // Resolved locally, with no network path. A bare `npx fallow` for a tool
54
+ // that is not a declared dependency is a registry fetch on the SCAFFOLD
55
+ // path — once per consumer, forever, including behind a proxy and in an
56
+ // air-gapped CI. `lib/conformity.ts` fixed this for itself in #510 and
57
+ // this caller never got it.
58
+ if (!fallowAvailable(projectPath) && !fallowAvailable(process.cwd())) {
59
+ return { unavailable: fallowNotInstalled() };
60
+ }
34
61
  const result = Bun.spawnSync(
35
62
  ["npx", "fallow", "dead-code", "--format", "json", "--quiet"],
36
63
  { cwd: projectPath, timeout: 30_000 }
37
64
  );
38
65
  const stdout = result.stdout.toString().trim();
39
- if (!stdout || stdout.startsWith("{\"error\"")) return null;
66
+ if (!stdout) return { unavailable: fallowRunFailed(`exit ${result.exitCode}, no output`) };
67
+ if (stdout.startsWith("{\"error\"")) {
68
+ return { unavailable: fallowRunFailed(stdout.slice(0, 200)) };
69
+ }
40
70
  try {
41
71
  const d = JSON.parse(stdout);
42
- return {
72
+ return { data: {
43
73
  entryPoints: d.entry_points?.total || 0,
44
74
  unusedFiles: (d.unused_files || []).map((f: any) => f.path),
45
75
  unusedExports: (d.unused_exports || []).map((e: any) => ({
@@ -49,8 +79,10 @@ function runFallow(): FallowData | null {
49
79
  files: c.files || [c.path]
50
80
  })),
51
81
  elapsed: d.elapsed_ms || 0,
52
- };
53
- } catch { return null; }
82
+ } };
83
+ } catch (e) {
84
+ return { unavailable: fallowRunFailed(`output did not parse as JSON (${(e as Error).name})`) };
85
+ }
54
86
  }
55
87
 
56
88
  // ── Route scanning ───────────────────────────────────────────
@@ -192,7 +224,9 @@ function readPackageInfo(): { name: string; deps: number; devDeps: number; scrip
192
224
 
193
225
  console.log(`Scanning ${projectName}...`);
194
226
 
195
- const fallow = runFallow();
227
+ const fallowOutcome = runFallow();
228
+ const fallow = "data" in fallowOutcome ? fallowOutcome.data : null;
229
+ const fallowMissing = "unavailable" in fallowOutcome ? fallowOutcome.unavailable : null;
196
230
  const routes = scanRoutes();
197
231
  const dirs = scanDirectories();
198
232
  const components = scanComponents();
@@ -200,7 +234,9 @@ const pkg = readPackageInfo();
200
234
  const consumerMappings = scanConsumerModules();
201
235
  const pageMappings = scanPageComponents();
202
236
 
203
- console.log(` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : "not available"}`);
237
+ console.log(
238
+ ` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : `UNMEASURED — ${fallowMissing?.reason}`}`,
239
+ );
204
240
  console.log(` Routes: ${routes.length}`);
205
241
  console.log(` Directories: ${dirs.length}`);
206
242
  console.log(` Components: ${components.length}`);
@@ -240,10 +276,10 @@ sections.push(`## Summary
240
276
  | Dev dependencies | ${pkg.devDeps} |
241
277
  | API routes | ${routes.length} |
242
278
  | React components | ${components.length} |
243
- | Entry points (fallow) | ${fallow?.entryPoints || "N/A"} |
244
- | Unused files | ${fallow?.unusedFiles.length || "N/A"} |
245
- | Unused exports | ${fallow?.unusedExports.length || "N/A"} |
246
- | Circular dependencies | ${fallow?.circularDeps.length || "N/A"} |
279
+ | Entry points (fallow) | ${fallow ? fallow.entryPoints : "UNMEASURED"} |
280
+ | Unused files | ${fallow ? fallow.unusedFiles.length : "UNMEASURED"} |
281
+ | Unused exports | ${fallow ? fallow.unusedExports.length : "UNMEASURED"} |
282
+ | Circular dependencies | ${fallow ? fallow.circularDeps.length : "UNMEASURED"} |
247
283
  | Module import mappings | ${consumerMappings.length} |
248
284
  | Page-component mappings | ${pageMappings.length} |`);
249
285
 
@@ -324,6 +360,11 @@ if (fallow) {
324
360
  }
325
361
 
326
362
  sections.push(health.trim());
363
+ } else if (fallowMissing) {
364
+ // Named, not omitted. A missing section and a section reporting nothing
365
+ // wrong are the same absence to a reader, and the reader of a CODE-MAP is
366
+ // an agent deciding whether this project has dead code.
367
+ sections.push(fallowUnmeasuredNotice(fallowMissing));
327
368
  }
328
369
 
329
370
  // Scripts
@@ -104,7 +104,10 @@ if (fix) {
104
104
  // actually do rather than what it would do with different settings (#398).
105
105
  runScaffoldWriteSteps(rehearsal.dir, projectType, actions, { force, commit: false, rehearsing: true, profile, autoFix, pruneConsumers });
106
106
  } finally {
107
- discardRehearsal(rehearsal);
107
+ // #549: a cleanup failure is a sentence, not an exception. The report
108
+ // has already printed by now, and throwing here threw it away.
109
+ const leaked = discardRehearsal(rehearsal);
110
+ if (leaked) console.error(`WARNING: ${leaked}`);
108
111
  }
109
112
  }
110
113
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { readFileSync, writeFileSync, mkdirSync } from "fs";
4
4
  import { join, dirname } from "path";
5
+ import { localCalendarDay } from "../lib/local-calendar-day";
5
6
 
6
7
  export interface SplitBoundary {
7
8
  heading: string;
@@ -166,7 +167,7 @@ export function generateSplitFiles(
166
167
  metadata: { owner: string; testable: boolean }
167
168
  ): SplitFile[] {
168
169
  const lines = content.split("\n");
169
- const now = new Date().toISOString().split("T")[0];
170
+ const now = localCalendarDay();
170
171
  const groups = groupBoundaries(boundaries, lines.length);
171
172
 
172
173
  return groups.map((group) => {
@@ -16,7 +16,7 @@
16
16
 
17
17
  import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
18
18
  import { commentMask, enclosingComment, stripJsComments } from "../lib/strip-js-comments";
19
- import { commentClaimForm, type ClaimForm } from "../lib/sc-claim-forms";
19
+ import { commentClaimForm, titleCall, type ClaimForm } from "../lib/sc-claim-forms";
20
20
  import { join } from "path";
21
21
  import { execSync } from "child_process";
22
22
  import { matchPattern, isBehavioralSC, type ParsedSC } from "../lib/conformity";
@@ -101,8 +101,6 @@ export function findUncheckedSCs(specsDir?: string): UncheckedSC[] {
101
101
  */
102
102
  export const scMentionPattern = oneScMentionPattern;
103
103
 
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
104
 
107
105
  /**
108
106
  * The success criteria a source file CLAIMS to cover (#149).
@@ -189,7 +187,7 @@ export interface ClaimSite {
189
187
  * Where it was written. A comment is a claim for an unambiguous id and is
190
188
  * NOT enough for an ambiguous one — see `findTestFilesForSCs`.
191
189
  */
192
- kind: "comment" | "title" | "bare";
190
+ kind: "comment" | "title" | "unrun-title" | "bare";
193
191
  /**
194
192
  * For a comment, WHICH structural declaring form it occupies, or `null` for
195
193
  * a bare mention inside running prose (#360). Always `null` for the other
@@ -243,7 +241,15 @@ export function coverageClaimSites(source: string): ClaimSite[] {
243
241
  while (open > 0 && !/['"`]/.test(codeOnly[open])) open--;
244
242
  if (!/['"`]/.test(codeOnly[open] ?? "")) continue;
245
243
 
246
- if (TITLE_CALL.test(codeOnly.slice(Math.max(0, open - 120), open))) add(id, at, "title");
244
+ // A title is a declaring position; a title that never runs is a
245
+ // declaration of INTENT (#574). `test.todo("SC-N: …")` is the honest way
246
+ // to write down work you have not done, and crediting it ticked 37
247
+ // criteria whose only test was the word todo. Kept as a site rather than
248
+ // dropped, so the sync can report it as UNMEASURED — dropping it would
249
+ // make "nobody wrote this test" look like "nobody mentioned this id".
250
+ const call = titleCall(codeOnly.slice(Math.max(0, open - 120), open));
251
+ if (call === "runs") add(id, at, "title");
252
+ else if (call === "never-runs") add(id, at, "unrun-title");
247
253
  }
248
254
 
249
255
  return claims;
@@ -324,6 +330,10 @@ export function findTestFilesForSCs(
324
330
  // project declares coverage and where it explains itself, and a bare id
325
331
  // inside a running sentence is a citation.
326
332
  if (kind === "comment" && !form) continue;
333
+ // #574. The direction this is allowed to be wrong in is toward NOT
334
+ // crediting, and a todo is the clearest case there is: nothing can go
335
+ // red, so nothing can be measured.
336
+ if (kind === "unrun-title") continue;
327
337
  for (const specFile of wanted.get(id) ?? []) {
328
338
  if (requiresQualification(id, reg) && !(kind === "title" && isQualifiedBy(source, at, specFile))) continue;
329
339
  if (!credits.some(c => c.id === id && c.specFile === specFile)) {
@@ -336,6 +346,36 @@ export function findTestFilesForSCs(
336
346
  return out;
337
347
  }
338
348
 
349
+ /**
350
+ * Ids whose only declaring position in the test tree is a title that never
351
+ * runs (#574), with the files that name them.
352
+ *
353
+ * An id that ALSO has a running title or a declaring comment anywhere is
354
+ * not here: the question is whether anything can measure it, not whether a
355
+ * todo exists. That distinction is the whole report — otherwise every
356
+ * criterion with a todo beside a real test would be listed as unmeasured
357
+ * and the list would be ignored within a week.
358
+ */
359
+ export function intendedOnly(testDir: string): Map<string, string[]> {
360
+ const out = new Map<string, string[]>();
361
+ if (!existsSync(testDir)) return out;
362
+ const measured = new Set<string>();
363
+ const intended = new Map<string, string[]>();
364
+ for (const file of readdirSync(testDir).filter(f => f.endsWith(".test.ts"))) {
365
+ for (const site of coverageClaimSites(readFileSync(join(testDir, file), "utf-8"))) {
366
+ if (site.kind === "unrun-title") {
367
+ const files = intended.get(site.id) ?? [];
368
+ if (!files.includes(file)) files.push(file);
369
+ intended.set(site.id, files);
370
+ } else if (site.kind === "title" || (site.kind === "comment" && site.form)) {
371
+ measured.add(site.id);
372
+ }
373
+ }
374
+ }
375
+ for (const [id, files] of intended) if (!measured.has(id)) out.set(id, files);
376
+ return out;
377
+ }
378
+
339
379
  /**
340
380
  * Mentions that look like claims and are not credited, with why (#330).
341
381
  *
@@ -631,6 +671,18 @@ if (isDirectExecution) {
631
671
  for (const line of [...unqualified.values()].sort()) console.log(line);
632
672
  }
633
673
 
674
+ // #574. A criterion whose only test is a `.todo` is UNMEASURED, and
675
+ // UNMEASURED has to be loud: `0`, `{}`, `null` and silence are all
676
+ // indistinguishable from success. Reported by name, with the file, so the
677
+ // list is a backlog rather than a number.
678
+ const intended = intendedOnly(TEST_DIR);
679
+ if (intended.size > 0) {
680
+ console.log(`\n⚠️ UNMEASURED: ${intended.size} SC(s) named only by a test that never runs:`);
681
+ for (const [id, files] of [...intended].sort()) {
682
+ console.log(` ${id}: ${files.join(", ")} — a .todo or .skip title is a declaration of intent, not coverage`);
683
+ }
684
+ }
685
+
634
686
  // Step 3: Run hand-written tests — scope by spec file
635
687
  const passingSCs = new Set<string>();
636
688
  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";`,