@cbartens/bkit 5.5.1 → 6.0.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 (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -6,6 +6,8 @@
6
6
  // order is the contract). Nothing declared is its own exit code, never an empty
7
7
  // command that exits 0 and reads as a clean run. A gate that exits 126 / 127 never
8
8
  // ran (not executable / not found), so it is not recorded as a failing test.
9
+ // The failure count comes from the JUnit reports the gate's runners write into
10
+ // `{log}.reports/` (`BKIT_TEST_REPORT_DIR`), never from reading the log.
9
11
  //
10
12
  // bkit tests red / green — test-first evidence for build tasks. Both run one test
11
13
  // file through the consumer's `bkit:test:file` script and judge its JUnit report,
@@ -17,15 +19,27 @@ import * as fs from "node:fs";
17
19
  import * as os from "node:os";
18
20
  import * as path from "node:path";
19
21
  import { BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
20
- import { CommandError, EXIT, git } from "../lib.js";
22
+ import { clampLogPath } from "../../ledgers/clamp-log.js";
23
+ import { CommandError, EXIT, git, runGit } from "../lib.js";
24
+ import { parseJson } from "../../shared/json.js";
21
25
  import { readPackageJson } from "../../shared/package-json.js";
22
26
  import { COULD_NOT_RUN_EXIT_CODES, scriptCommand } from "../../shared/package-manager.js";
23
- import { FILE_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, positiveInt, readStatusRows, statusFile, str, } from "./status.js";
27
+ import { CONFIG_DEFAULTS, readBkitConfig } from "../../shared/settings.js";
28
+ import { FILE_FLAG, GROUP_FLAG, WORKFLOW_FLAG, positiveInt, readStatusRows, statusFile, str, } from "./status.js";
29
+ import { fenceNeverClosed, parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
24
30
  import { writeStepRow } from "./steps.js";
31
+ import { appendRecord, clampFile } from "./context.js";
25
32
  /** Exit code: no candidate gate is declared in package.json. */
26
33
  export const EXIT_NO_GATE = 3;
27
34
  /** Exit code: the gate could not run (exit 126 / 127, or the package runner is missing). */
28
35
  export const EXIT_COULD_NOT_RUN = 4;
36
+ /** Exit code: --artifact could not be written, trimmed or recorded. */
37
+ export const EXIT_ARTIFACT_STEP = 5;
38
+ /** The env var naming the folder every runner a gate calls writes its JUnit XML into. */
39
+ export const REPORT_DIR_ENV = "BKIT_TEST_REPORT_DIR";
40
+ const NO_REPORT_HINT = `no JUnit report in $${REPORT_DIR_ENV} — failures unknown; turn on each test runner's JUnit ` +
41
+ `reporter in the gate and point its output into $${REPORT_DIR_ENV} ` +
42
+ "(.bkit/workflows.md § Local gate scripts)";
29
43
  const DEFAULT_TAIL = 40;
30
44
  const NO_GATE_HINT = "declare a bkit:gate:* script in package.json that runs your stack's checks " +
31
45
  "(.bkit/workflows.md § Local gate scripts lists the names and what each covers)";
@@ -67,7 +81,27 @@ export function runToLog(argv, cwd, log, env) {
67
81
  return res.status;
68
82
  return 128 + ((res.signal ? os.constants.signals[res.signal] : undefined) ?? 1);
69
83
  }
70
- const tailLines = (file, n) => fs.readFileSync(file, "utf-8").replace(/\n$/, "").split("\n").slice(-n);
84
+ /** `{log}.reports`, emptied: a previous attempt's reports never count toward this one. */
85
+ function freshReportDir(log) {
86
+ const dir = `${log}.reports`;
87
+ fs.rmSync(dir, { recursive: true, force: true });
88
+ fs.mkdirSync(dir, { recursive: true });
89
+ return dir;
90
+ }
91
+ /** Failing plus erroring test cases across every `*.xml` under `dir`; null when there is none. */
92
+ export function countReportFailures(dir) {
93
+ const xml = fs.readdirSync(dir, { recursive: true }).filter((f) => f.endsWith(".xml") && fs.statSync(path.join(dir, f)).isFile());
94
+ if (xml.length === 0)
95
+ return null;
96
+ return xml
97
+ .flatMap((f) => parseJunit(fs.readFileSync(path.join(dir, f), "utf-8")))
98
+ .filter((c) => c.state === "failure" || c.state === "error").length;
99
+ }
100
+ const tailLines = (file, n) => fs
101
+ .readFileSync(file, "utf-8")
102
+ .replace(/\r?\n$/, "")
103
+ .split(/\r?\n/)
104
+ .slice(-n);
71
105
  // ---------------------------------------------------------------------------
72
106
  // Test-first: JUnit reading, plan `Test first:` lines, red / green judgement
73
107
  // ---------------------------------------------------------------------------
@@ -158,61 +192,301 @@ export function judgeGreen(cases, want) {
158
192
  ? null
159
193
  : `"${want}" ${bad.state}${bad.message ? `: ${bad.message}` : ""}`;
160
194
  }
161
- const TASK_LINE = /^\s*- \[[ xX]\] \*\*Task (\d+):\*\*/;
162
- const TEST_FIRST = "**Test first:**";
163
- /** `text` split on `;` outside backticks. */
164
- function splitEntries(text) {
165
- const out = [];
166
- let cur = "";
167
- let quoted = false;
168
- for (const ch of text) {
169
- if (ch === "`")
170
- quoted = !quoted;
171
- if (ch === ";" && !quoted) {
172
- out.push(cur);
173
- cur = "";
195
+ /** The task field naming a task's tests, and the one recording an accepted test-order gap. */
196
+ export const TEST_FIRST = "**TEST FIRST:**";
197
+ export const TEST_EXCEPTION = "**TEST EXCEPTION:**";
198
+ /** Why `tests green` refuses a plan with no group and task blocks. */
199
+ export const NO_MARKERS_REASON = "this plan has no task markers; run /bkit-build again to convert it";
200
+ /** The plan caps `package.json` `bkit.workflows.tasks` sets for the checkout `cwd` sits in. */
201
+ export const planCaps = (cwd) => readBkitConfig(toplevel(cwd)).tasks;
202
+ /** The caps as the plan-check report and help state them. */
203
+ export const capsText = (c) => `${c.maxPerGroup} tasks and ${c.maxTestsPerGroup} TEST FIRST tests per group; ${c.maxTestsPerTask} tests across ${c.maxTestFilesPerTask} test files per task`;
204
+ /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
205
+ function testFirstOf(t) {
206
+ const { task, testFirst: tf, testException: exc } = t;
207
+ const plain = (tests) => tests.map(({ test, name }) => ({ test, name }));
208
+ if (tf === undefined)
209
+ return exc === undefined ? { task, kind: "missing" } : { task, kind: "na", reason: exc.text };
210
+ if (tf.malformed.length > 0 || (tf.tests.length === 0 && tf.na === undefined))
211
+ return { task, kind: "malformed" };
212
+ if (tf.tests.length === 0)
213
+ return { task, kind: "na", reason: tf.na };
214
+ const tests = plain(tf.tests);
215
+ return exc === undefined || exc.tests.length === 0
216
+ ? { task, kind: "test", tests }
217
+ : { task, kind: "test", tests, exception: { tests: plain(exc.tests), lines: exc.lines } };
218
+ }
219
+ /**
220
+ * Each task block's TEST FIRST field (`plan-blocks.ts`): one test per sub-bullet (first
221
+ * backticked span = file, second = test name), `n/a — {reason}`, missing, or malformed
222
+ * (an entry with fewer than two spans, or no entry). A TEST EXCEPTION field names, in
223
+ * the same entry form, the tests whose test-order gaps it accepts. `group` narrows to
224
+ * one group's tasks.
225
+ */
226
+ export function readTestFirst(plan, group) {
227
+ return parsePlanBlocks(plan)
228
+ .tasks.filter((t) => group === undefined || t.group === group)
229
+ .map(testFirstOf);
230
+ }
231
+ /** Per task, the planned tests and distinct test files it names (`n/a`, missing and malformed count 0). */
232
+ export const taskSizes = (specs) => specs.map((s) => s.kind === "test"
233
+ ? { task: s.task, tests: s.tests.length, files: new Set(s.tests.map((t) => t.test)).size }
234
+ : { task: s.task, tests: 0, files: 0 });
235
+ /**
236
+ * Files with a NEW row in the plan's Reuse Inventory table (`reuseInventory`): the
237
+ * paths in the `File` cell of each row whose `Decision` cell reads NEW.
238
+ */
239
+ export function inventoryNewFiles(text) {
240
+ const rows = reuseInventory(text)?.rows ?? [];
241
+ return new Set(rows.filter((r) => /^\**new\b/i.test(r.decision)).flatMap((r) => r.files));
242
+ }
243
+ const kb1 = (bytes) => Math.round((bytes / 1024) * 10) / 10;
244
+ /**
245
+ * One plan's groups and tasks against the caps and the block format: parse errors and
246
+ * task-like text outside every block, a task without DONE WHEN or without TEST FIRST and
247
+ * TEST EXCEPTION, a malformed TEST FIRST, a DEPENDS ON naming a missing task or one in a
248
+ * later group, a group or task over a cap in `caps`, a CREATE file with no NEW Reuse
249
+ * Inventory row.
250
+ */
251
+ export function checkPlanText(text, caps = CONFIG_DEFAULTS.tasks) {
252
+ const blocks = parsePlanBlocks(text);
253
+ const lines = text.split(/\r?\n/);
254
+ const problems = blocks.errors.map((e) => ({
255
+ line: e.line,
256
+ kind: e.kind,
257
+ message: e.message,
258
+ }));
259
+ if (blocks.tasks.length === 0 && blocks.fenceOpen === undefined)
260
+ problems.push({
261
+ line: 1,
262
+ kind: "markers",
263
+ message: "no task markers: write each task as a `<!-- bkit:task N start -->` block inside a `<!-- bkit:group N start -->` block",
264
+ });
265
+ const specs = new Map(blocks.tasks.map((t) => [t.task, testFirstOf(t)]));
266
+ const sizes = blocks.tasks.map((t) => {
267
+ const s = specs.get(t.task);
268
+ const tests = s.kind === "test" ? s.tests : [];
269
+ return {
270
+ task: t.task,
271
+ group: t.group,
272
+ tests: tests.length,
273
+ files: new Set(tests.map((x) => x.test)).size,
274
+ };
275
+ });
276
+ const overCap = sizes.filter((t) => t.tests > caps.maxTestsPerTask || t.files > caps.maxTestFilesPerTask);
277
+ const byTask = new Map(blocks.tasks.map((t) => [t.task, t]));
278
+ const newFiles = inventoryNewFiles(text);
279
+ for (const t of blocks.tasks) {
280
+ const field = (message, line = t.line) => problems.push({ line, kind: "field", message: `TASK ${t.task}: ${message}` });
281
+ if (t.doneWhen === undefined || t.doneWhen === "")
282
+ field("has no **DONE WHEN:** field");
283
+ const s = specs.get(t.task);
284
+ if (s.kind === "missing")
285
+ field("has neither **TEST FIRST:** nor **TEST EXCEPTION:**");
286
+ for (const line of t.testFirst?.malformed ?? [])
287
+ field("TEST FIRST entry is neither `test file` `test name` nor `n/a — {reason}`", line);
288
+ if (s.kind === "malformed" && (t.testFirst?.malformed.length ?? 0) === 0)
289
+ field("TEST FIRST names no test", t.testFirst.line);
290
+ for (const d of t.dependsOn) {
291
+ const dep = byTask.get(d);
292
+ const message = d === t.task
293
+ ? `TASK ${t.task} depends on itself`
294
+ : dep === undefined
295
+ ? `TASK ${t.task} depends on TASK ${d}, but TASK ${d} does not exist`
296
+ : dep.group > t.group
297
+ ? `TASK ${t.task} depends on TASK ${d}, which is in a later group (GROUP ${dep.group}); groups build in order`
298
+ : undefined;
299
+ if (message !== undefined)
300
+ problems.push({ line: t.line, kind: "depends", message });
301
+ }
302
+ const size = sizes.find((x) => x.task === t.task);
303
+ if (size.tests > caps.maxTestsPerTask)
304
+ problems.push({
305
+ line: t.line,
306
+ kind: "cap",
307
+ message: `TASK ${t.task} names ${size.tests} TEST FIRST tests, over the cap of ${caps.maxTestsPerTask}`,
308
+ });
309
+ if (size.files > caps.maxTestFilesPerTask)
310
+ problems.push({
311
+ line: t.line,
312
+ kind: "cap",
313
+ message: `TASK ${t.task} names ${size.files} test files, over the cap of ${caps.maxTestFilesPerTask}`,
314
+ });
315
+ for (const c of t.create)
316
+ if (!newFiles.has(path.posix.normalize(c.file)))
317
+ problems.push({
318
+ line: c.line,
319
+ kind: "inventory",
320
+ message: `TASK ${t.task}: CREATE in \`${c.file}\` has no NEW row naming it in the Reuse Inventory's File column`,
321
+ });
322
+ }
323
+ const groups = blocks.groups.map((g) => {
324
+ const tests = sizes.filter((s) => s.group === g.group).reduce((n, s) => n + s.tests, 0);
325
+ const bytes = Buffer.byteLength(lines.slice(g.line - 1, g.end).join("\n"));
326
+ return { group: g.group, title: g.title, tasks: g.tasks.length, tests, kb: kb1(bytes) };
327
+ });
328
+ for (const g of groups) {
329
+ const at = blocks.groups.find((x) => x.group === g.group).line;
330
+ if (g.tasks > caps.maxPerGroup)
331
+ problems.push({
332
+ line: at,
333
+ kind: "cap",
334
+ message: `GROUP ${g.group} has ${g.tasks} tasks, over the cap of ${caps.maxPerGroup}`,
335
+ });
336
+ if (g.tests > caps.maxTestsPerGroup)
337
+ problems.push({
338
+ line: at,
339
+ kind: "cap",
340
+ message: `GROUP ${g.group} has ${g.tests} TEST FIRST tests, over the cap of ${caps.maxTestsPerGroup}`,
341
+ });
342
+ }
343
+ problems.sort((a, b) => a.line - b.line);
344
+ return { groups, sizes, overCap, problems };
345
+ }
346
+ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
347
+ const wordIn = (body, word) => new RegExp(`(?<![\\w$])${escapeRe(word)}(?![\\w$])`).test(body);
348
+ /** The 1-based lines of `body` that are a Markdown heading reading exactly `heading`. */
349
+ const headingLines = (body, heading) => body.split(/\r?\n/).flatMap((l, i) => {
350
+ const h = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(l);
351
+ return h !== null && h[1].trim() === heading ? [i + 1] : [];
352
+ });
353
+ /** A key path's segments nested in indented `key:` lines (YAML): each one inside the block of the one before. */
354
+ function nestedKeys(body, segs) {
355
+ const lines = body.split(/\r?\n/);
356
+ const indent = (l) => /^\s*/.exec(l)[0].length;
357
+ const walk = (from, to, k, above) => {
358
+ const key = new RegExp(`^\\s*["']?${escapeRe(segs[k])}["']?\\s*:`);
359
+ for (let i = from; i < to; i++) {
360
+ const l = lines[i];
361
+ if (l.trim() === "" || indent(l) <= above || !key.test(l))
362
+ continue;
363
+ if (k === segs.length - 1)
364
+ return true;
365
+ let end = i + 1;
366
+ while (end < to && (lines[end].trim() === "" || indent(lines[end]) > indent(l)))
367
+ end++;
368
+ if (walk(i + 1, end, k + 1, indent(l)))
369
+ return true;
174
370
  }
175
- else
176
- cur += ch;
371
+ return false;
372
+ };
373
+ return walk(0, lines.length, 0, -1);
374
+ }
375
+ /** A key path as a `[table]` header holding its first segments and a `key =` line for the rest (TOML). */
376
+ function tableKey(body, segs) {
377
+ const lines = body.split(/\r?\n/);
378
+ for (let k = 1; k < segs.length; k++) {
379
+ const table = segs.slice(0, k).join(".");
380
+ const key = segs.slice(k).join(".");
381
+ const start = lines.findIndex((l) => l.trim() === `[${table}]`);
382
+ if (start < 0)
383
+ continue;
384
+ const end = lines.findIndex((l, i) => i > start && /^\s*\[/.test(l));
385
+ const keyRe = new RegExp(`^\\s*${escapeRe(key)}\\s*=`);
386
+ if (lines.slice(start + 1, end < 0 ? undefined : end).some((l) => keyRe.test(l)))
387
+ return true;
388
+ }
389
+ return false;
390
+ }
391
+ /** Config files whose dotted keys must be there as the whole key path. */
392
+ const CONFIG_EXTS = new Set([".json", ".jsonc", ".yaml", ".yml", ".toml"]);
393
+ /** Whether parsed JSON `value` holds `segs` as nested object keys. */
394
+ function jsonPath(value, segs) {
395
+ let at = value;
396
+ for (const s of segs) {
397
+ if (typeof at !== "object" || at === null || Array.isArray(at) || !Object.hasOwn(at, s))
398
+ return false;
399
+ at = at[s];
177
400
  }
178
- return [...out, cur];
401
+ return true;
179
402
  }
180
403
  /**
181
- * Each runbook task's `Test first:` line: one or more tests separated by `;` (per entry,
182
- * first backticked span = file, second = test name), `n/a — {reason}`, missing, or
183
- * malformed (an entry with one span, or no test at all). A task's text runs from its
184
- * bullet to the next bullet or heading.
404
+ * Whether config `body` of `file` holds the dotted key `bare` as the whole key path: a
405
+ * `.json` file that parses is walked as JSON; otherwise the key is written whole, nested
406
+ * in indented `key:` / `"key":` lines (YAML, indented JSON), or a `[table]` and its
407
+ * `key =` line (TOML).
185
408
  */
186
- export function readTestFirst(plan) {
409
+ function hasDottedKey(file, body, bare) {
410
+ const segs = bare.split(".");
411
+ const json = path.posix.extname(file).toLowerCase() === ".json" ? parseJson(body) : { ok: false };
412
+ if (json.ok)
413
+ return jsonPath(json.value, segs);
414
+ return wordIn(body, bare) || nestedKeys(body, segs) || tableKey(body, segs);
415
+ }
416
+ /**
417
+ * Each READ / UPDATE / DELETE line of an unticked task whose file or symbol is not
418
+ * there, read from `root`: a plain word-boundary search in the named file. `§ heading`
419
+ * must equal one of the file's heading lines; a dotted key in a config file (`CONFIG_EXTS`)
420
+ * must be there as the whole key path, and in any other file matches on its last segment;
421
+ * a file-only line checks the file exists. A line naming
422
+ * what the task itself or a task it DEPENDS ON creates is not checked: it does not
423
+ * exist yet.
424
+ */
425
+ export function planExistence(text, root) {
426
+ const blocks = parsePlanBlocks(text);
427
+ const byTask = new Map(blocks.tasks.map((t) => [t.task, t]));
187
428
  const out = [];
188
- const lines = plan.split("\n");
189
- for (let i = 0; i < lines.length; i++) {
190
- const head = TASK_LINE.exec(lines[i]);
191
- if (!head)
192
- continue;
193
- let text = lines[i];
194
- for (let j = i + 1; j < lines.length && !/^\s*(- |#)/.test(lines[j]); j++)
195
- text += ` ${lines[j]}`;
196
- const task = Number(head[1]);
197
- const at = text.indexOf(TEST_FIRST);
198
- if (at < 0) {
199
- out.push({ task, kind: "missing" });
200
- continue;
429
+ const cache = new Map();
430
+ const read = (file) => {
431
+ if (!cache.has(file)) {
432
+ const abs = path.resolve(root, file);
433
+ const inside = !path.relative(root, abs).startsWith("..");
434
+ cache.set(file, inside && fs.statSync(abs, { throwIfNoEntry: false })?.isFile()
435
+ ? fs.readFileSync(abs, "utf-8")
436
+ : null);
201
437
  }
202
- const rest = text.slice(at + TEST_FIRST.length).trim();
203
- if (/^n\/a\b/i.test(rest)) {
204
- out.push({ task, kind: "na", reason: rest.replace(/^n\/a\s*[—–-]?\s*/i, "") });
438
+ return cache.get(file);
439
+ };
440
+ for (const t of blocks.tasks) {
441
+ if (t.done)
205
442
  continue;
443
+ const created = [t, ...t.dependsOn.map((d) => byTask.get(d)).filter((d) => d !== undefined)]
444
+ .flatMap((d) => d.create)
445
+ .map((c) => ({ file: path.posix.normalize(c.file), symbol: c.symbol }));
446
+ for (const ref of [...t.read, ...t.update, ...t.delete]) {
447
+ const file = path.posix.normalize(ref.file);
448
+ if (created.some((c) => c.file === file && (c.symbol === undefined || c.symbol === ref.symbol)))
449
+ continue;
450
+ const body = read(file);
451
+ const miss = (message) => out.push({ line: ref.line, task: t.task, message });
452
+ if (body === null) {
453
+ miss(`TASK ${t.task}: \`${ref.file}\` does not exist`);
454
+ continue;
455
+ }
456
+ if (ref.symbol === undefined)
457
+ continue;
458
+ if (ref.symbol.startsWith("§")) {
459
+ const heading = ref.symbol.replace(/^§\s*/, "").trim();
460
+ if (headingLines(body, heading).length === 0)
461
+ miss(`TASK ${t.task}: no heading \`${heading}\` in \`${ref.file}\``);
462
+ continue;
463
+ }
464
+ const bare = ref.symbol.replace(/\(\)$/, "");
465
+ const key = bare.split(".").at(-1);
466
+ if (bare.includes(".") && CONFIG_EXTS.has(path.posix.extname(file).toLowerCase())) {
467
+ if (!hasDottedKey(file, body, bare))
468
+ miss(`TASK ${t.task}: \`${bare}\` is not in \`${ref.file}\``);
469
+ }
470
+ else if (!wordIn(body, key))
471
+ miss(key === bare
472
+ ? `TASK ${t.task}: \`${key}\` is not in \`${ref.file}\``
473
+ : `TASK ${t.task}: \`${key}\` (last segment of \`${ref.symbol}\`) is not in \`${ref.file}\``);
206
474
  }
207
- const entries = splitEntries(rest).map((e) => [...e.matchAll(/`([^`]+)`/g)].map((m) => m[1].trim()));
208
- const tests = entries
209
- .filter((spans) => spans.length >= 2)
210
- .map((spans) => ({ test: path.posix.normalize(spans[0]), name: spans[1] }));
211
- out.push(tests.length > 0 && !entries.some((spans) => spans.length === 1)
212
- ? { task, kind: "test", tests }
213
- : { task, kind: "malformed" });
214
475
  }
215
- return out;
476
+ return out.sort((a, b) => a.line - b.line);
477
+ }
478
+ /** True when `after` keeps every non-blank line of `before`, in order, ignoring whitespace: lines were only added. */
479
+ export function onlyAddsLines(before, after) {
480
+ const norm = (text) => text
481
+ .split("\n")
482
+ .map((l) => l.replace(/\s+/g, ""))
483
+ .filter(Boolean);
484
+ const want = norm(before);
485
+ let kept = 0;
486
+ for (const line of norm(after))
487
+ if (kept < want.length && line === want[kept])
488
+ kept++;
489
+ return kept === want.length;
216
490
  }
217
491
  /** `test` as a repo-relative path inside `top`; usage error when absolute, outside, or absent. */
218
492
  function repoTestPath(top, test) {
@@ -240,18 +514,209 @@ export const snapshotPath = (log) => `${log.replace(/\.md$/, "")}.snapshot`;
240
514
  const toplevel = (cwd) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
241
515
  /** A fence longer than any backtick run in `text`. */
242
516
  const fenceFor = (text) => "`".repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map((m) => m[0].length + 1)));
243
- /** The red rows of status.jsonl for this workflow and sub-plan, oldest first. */
244
- function redRows(file, workflow, subPlan) {
517
+ /** Gaps about when a test was seen failing; no edit made after the task's code can close one. */
518
+ export const TEST_ORDER_GAPS = new Set([
519
+ "no-red",
520
+ "late-red",
521
+ "red-mismatch",
522
+ "red-evidence-missing",
523
+ "test-changed",
524
+ ]);
525
+ /** The gap for a task whose only test field is a TEST EXCEPTION that is not honoured. */
526
+ export const EXCEPTION_REFUSED = "exception-refused";
527
+ /** The status row step plan-execute's finish writes; its commit carries the code of each task its log records DONE. */
528
+ export const PLAN_EXECUTE_STEP = "build-plan-execute";
529
+ const repoRel = (top, cwd, p) => path.relative(top, path.resolve(cwd, p)).split(path.sep).join("/");
530
+ /**
531
+ * Per task, the first plan-execute step commit whose log records the task `DONE` — the
532
+ * commit that first holds the task's code. `steps finish` writes the row then commits
533
+ * everything, so a row's commit is the first commit after its `parentSha` touching the status file.
534
+ */
535
+ function taskCodeCommits(top, cwd, file, workflow) {
536
+ const statusRel = repoRel(top, cwd, file);
537
+ const commits = new Map();
538
+ for (const r of readStatusRows(file)) {
539
+ if (r.type !== "step-done" || r.workflow !== workflow || r.step !== PLAN_EXECUTE_STEP)
540
+ continue;
541
+ const log = Array.isArray(r.artifacts) ? r.artifacts.map(String)[0] : undefined;
542
+ if (typeof r.parentSha !== "string" || log === undefined)
543
+ continue;
544
+ const range = `${r.parentSha}..HEAD`;
545
+ const commit = git(top, ["rev-list", "--reverse", "--ancestry-path", range, "--", statusRel])
546
+ ?.split("\n")
547
+ .find(Boolean);
548
+ const text = commit === undefined ? null : git(top, ["show", `${commit}:${repoRel(top, cwd, log)}`]);
549
+ if (commit === undefined || text === null)
550
+ continue;
551
+ for (const n of doneTasks(text))
552
+ if (!commits.has(n))
553
+ commits.set(n, commit);
554
+ }
555
+ return commits;
556
+ }
557
+ /** The task numbers a plan-execute log records `DONE — TASK N` for, in log order. */
558
+ export function doneTasks(log) {
559
+ return [...log.matchAll(/^DONE\s*[—–-]+\s*TASK\s+(\d+)\b/gim)].map((m) => Number(m[1]));
560
+ }
561
+ /**
562
+ * Why a task's `TEST EXCEPTION` lines do not count, or null when they do: every
563
+ * line committed, and last changed by a commit that does not write the status file.
564
+ * Every workflow step commit writes it, so a line riding one is refused; agents are
565
+ * barred from committing, so the remaining commits are human-made.
566
+ */
567
+ function exceptionRefusal(top, plan, lines, statusRel) {
568
+ const blame = git(top, ["blame", "--porcelain", "-L", `${lines[0]},${lines.at(-1)}`, "--", plan]);
569
+ if (blame === null)
570
+ return "the plan file is not committed";
571
+ const shas = new Set([...blame.matchAll(/^([0-9a-f]{40}) \d+ \d+/gm)].map((m) => m[1]));
572
+ if ([...shas].some((s) => /^0+$/.test(s)))
573
+ return "the line is not committed — a human commits it before the build re-runs";
574
+ for (const sha of shas) {
575
+ const files = git(top, ["show", "--name-only", "--format=", sha])?.split("\n") ?? [];
576
+ if (files.includes(statusRel))
577
+ return `last changed by ${sha.slice(0, 7)}, a workflow step commit (it also writes \`${statusRel}\`) — commit the line in a commit that does not touch it`;
578
+ }
579
+ return null;
580
+ }
581
+ const withoutExt = (p) => p.replace(/\.[^./]*$/, "");
582
+ /**
583
+ * Whether a grep hit for `stem` in `file` refers to something other than the files of
584
+ * `targets` (repo-relative): false for a hit inside a target, or a line whose every
585
+ * path-like mention of `stem` resolves to a target. A `./` or `../` path resolves
586
+ * against `file`'s folder; any other path with a `/` matches a target ending in it.
587
+ */
588
+ function namesOldPath(stem, targets) {
589
+ const bare = targets.map(withoutExt);
590
+ const isTarget = (token, file) => {
591
+ const t = withoutExt(token);
592
+ if (t.startsWith("./") || t.startsWith("../"))
593
+ return bare.includes(path.posix.join(path.posix.dirname(file), t));
594
+ return t.includes("/") && bare.some((b) => b === t || b.endsWith(`/${t}`));
595
+ };
596
+ return (file, text) => {
597
+ if (targets.includes(file))
598
+ return false;
599
+ const mentions = text
600
+ .split(/[^\w./@-]+/)
601
+ .filter((tok) => path.posix.basename(withoutExt(tok)) === stem);
602
+ return mentions.length === 0 || mentions.some((tok) => !isTarget(tok, file));
603
+ };
604
+ }
605
+ /** The gap for a DELETE line whose file or symbol the tree still holds or refers to. */
606
+ export const DELETE_STILL_REFERENCED = "delete-still-referenced";
607
+ /**
608
+ * One `delete-still-referenced` gap per DELETE line of `tasks` the tree at `top` still
609
+ * holds: a file-only line whose file exists, or whose file name (no extension) a tracked
610
+ * or untracked file names as a word; a symbol (a dotted key's last segment) named as a
611
+ * word; a `§ heading` written as `§ heading`, or still a heading of its file. The plan
612
+ * file and the folder it sits in are not searched. A line naming what a task of
613
+ * `planTasks` CREATEs is a move, not checked. A file-only line whose file name a CREATE
614
+ * of `planTasks` reuses is a file move: the created file, and lines whose every mention
615
+ * of the name is a path to the created file, are not references. A word search hits
616
+ * other things of the same name, so this is a gap for verify to judge, never a refusal.
617
+ */
618
+ function deleteGaps(top, planRel, tasks, planTasks) {
619
+ const created = planTasks.flatMap((t) => t.create);
620
+ const planDir = path.posix.dirname(planRel);
621
+ const excludes = [`:(exclude)${planRel}`, ...(planDir === "." ? [] : [`:(exclude)${planDir}`])];
622
+ const grep = (term, word, keep) => {
623
+ const res = spawnSync("git", [
624
+ "grep",
625
+ "-n",
626
+ "-z",
627
+ "-I",
628
+ "--untracked",
629
+ ...(word ? ["-w"] : []),
630
+ "-F",
631
+ "-e",
632
+ term,
633
+ "--",
634
+ ".",
635
+ ...excludes,
636
+ ], { cwd: top, encoding: "utf-8" });
637
+ if (res.status === 1)
638
+ return { hits: [] };
639
+ if (res.status !== 0)
640
+ return {
641
+ failed: `git grep exited ${res.status ?? res.signal}: ${(res.stderr ?? "").trim()}`,
642
+ };
643
+ const hits = res.stdout
644
+ .split("\n")
645
+ .filter(Boolean)
646
+ .map((l) => l.split("\0"))
647
+ .filter(([file, , text]) => keep === undefined || keep(file, text ?? ""))
648
+ .map((parts) => parts.slice(0, 2).join(":"));
649
+ return { hits };
650
+ };
651
+ const listed = (hits) => hits
652
+ .slice(0, 5)
653
+ .map((h) => `\`${h}\``)
654
+ .join(", ") + (hits.length > 5 ? `, and ${hits.length - 5} more` : "");
655
+ const gaps = [];
656
+ for (const t of tasks)
657
+ for (const ref of t.delete) {
658
+ const file = path.posix.normalize(ref.file);
659
+ const moved = created.some((c) => ref.symbol === undefined ? path.posix.normalize(c.file) === file : c.symbol === ref.symbol);
660
+ if (moved)
661
+ continue;
662
+ const movedTo = ref.symbol === undefined
663
+ ? created
664
+ .filter((c) => c.symbol === undefined &&
665
+ path.posix.basename(path.posix.normalize(c.file)) === path.posix.basename(file))
666
+ .map((c) => path.posix.normalize(c.file))
667
+ : [];
668
+ const gap = (detail) => gaps.push({ task: t.task, kind: DELETE_STILL_REFERENCED, detail });
669
+ const abs = path.join(top, file);
670
+ const exists = fs.statSync(abs, { throwIfNoEntry: false })?.isFile() === true;
671
+ let what;
672
+ let found;
673
+ if (ref.symbol === undefined) {
674
+ if (exists) {
675
+ gap(`DELETE \`${ref.file}\`: the file still exists`);
676
+ continue;
677
+ }
678
+ const stem = path.posix.basename(file).replace(/\.[^.]*$/, "");
679
+ what = `DELETE \`${ref.file}\` is still referenced as \`${stem}\``;
680
+ found = grep(stem, true, movedTo.length === 0 ? undefined : namesOldPath(stem, movedTo));
681
+ }
682
+ else if (ref.symbol.startsWith("§")) {
683
+ const heading = ref.symbol.replace(/^§\s*/, "").trim();
684
+ what = `DELETE ${ref.symbol} in \`${ref.file}\` is still referenced`;
685
+ found = grep(`§ ${heading}`, false);
686
+ if (exists && found.hits !== undefined)
687
+ found.hits.push(...headingLines(fs.readFileSync(abs, "utf-8"), heading).map((n) => `${file}:${n}`));
688
+ }
689
+ else {
690
+ const bare = ref.symbol.replace(/\(\)$/, "");
691
+ what = `DELETE \`${ref.symbol}\` in \`${ref.file}\` is still referenced`;
692
+ found = grep(bare.split(".").at(-1), true);
693
+ }
694
+ if (found.failed !== undefined)
695
+ gap(`${what.replace(/ is still referenced.*$/, "")}: references not checked — ${found.failed}`);
696
+ else if (found.hits.length > 0)
697
+ gap(`${what}: ${listed([...new Set(found.hits)].sort())}`);
698
+ }
699
+ return gaps;
700
+ }
701
+ /**
702
+ * The red rows of status.jsonl for this workflow, oldest first. Task numbers are unique
703
+ * across the plan, so a red matches its task by number whatever group recorded it.
704
+ */
705
+ export function redRows(file, workflow) {
245
706
  return readStatusRows(file).filter((r) => {
246
707
  const row = r;
247
- return (row.type === "step-done" &&
248
- row.workflow === workflow &&
249
- row.step === RED_STEP &&
250
- (subPlan === undefined || row.subPlan === subPlan));
708
+ return row.type === "step-done" && row.workflow === workflow && row.step === RED_STEP;
251
709
  });
252
710
  }
253
711
  function writeAuditReport(log, o) {
254
- const out = [`Enforced: ${o.enforced}`, `Gaps: ${o.gaps.length}`, "", "<!-- verdict:end -->", ""];
712
+ const out = [
713
+ `Enforced: ${o.enforced}`,
714
+ `Gaps: ${o.gaps.length}`,
715
+ `Test order only: ${o.testOrderOnly}`,
716
+ "",
717
+ "<!-- verdict:end -->",
718
+ "",
719
+ ];
255
720
  out.push("# Test-First Audit", "");
256
721
  if (o.plan)
257
722
  out.push(`Plan: \`${o.plan}\``, "");
@@ -267,7 +732,17 @@ function writeAuditReport(log, o) {
267
732
  if (o.gaps.length === 0)
268
733
  out.push("None.");
269
734
  for (const g of o.gaps)
270
- out.push(`- Task ${g.task} \`${g.kind}\` — ${g.detail}`);
735
+ out.push(`- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${g.detail}`);
736
+ if (o.exceptions.length > 0)
737
+ out.push("", "## Test exceptions", "");
738
+ for (const e of o.exceptions)
739
+ out.push(e.refusal === null
740
+ ? `- Task ${e.task} — honoured; cleared ${e.cleared.length > 0 ? e.cleared.join(", ") : "nothing"}`
741
+ : `- Task ${e.task} — not honoured: ${e.refusal}`);
742
+ if (o.lateUnchecked.length > 0)
743
+ out.push("", "## Late-red check", "");
744
+ for (const task of o.lateUnchecked)
745
+ out.push(`- Task ${task} — not checked: no plan-execute step commit's log records \`DONE — TASK ${task}\`, so when its code landed is unknown`);
271
746
  for (const d of o.diffs) {
272
747
  const fence = fenceFor(d.diff);
273
748
  out.push("", `## Diff since red — Task ${d.task} \`${d.test}\``, "", `${fence}diff`, d.diff, fence);
@@ -304,25 +779,44 @@ export const testsCommand = {
304
779
  type: "string",
305
780
  help: `lines of the log echoed to stderr afterwards (default ${DEFAULT_TAIL}; 0 for none)`,
306
781
  },
782
+ {
783
+ name: "artifact",
784
+ type: "string",
785
+ help: "copy the log here, trim the copy (debug-evidence) and record the clamp; needs --fid and --step",
786
+ },
787
+ { name: "fid", type: "string", help: "--artifact: feature id, for the clamp log" },
788
+ { name: "step", type: "string", help: "--artifact: step name, for the clamp log" },
789
+ { name: "attempt", type: "string", help: "--artifact: attempt, for the clamp log" },
307
790
  ],
308
791
  output: {
309
792
  verdict: "PASS | FAIL (null when the gate could not run)",
310
793
  exitCode: "the gate's exit code",
311
794
  gate: "the script that ran",
312
795
  scope: "the command that ran, as status rows record it",
313
- failures: "0 on PASS; null otherwise — count failing suites from the log",
314
- log: "where the full output was saved (as given)",
796
+ failures: `0 on PASS; on FAIL the failing + erroring test cases in the JUnit reports, or null when no report counts any (unknown, never 0)`,
797
+ reports: `{log}.reports — emptied before the run and passed to the gate as $${REPORT_DIR_ENV}`,
798
+ log: "where the full output was saved (as given); the untouched original",
315
799
  logBytes: "size of the saved output",
800
+ artifact: "--artifact as given, else null",
801
+ clamp: "the artifact's clamp record (raw = the log, source = scope), else null",
316
802
  },
803
+ textOmit: ["clamp"],
317
804
  exitCodes: {
318
805
  [EXIT_NO_GATE]: "no candidate gate is declared in package.json",
319
806
  [EXIT_COULD_NOT_RUN]: "the gate could not run (exit 126 / 127): not a test failure",
807
+ [EXIT_ARTIFACT_STEP]: "--artifact could not be written, trimmed or recorded",
320
808
  },
321
809
  run: (ctx) => {
322
810
  const candidates = ctx.flags.gate;
323
811
  const logArg = String(ctx.flags.log);
324
812
  if (logArg === "")
325
813
  throw new CommandError(EXIT.USAGE, "--log must be non-empty");
814
+ const artifact = str(ctx.flags.artifact);
815
+ const fid = str(ctx.flags.fid);
816
+ const step = str(ctx.flags.step);
817
+ const attempt = positiveInt(ctx.flags.attempt, "attempt");
818
+ if (artifact !== undefined && (!fid || !step))
819
+ throw new CommandError(EXIT.USAGE, "--artifact needs --fid and --step");
326
820
  const tailRaw = str(ctx.flags.tail) ?? String(DEFAULT_TAIL);
327
821
  if (!/^[0-9]+$/.test(tailRaw)) {
328
822
  throw new CommandError(EXIT.USAGE, `--tail must be a non-negative integer, got "${tailRaw}"`);
@@ -340,21 +834,60 @@ export const testsCommand = {
340
834
  }
341
835
  const scope = gateScope(gate);
342
836
  const log = path.resolve(ctx.cwd, logArg);
837
+ const reports = freshReportDir(log);
343
838
  ctx.log(`running ${scope} — full output in ${logArg}`);
344
- const exitCode = runToLog(scriptCommand(gate), top, log);
839
+ const fetchedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
840
+ const exitCode = runToLog(scriptCommand(gate), top, log, { [REPORT_DIR_ENV]: reports });
345
841
  for (const line of Number(tailRaw) > 0 ? tailLines(log, Number(tailRaw)) : [])
346
842
  ctx.log(line);
347
843
  const couldNotRun = COULD_NOT_RUN_EXIT_CODES.has(exitCode);
348
844
  const verdict = couldNotRun ? null : exitCode === 0 ? "PASS" : "FAIL";
845
+ const counted = countReportFailures(reports);
846
+ if (counted === null)
847
+ ctx.log(NO_REPORT_HINT);
848
+ else if (verdict === "FAIL" && counted === 0)
849
+ ctx.log(`the JUnit reports in $${REPORT_DIR_ENV} hold no failing case — the gate failed outside its reported tests; failures unknown`);
850
+ const failures = verdict === "PASS" ? 0 : counted !== null && counted > 0 ? counted : null;
851
+ let clamp = null;
852
+ let artifactFailed = null;
853
+ if (artifact !== undefined) {
854
+ try {
855
+ const out = path.resolve(ctx.cwd, artifact);
856
+ fs.mkdirSync(path.dirname(out), { recursive: true });
857
+ fs.copyFileSync(log, out);
858
+ const clampLog = clampLogPath(ctx.cwd, fid, step, attempt);
859
+ fs.mkdirSync(path.dirname(clampLog), { recursive: true });
860
+ fs.writeFileSync(clampLog, "");
861
+ clamp = clampFile(out, "debug-evidence", artifact, {
862
+ rawDir: null,
863
+ source: scope,
864
+ fetchedAt,
865
+ original: log,
866
+ });
867
+ appendRecord(clampLog, clamp);
868
+ }
869
+ catch (err) {
870
+ // The verdict stands; the step's artifact is what failed.
871
+ clamp = null;
872
+ artifactFailed = err.message;
873
+ }
874
+ }
349
875
  ctx.emit({
350
876
  verdict,
351
877
  exitCode,
352
878
  gate,
353
879
  scope,
354
- failures: verdict === "PASS" ? 0 : null,
880
+ failures,
881
+ reports: `${logArg}.reports`,
355
882
  log: logArg,
356
883
  logBytes: fs.statSync(log).size,
884
+ artifact: artifact ?? null,
885
+ clamp,
357
886
  });
887
+ if (artifactFailed !== null) {
888
+ ctx.log(`--artifact ${artifact}: ${artifactFailed}`);
889
+ return EXIT_ARTIFACT_STEP;
890
+ }
358
891
  if (couldNotRun) {
359
892
  ctx.log(`${scope} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no tests executed; this is not a FAIL verdict`);
360
893
  return EXIT_COULD_NOT_RUN;
@@ -368,7 +901,7 @@ export const testsCommand = {
368
901
  flags: [
369
902
  FILE_FLAG,
370
903
  WORKFLOW_FLAG,
371
- SUB_PLAN_FLAG,
904
+ GROUP_FLAG,
372
905
  {
373
906
  name: "task",
374
907
  type: "string",
@@ -409,7 +942,7 @@ export const testsCommand = {
409
942
  },
410
943
  run: (ctx) => {
411
944
  const workflow = String(ctx.flags.workflow);
412
- const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
945
+ const group = positiveInt(ctx.flags.group, "group");
413
946
  const task = positiveInt(ctx.flags.task, "task");
414
947
  const name = String(ctx.flags.name).trim();
415
948
  if (name === "")
@@ -426,7 +959,7 @@ export const testsCommand = {
426
959
  const blob = git(top, ["hash-object", "--", test]);
427
960
  const status = statusFile(ctx);
428
961
  const prior = fs.existsSync(status)
429
- ? redRows(status, workflow, subPlan)
962
+ ? redRows(status, workflow)
430
963
  .reverse()
431
964
  .find((r) => r.task === task && r.test === test && r.testName === name)
432
965
  : undefined;
@@ -461,7 +994,7 @@ export const testsCommand = {
461
994
  file: statusFile(ctx),
462
995
  workflow,
463
996
  step: RED_STEP,
464
- subPlan,
997
+ group,
465
998
  artifacts: [path.relative(ctx.cwd, log), path.relative(ctx.cwd, snapshot)],
466
999
  extras: {
467
1000
  task,
@@ -479,11 +1012,11 @@ export const testsCommand = {
479
1012
  },
480
1013
  },
481
1014
  green: {
482
- summary: "Audit a sub-plan's test-first evidence (a red per planned test, the test unchanged since, the named test passing now); exit 0 no gaps, 1 gaps.",
1015
+ summary: "Audit a plan's test-first evidence (a red per TEST FIRST test recorded before the task's code commit, the test only added to since, the named test passing now); exit 0 no gaps, 1 gaps or a plan with no task markers.",
483
1016
  flags: [
484
1017
  FILE_FLAG,
485
1018
  WORKFLOW_FLAG,
486
- SUB_PLAN_FLAG,
1019
+ { ...GROUP_FLAG, help: "audit only this plan group's tasks (positive integer)" },
487
1020
  {
488
1021
  name: "plan",
489
1022
  type: "string",
@@ -491,11 +1024,6 @@ export const testsCommand = {
491
1024
  repeatable: true,
492
1025
  help: "candidate plan file; the first that exists is audited",
493
1026
  },
494
- {
495
- name: "brief",
496
- type: "string",
497
- help: "the build input, audited when no plan file exists and it carries `**Task N:**` lines with `Test first:`",
498
- },
499
1027
  {
500
1028
  name: "log",
501
1029
  type: "string",
@@ -504,10 +1032,12 @@ export const testsCommand = {
504
1032
  },
505
1033
  ],
506
1034
  output: {
507
- enforced: "false when there is nothing to audit (reason says why)",
1035
+ enforced: "false when the audit could not run: no plan file, a plan with no task markers (exit 1), or the test-file script undeclared (exit 0)",
508
1036
  reason: "why test-first is not enforced",
509
- plan: "the plan file audited (the brief when no plan file exists and it carries Test first lines)",
510
- gaps: "[{task, kind, detail}]: no-test-first | test-first-malformed | no-red | red-mismatch | red-evidence-missing | test-changed | not-green",
1037
+ plan: "the plan file audited",
1038
+ gaps: "[{task, kind, detail}]: no-test-first | test-first-malformed | test-first-unread (task null: a plan-level format problem) | no-red | late-red | red-mismatch | red-evidence-missing | test-changed | not-green | exception-refused (a task whose only test field is a TEST EXCEPTION not honoured) | delete-still-referenced (a DELETE line's file still exists, or its name is still found in the tree)",
1039
+ testOrderOnly: "true when there are gaps and every one is a test-order gap (no-red | late-red | red-mismatch | red-evidence-missing | test-changed)",
1040
+ lateRedUnchecked: "tasks with a red but no plan-execute step commit whose log records `DONE — TASK N`: the late-red check could not run for them",
511
1041
  log: "where the report was written (as given)",
512
1042
  },
513
1043
  exitCodes: {
@@ -515,39 +1045,65 @@ export const testsCommand = {
515
1045
  },
516
1046
  run: (ctx) => {
517
1047
  const workflow = String(ctx.flags.workflow);
518
- const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
1048
+ const group = positiveInt(ctx.flags.group, "group");
519
1049
  const logArg = String(ctx.flags.log);
520
1050
  if (logArg === "")
521
1051
  throw new CommandError(EXIT.USAGE, "--log must be non-empty");
522
1052
  const log = path.resolve(ctx.cwd, logArg);
523
1053
  const top = toplevel(ctx.cwd);
524
1054
  const exists = (p) => fs.existsSync(path.resolve(ctx.cwd, p));
525
- const planFile = ctx.flags.plan.find(exists);
526
- const briefArg = str(ctx.flags.brief);
527
- const brief = planFile === undefined && briefArg !== undefined && exists(briefArg)
528
- ? briefArg
529
- : undefined;
530
- const plan = planFile ?? brief;
531
- const specs = plan
532
- ? readTestFirst(fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8"))
533
- : [];
534
- const reason = plan === undefined
535
- ? "no plan file — the build runs from its brief"
536
- : !specs.some((s) => s.kind !== "missing")
537
- ? brief !== undefined
538
- ? "no plan file, and the brief has no `**Task N:**` lines with `Test first:`"
539
- : "the plan has no `Test first:` lines"
540
- : resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
541
- ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
542
- : undefined;
543
- const empty = { rows: [], gaps: [], diffs: [], outputs: [] };
1055
+ const plan = ctx.flags.plan.find(exists);
1056
+ const planText = plan ? fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8") : "";
1057
+ const parsed = parsePlanBlocks(planText);
1058
+ const specs = readTestFirst(planText, group);
1059
+ // A plan with no task markers is an old-format plan: nothing it says can be audited,
1060
+ // and passing it would let its tests go unchecked.
1061
+ const refusal = plan === undefined
1062
+ ? `no plan file; ${NO_MARKERS_REASON}`
1063
+ : parsed.tasks.length === 0
1064
+ ? parsed.fenceOpen === undefined
1065
+ ? NO_MARKERS_REASON
1066
+ : fenceNeverClosed(parsed.fenceOpen)
1067
+ : undefined;
1068
+ if (refusal === undefined && group !== undefined) {
1069
+ const g = parsed.groups.find((x) => x.group === group);
1070
+ if (g === undefined)
1071
+ throw new CommandError(EXIT.USAGE, `the plan has no GROUP ${group}`);
1072
+ if (g.tasks.length === 0)
1073
+ throw new CommandError(EXIT.USAGE, `GROUP ${group} has no tasks; nothing to audit`);
1074
+ }
1075
+ const reason = refusal ??
1076
+ (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
1077
+ ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
1078
+ : undefined);
1079
+ const empty = {
1080
+ rows: [],
1081
+ gaps: [],
1082
+ testOrderOnly: false,
1083
+ exceptions: [],
1084
+ lateUnchecked: [],
1085
+ diffs: [],
1086
+ outputs: [],
1087
+ };
544
1088
  if (reason !== undefined) {
545
1089
  writeAuditReport(log, { enforced: false, reason, plan, ...empty });
546
- ctx.emit({ enforced: false, reason, plan: plan ?? null, gaps: [], log: logArg });
1090
+ ctx.emit({
1091
+ enforced: false,
1092
+ reason,
1093
+ plan: plan ?? null,
1094
+ gaps: [],
1095
+ testOrderOnly: false,
1096
+ lateRedUnchecked: [],
1097
+ log: logArg,
1098
+ });
547
1099
  ctx.log(`test-first not enforced: ${reason}`);
548
- return EXIT.OK;
1100
+ return refusal === undefined ? EXIT.OK : EXIT.NO;
549
1101
  }
550
- const reds = redRows(statusFile(ctx), workflow, subPlan);
1102
+ const reds = redRows(statusFile(ctx), workflow);
1103
+ const statusRel = repoRel(top, ctx.cwd, statusFile(ctx));
1104
+ const codeCommits = taskCodeCommits(top, ctx.cwd, statusFile(ctx), workflow);
1105
+ const exceptions = [];
1106
+ const lateUnchecked = new Set();
551
1107
  const gaps = [];
552
1108
  const rows = [];
553
1109
  const diffs = [];
@@ -572,18 +1128,44 @@ export const testsCommand = {
572
1128
  return run;
573
1129
  };
574
1130
  for (const s of specs) {
575
- if (s.kind === "na")
1131
+ if (s.kind === "na") {
1132
+ const block = parsed.tasks.find((t) => t.task === s.task);
1133
+ if (block.testFirst !== undefined || block.testException === undefined)
1134
+ continue;
1135
+ const refused = exceptionRefusal(top, repoRel(top, ctx.cwd, plan), block.testException.lines, statusRel);
1136
+ exceptions.push({
1137
+ task: s.task,
1138
+ refusal: refused,
1139
+ cleared: refused === null ? ["the task's `TEST FIRST` check"] : [],
1140
+ });
1141
+ if (refused !== null)
1142
+ gaps.push({
1143
+ task: s.task,
1144
+ kind: EXCEPTION_REFUSED,
1145
+ detail: `the task's only test field is a \`**TEST EXCEPTION:**\`, not honoured: ${refused}`,
1146
+ });
576
1147
  continue;
1148
+ }
577
1149
  if (s.kind !== "test") {
578
1150
  gaps.push({
579
1151
  task: s.task,
580
1152
  kind: s.kind === "missing" ? "no-test-first" : "test-first-malformed",
581
1153
  detail: s.kind === "missing"
582
- ? "the task has no `Test first:` line"
583
- : "`Test first:` is neither `n/a — {reason}` nor `;`-separated entries of a backticked test file and test name",
1154
+ ? "the task has neither a `**TEST FIRST:**` nor a `**TEST EXCEPTION:**` field"
1155
+ : "`**TEST FIRST:**` is neither `n/a — {reason}` nor one sub-bullet per test naming a backticked test file and test name",
584
1156
  });
585
1157
  continue;
586
1158
  }
1159
+ const excepted = s.exception;
1160
+ const exception = excepted === undefined
1161
+ ? undefined
1162
+ : {
1163
+ task: s.task,
1164
+ refusal: exceptionRefusal(top, repoRel(top, ctx.cwd, plan), excepted.lines, statusRel),
1165
+ cleared: [],
1166
+ };
1167
+ if (exception !== undefined)
1168
+ exceptions.push(exception);
587
1169
  const taskReds = reds.filter((r) => r.task === s.task);
588
1170
  const planned = (r) => s.tests.some((t) => t.test === r.test && t.name === r.testName);
589
1171
  for (const t of s.tests) {
@@ -595,6 +1177,16 @@ export const testsCommand = {
595
1177
  green: "—",
596
1178
  };
597
1179
  rows.push(row);
1180
+ const clearing = exception?.refusal === null &&
1181
+ excepted.tests.some((e) => e.test === t.test && e.name === t.name)
1182
+ ? exception
1183
+ : undefined;
1184
+ const gap = (kind, detail) => {
1185
+ if (clearing !== undefined && TEST_ORDER_GAPS.has(kind))
1186
+ clearing.cleared.push(`\`${kind}\` for \`${t.test}\` "${t.name}"`);
1187
+ else
1188
+ gaps.push({ task: s.task, kind, detail });
1189
+ };
598
1190
  const red = [...taskReds]
599
1191
  .reverse()
600
1192
  .find((r) => r.test === t.test && r.testName === t.name);
@@ -614,21 +1206,21 @@ export const testsCommand = {
614
1206
  }
615
1207
  recorded.push(`\`${rTest}\` "${rName}" (${now})`);
616
1208
  }
617
- gaps.push({
618
- task: s.task,
619
- kind: "red-mismatch",
620
- detail: `no red for \`${t.test}\` "${t.name}"; reds recorded for ${recorded.join(", ")}`,
621
- });
1209
+ gap("red-mismatch", `no red for \`${t.test}\` "${t.name}"; reds recorded for ${recorded.join(", ")}`);
622
1210
  }
623
1211
  else if (red === undefined) {
624
- gaps.push({
625
- task: s.task,
626
- kind: "no-red",
627
- detail: `no red recorded for "${t.name}" — the test was never seen failing before the code`,
628
- });
1212
+ gap("no-red", `no red recorded for "${t.name}" — the test was never seen failing before the code`);
629
1213
  }
630
1214
  else {
631
1215
  row.red = `recorded ${String(red.at)}`;
1216
+ const code = codeCommits.get(s.task);
1217
+ const on = typeof red.parentSha === "string" ? red.parentSha : undefined;
1218
+ if (code === undefined || on === undefined)
1219
+ lateUnchecked.add(s.task);
1220
+ else if (runGit(top, ["merge-base", "--is-ancestor", code, on]).ok) {
1221
+ row.red = `late — ${row.red}`;
1222
+ gap("late-red", `the red for "${t.name}" was recorded on ${on.slice(0, 7)}, on or after ${code.slice(0, 7)}, the first commit whose plan-execute log records TASK ${s.task} DONE — the task's code already existed`);
1223
+ }
632
1224
  const snap = (Array.isArray(red.artifacts) ? red.artifacts : [])
633
1225
  .map(String)
634
1226
  .find((a) => a.endsWith(".snapshot"));
@@ -636,40 +1228,33 @@ export const testsCommand = {
636
1228
  const testAbs = path.join(top, t.test);
637
1229
  if (snapAbs === undefined || !fs.existsSync(snapAbs)) {
638
1230
  row.changed = "unknown";
639
- gaps.push({
640
- task: s.task,
641
- kind: "red-evidence-missing",
642
- detail: `the red's test snapshot ${snap ?? "(none recorded)"} is missing`,
643
- });
1231
+ gap("red-evidence-missing", `the red's test snapshot ${snap ?? "(none recorded)"} is missing`);
644
1232
  }
645
1233
  else if (!fs.existsSync(testAbs)) {
646
1234
  row.changed = "deleted";
647
- gaps.push({
648
- task: s.task,
649
- kind: "test-changed",
650
- detail: `\`${t.test}\` no longer exists`,
651
- });
1235
+ gap("test-changed", `\`${t.test}\` no longer exists`);
652
1236
  }
653
1237
  else if (!fs.readFileSync(snapAbs).equals(fs.readFileSync(testAbs))) {
654
- row.changed = "yes";
655
- gaps.push({
656
- task: s.task,
657
- kind: "test-changed",
658
- detail: `\`${t.test}\` differs from its red snapshot for "${t.name}" (diff below)`,
659
- });
660
- const diff = spawnSync("git", ["diff", "--no-index", "--no-color", "--", path.relative(top, snapAbs), t.test], { cwd: top, encoding: "utf-8" });
661
- diffs.push({ task: s.task, test: t.test, diff: diff.stdout.trimEnd() });
1238
+ const added = onlyAddsLines(fs.readFileSync(snapAbs, "utf-8"), fs.readFileSync(testAbs, "utf-8"));
1239
+ row.changed = added ? "added lines only" : "yes";
1240
+ if (!added)
1241
+ gap("test-changed", `\`${t.test}\` differs from its red snapshot for "${t.name}" (diff below)`);
1242
+ const diff = runGit(top, [
1243
+ "diff",
1244
+ "--no-index",
1245
+ "--no-color",
1246
+ "--",
1247
+ path.relative(top, snapAbs),
1248
+ t.test,
1249
+ ]);
1250
+ diffs.push({ task: s.task, test: t.test, diff: diff.stdout });
662
1251
  }
663
1252
  else
664
1253
  row.changed = "no";
665
1254
  }
666
1255
  if (!fs.existsSync(path.join(top, t.test))) {
667
1256
  row.green = "file missing";
668
- gaps.push({
669
- task: s.task,
670
- kind: "not-green",
671
- detail: `\`${t.test}\` does not exist`,
672
- });
1257
+ gap("not-green", `\`${t.test}\` does not exist`);
673
1258
  continue;
674
1259
  }
675
1260
  const green = greenRun(t.test);
@@ -678,17 +1263,130 @@ export const testsCommand = {
678
1263
  const why = judgeGreen(green.cases, t.name);
679
1264
  row.green = why === null ? "passed" : "not passed";
680
1265
  if (why !== null) {
681
- gaps.push({ task: s.task, kind: "not-green", detail: why });
1266
+ gap("not-green", why);
682
1267
  if (!outputs.some((o) => o.test === t.test))
683
1268
  outputs.push({ test: t.test, tail: green.tail });
684
1269
  }
685
1270
  }
686
1271
  }
687
- writeAuditReport(log, { enforced: true, plan, rows, gaps, diffs, outputs });
688
- ctx.emit({ enforced: true, plan, gaps, log: logArg });
1272
+ gaps.push(...deleteGaps(top, repoRel(top, ctx.cwd, plan), parsed.tasks.filter((t) => group === undefined || t.group === group), parsed.tasks));
1273
+ for (const e of parsed.errors)
1274
+ gaps.push({
1275
+ task: null,
1276
+ kind: "test-first-unread",
1277
+ detail: `\`${plan}:${e.line}\` ${e.message} — tests there were not audited; the plan's blocks need fixing`,
1278
+ });
1279
+ const testOrderOnly = gaps.length > 0 && gaps.every((g) => TEST_ORDER_GAPS.has(g.kind));
1280
+ writeAuditReport(log, {
1281
+ enforced: true,
1282
+ plan,
1283
+ rows,
1284
+ gaps,
1285
+ testOrderOnly,
1286
+ exceptions,
1287
+ lateUnchecked: [...lateUnchecked].sort((a, b) => a - b),
1288
+ diffs,
1289
+ outputs,
1290
+ });
1291
+ ctx.emit({
1292
+ enforced: true,
1293
+ plan,
1294
+ gaps,
1295
+ testOrderOnly,
1296
+ lateRedUnchecked: [...lateUnchecked].sort((a, b) => a - b),
1297
+ log: logArg,
1298
+ });
689
1299
  ctx.log(`test-first audit: ${gaps.length} gap(s) — report in ${logArg}`);
690
1300
  return gaps.length === 0 ? EXIT.OK : EXIT.NO;
691
1301
  },
692
1302
  },
1303
+ "plan-check": {
1304
+ summary: `Check a plan's group and task blocks: the block format, DONE WHEN and TEST FIRST on every task, DEPENDS ON order, the caps from package.json \`bkit.workflows.tasks\` (defaults: ${capsText(CONFIG_DEFAULTS.tasks)}), a Reuse Inventory NEW row per CREATE file, and that each READ / UPDATE / DELETE file and symbol exists; exit 0 no problems, 1 refused.`,
1305
+ flags: [
1306
+ {
1307
+ name: "plan",
1308
+ type: "string",
1309
+ required: true,
1310
+ help: "the plan file checked",
1311
+ },
1312
+ {
1313
+ name: "existence",
1314
+ type: "string",
1315
+ help: "refuse (default): a missing READ / UPDATE / DELETE file or symbol refuses the plan; report: it is listed only",
1316
+ },
1317
+ {
1318
+ name: "log",
1319
+ type: "string",
1320
+ required: true,
1321
+ help: "file the report is written to, `Problems:` header first (directories are created)",
1322
+ },
1323
+ ],
1324
+ output: {
1325
+ plan: "the plan file checked (as given)",
1326
+ groups: "[{group, title, tasks, tests, kb}]: each group's tasks, planned TEST FIRST tests and size",
1327
+ tasks: "[{task, group, tests, files}]: each task's planned tests and distinct test files",
1328
+ problems: "[{line, kind, message}]: format | stray | field | depends | cap | inventory | markers — each refuses the plan",
1329
+ existence: "[{line, task, message}]: READ / UPDATE / DELETE files or symbols not found; refuses only with --existence=refuse",
1330
+ log: "where the report was written (as given)",
1331
+ },
1332
+ run: (ctx) => {
1333
+ const logArg = String(ctx.flags.log);
1334
+ if (logArg === "")
1335
+ throw new CommandError(EXIT.USAGE, "--log must be non-empty");
1336
+ const existenceArg = str(ctx.flags.existence) ?? "refuse";
1337
+ if (existenceArg !== "refuse" && existenceArg !== "report")
1338
+ throw new CommandError(EXIT.USAGE, `--existence must be refuse or report, got "${existenceArg}"`);
1339
+ const plan = String(ctx.flags.plan);
1340
+ const planAbs = path.resolve(ctx.cwd, plan);
1341
+ if (!fs.statSync(planAbs, { throwIfNoEntry: false })?.isFile())
1342
+ throw new CommandError(EXIT.USAGE, `--plan ${plan} does not exist`);
1343
+ const text = fs.readFileSync(planAbs, "utf-8");
1344
+ const caps = planCaps(ctx.cwd);
1345
+ const { groups, sizes, problems } = checkPlanText(text, caps);
1346
+ const existence = planExistence(text, toplevel(ctx.cwd));
1347
+ const refused = problems.length > 0 || (existenceArg === "refuse" && existence.length > 0);
1348
+ const out = [
1349
+ `Problems: ${problems.length}`,
1350
+ `Existence: ${existence.length}`,
1351
+ "",
1352
+ "<!-- verdict:end -->",
1353
+ "",
1354
+ "# Plan Check",
1355
+ "",
1356
+ `Plan: \`${plan}\`. Caps: ${capsText(caps)}.`,
1357
+ "",
1358
+ "## Groups",
1359
+ "",
1360
+ ];
1361
+ if (groups.length === 0)
1362
+ out.push("No group blocks read.");
1363
+ else {
1364
+ out.push("| Group | Title | Tasks | TEST FIRST tests | KB |", "| --- | --- | --- | --- | --- |");
1365
+ for (const g of groups)
1366
+ out.push(`| ${g.group} | ${g.title} | ${g.tasks} | ${g.tests} | ${g.kb.toFixed(1)} |`);
1367
+ }
1368
+ if (sizes.length > 0) {
1369
+ out.push("", "## Tasks", "", "| Task | Group | Tests | Test files |", "| --- | --- | --- | --- |");
1370
+ for (const t of sizes)
1371
+ out.push(`| ${t.task} | ${t.group} | ${t.tests} | ${t.files} |`);
1372
+ }
1373
+ out.push("", "## Problems", "");
1374
+ if (problems.length === 0)
1375
+ out.push("None.");
1376
+ for (const p of problems)
1377
+ out.push(`- \`${plan}:${p.line}\` \`${p.kind}\` — ${p.message}`);
1378
+ out.push("", `## Existence (${existenceArg === "refuse" ? "refuses the plan" : "reported only"})`, "");
1379
+ if (existence.length === 0)
1380
+ out.push("None.");
1381
+ for (const e of existence)
1382
+ out.push(`- \`${plan}:${e.line}\` — ${e.message}`);
1383
+ const log = path.resolve(ctx.cwd, logArg);
1384
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1385
+ fs.writeFileSync(log, `${out.join("\n")}\n`);
1386
+ ctx.emit({ plan, groups, tasks: sizes, problems, existence, log: logArg });
1387
+ ctx.log(`plan check: ${problems.length} problem(s), ${existence.length} existence finding(s)${refused ? " — refused" : ""}; report in ${logArg}`);
1388
+ return refused ? EXIT.NO : EXIT.OK;
1389
+ },
1390
+ },
693
1391
  },
694
1392
  };