@cbartens/bkit 5.5.1 → 6.1.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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -6,26 +6,47 @@
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
- //
10
- // bkit tests red / green — test-first evidence for build tasks. Both run one test
11
- // file through the consumer's `bkit:test:file` script and judge its JUnit report,
12
- // never its exit code alone: a misspelled path, a syntax error and an import of
13
- // unwritten code all exit non-zero exactly like a real failure. A red counts only
14
- // when the NAMED test ran and failed; green only when it ran and passed.
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.
11
+ // bkit tests red / green — test-first evidence for build tasks. `red` runs every TEST FIRST
12
+ // test of one group's open tasks after the tests step wrote them and before any task code
13
+ // exists: one run per test file through the consumer's `bkit:test:file` script, each test
14
+ // judged by the JUnit report, never the exit code alone (a misspelled path, a syntax error
15
+ // and an import of unwritten code all exit non-zero exactly like a real failure). A red is
16
+ // the NAMED test failing, or its file failing to load; `green` reads the group's red row and
17
+ // needs the named test to run and pass.
15
18
  import { spawnSync } from "node:child_process";
19
+ import { createHash } from "node:crypto";
16
20
  import * as fs from "node:fs";
17
21
  import * as os from "node:os";
18
22
  import * as path from "node:path";
19
- import { BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
20
- import { CommandError, EXIT, git } from "../lib.js";
23
+ import { BKIT_LINT_FILE_SCRIPT, BKIT_TEST_FILE_SCRIPT } from "../../install/manifest.js";
24
+ import { clampLogPath } from "../../ledgers/clamp-log.js";
25
+ import { appendLine, statusTimestamp, validateCiSelection, testRunProblem, } from "../../ledgers/status.js";
26
+ import { classifyLockExit, CommandError, EXIT, git, runGit, testsLockHolder, wholeNumber, } from "../lib.js";
27
+ import { parseJson } from "../../shared/json.js";
21
28
  import { readPackageJson } from "../../shared/package-json.js";
22
- 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";
29
+ import { COULD_NOT_RUN_EXIT_CODES, scriptCommand, testCommand, } from "../../shared/package-manager.js";
30
+ import { CONFIG_DEFAULTS, readBkitConfig } from "../../shared/settings.js";
31
+ import { FILE_FLAG, GROUP_FLAG, WORKFLOW_FLAG, positiveInt, readStatusRows, readRuns, statusFile, str, } from "./status.js";
32
+ import { NO_MARKERS_REASON, derivedTestMatrix, fenceNeverClosed, parsePlanBlocks, reuseInventory, supersessionInventory, } from "./plan-blocks.js";
24
33
  import { writeStepRow } from "./steps.js";
34
+ import { appendRecord, clampFile } from "./context.js";
35
+ import { testsChangedVerb } from "./tests-changed.js";
25
36
  /** Exit code: no candidate gate is declared in package.json. */
26
37
  export const EXIT_NO_GATE = 3;
27
38
  /** Exit code: the gate could not run (exit 126 / 127, or the package runner is missing). */
28
39
  export const EXIT_COULD_NOT_RUN = 4;
40
+ /** Exit code: --artifact could not be written, trimmed or recorded. */
41
+ export const EXIT_ARTIFACT_STEP = 5;
42
+ /** The status row type `tests run --file` appends, one per run. */
43
+ export const TEST_RUN_ROW = "test-run";
44
+ /** The env var naming the folder every runner a gate calls writes its JUnit XML into. */
45
+ export const REPORT_DIR_ENV = "BKIT_TEST_REPORT_DIR";
46
+ export { classifyLockExit } from "../lib.js";
47
+ const NO_REPORT_HINT = `no JUnit report in $${REPORT_DIR_ENV} — failures unknown; turn on each test runner's JUnit ` +
48
+ `reporter in the gate and point its output into $${REPORT_DIR_ENV} ` +
49
+ "(.bkit/workflows.md § Local gate scripts)";
29
50
  const DEFAULT_TAIL = 40;
30
51
  const NO_GATE_HINT = "declare a bkit:gate:* script in package.json that runs your stack's checks " +
31
52
  "(.bkit/workflows.md § Local gate scripts lists the names and what each covers)";
@@ -53,7 +74,8 @@ export const gateScope = (gate) => scriptCommand(gate).join(" ");
53
74
  export function runToLog(argv, cwd, log, env) {
54
75
  fs.mkdirSync(path.dirname(log), { recursive: true });
55
76
  const fd = fs.openSync(log, "w");
56
- const res = spawnSync(argv[0], argv.slice(1), {
77
+ const protectedArgv = testCommand(argv);
78
+ const res = spawnSync(protectedArgv[0], protectedArgv.slice(1), {
57
79
  cwd,
58
80
  stdio: ["ignore", fd, fd],
59
81
  env: env === undefined ? process.env : { ...process.env, ...env },
@@ -67,14 +89,307 @@ export function runToLog(argv, cwd, log, env) {
67
89
  return res.status;
68
90
  return 128 + ((res.signal ? os.constants.signals[res.signal] : undefined) ?? 1);
69
91
  }
70
- const tailLines = (file, n) => fs.readFileSync(file, "utf-8").replace(/\n$/, "").split("\n").slice(-n);
92
+ /** `{log}.reports`, emptied: a previous attempt's reports never count toward this one. */
93
+ function freshReportDir(log) {
94
+ const dir = `${log}.reports`;
95
+ fs.rmSync(dir, { recursive: true, force: true });
96
+ fs.mkdirSync(dir, { recursive: true });
97
+ return dir;
98
+ }
99
+ /** Failing plus erroring test cases across every `*.xml` under `dir`; null when there is none. */
100
+ export function countReportFailures(dir) {
101
+ const xml = fs.readdirSync(dir, { recursive: true }).filter((f) => f.endsWith(".xml") && fs.statSync(path.join(dir, f)).isFile());
102
+ if (xml.length === 0)
103
+ return null;
104
+ return xml
105
+ .flatMap((f) => parseJunit(fs.readFileSync(path.join(dir, f), "utf-8")))
106
+ .filter((c) => c.state === "failure" || c.state === "error").length;
107
+ }
108
+ const tailLines = (file, n) => fs
109
+ .readFileSync(file, "utf-8")
110
+ .replace(/\r?\n$/, "")
111
+ .split(/\r?\n/)
112
+ .slice(-n);
113
+ /**
114
+ * Append one `test-run` row to `file`. `run` numbers this step's test-run rows in the
115
+ * workflow's active run (since its last workflow-started row), this one included, so a
116
+ * gate re-run under the same attempt still shows.
117
+ */
118
+ function appendTestRun(file, r) {
119
+ const rows = readStatusRows(file);
120
+ let start = -1;
121
+ rows.forEach((x, i) => {
122
+ if (x.type === "workflow-started" && x.workflow === r.workflow)
123
+ start = i;
124
+ });
125
+ const run = rows
126
+ .slice(start + 1)
127
+ .filter((x) => x.type === TEST_RUN_ROW && x.workflow === r.workflow && x.step === r.step)
128
+ .length + 1;
129
+ const row = {
130
+ type: TEST_RUN_ROW,
131
+ workflow: r.workflow,
132
+ at: statusTimestamp(),
133
+ step: r.step,
134
+ ...(r.attempt === undefined ? {} : { attempt: r.attempt }),
135
+ run,
136
+ verdict: r.verdict,
137
+ exitCode: r.exitCode,
138
+ failures: r.failures,
139
+ scope: r.scope,
140
+ log: r.log,
141
+ ...(r.artifact === undefined ? {} : { artifact: r.artifact }),
142
+ ...(r.source === undefined ? {} : { source: r.source }),
143
+ ...r.evidence,
144
+ };
145
+ const problem = testRunProblem(row);
146
+ if (problem !== null)
147
+ throw new CommandError(EXIT.USAGE, problem);
148
+ fs.appendFileSync(file, appendLine(row));
149
+ return row;
150
+ }
71
151
  // ---------------------------------------------------------------------------
72
152
  // Test-first: JUnit reading, plan `Test first:` lines, red / green judgement
73
153
  // ---------------------------------------------------------------------------
74
154
  /** The env var naming the JUnit report path `bkit:test:file` must write. */
75
155
  export const REPORT_ENV = "BKIT_TEST_REPORT";
76
- /** The status row step a recorded red writes. */
77
- export const RED_STEP = "build-task-red";
156
+ /** The status row step a group's red writes: one row per `tests red` run, a state and blob per planned test. */
157
+ export const RED_STEP = "build-tests-red";
158
+ /**
159
+ * The states that count as a red: the test failed, its file did not load, the tests step
160
+ * vouched for its pass, or it is an existing test updated and passing, whose diff the
161
+ * verifier judges (it may add expectations, never remove or loosen one).
162
+ */
163
+ export const RED_PROVEN = new Set([
164
+ "red",
165
+ "red-not-loaded",
166
+ "passed-accepted",
167
+ "updated",
168
+ ]);
169
+ /** The `build-tests-red` rows of `workflow` in status.jsonl, in file order; `group` narrows. */
170
+ function redRows(file, workflow, group) {
171
+ if (!fs.existsSync(file))
172
+ return [];
173
+ return readStatusRows(file).filter((r) => r.type === "step-done" &&
174
+ r.workflow === workflow &&
175
+ r.step === RED_STEP &&
176
+ typeof r.group === "number" &&
177
+ (group === undefined || r.group === group));
178
+ }
179
+ /** A red row's `tests`, as written. */
180
+ export const redTestsOf = (row) => Array.isArray(row.tests) ? row.tests : [];
181
+ /** The key a planned test is looked up by: task numbers are unique across the plan. */
182
+ export const redKey = (task, test, name) => JSON.stringify([task, test, name]);
183
+ /** The number this group's next red row carries: its rows so far, plus one. */
184
+ function redAttempt(file, workflow, group) {
185
+ if (!fs.existsSync(file))
186
+ return 1;
187
+ return (readStatusRows(file).filter((r) => {
188
+ const row = r;
189
+ return (row.type === "step-done" &&
190
+ row.workflow === workflow &&
191
+ row.step === RED_STEP &&
192
+ row.group === group);
193
+ }).length + 1);
194
+ }
195
+ /**
196
+ * Every planned test the red rows recorded, keyed by task, file and name. A later row's entry
197
+ * wins, so a retry or a later task of the group overrides only the tests it ran, except that a
198
+ * proven red is never replaced by an unproven result for the same test lines. `group` narrows
199
+ * to one group.
200
+ */
201
+ export function redEntries(file, workflow, group) {
202
+ const out = new Map();
203
+ for (const row of redRows(file, workflow, group))
204
+ for (const t of redTestsOf(row)) {
205
+ const key = redKey(t.task, t.test, t.testName);
206
+ const earlier = out.get(key);
207
+ const keepsProof = earlier !== undefined &&
208
+ RED_PROVEN.has(earlier.state) &&
209
+ !RED_PROVEN.has(t.state) &&
210
+ typeof earlier.block === "string" &&
211
+ earlier.block === t.block;
212
+ if (!keepsProof)
213
+ out.set(key, t);
214
+ }
215
+ return out;
216
+ }
217
+ /**
218
+ * The planned tests of `group` a code step changed since their red: a test whose own lines
219
+ * (`testBlock`) no longer hash to the recorded block. A row with no block (written before
220
+ * per-test locking, or when no line carried the name) derives the block from the recorded
221
+ * blob; when that holds no block either, the whole file's blob is compared. Other edits to a
222
+ * test file are free.
223
+ */
224
+ export function touchedTests(top, file, workflow, group) {
225
+ const touched = [];
226
+ const texts = new Map();
227
+ const textOf = (test) => {
228
+ if (!texts.has(test)) {
229
+ const abs = path.join(top, test);
230
+ texts.set(test, fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null);
231
+ }
232
+ return texts.get(test);
233
+ };
234
+ for (const t of redEntries(file, workflow, group).values()) {
235
+ let block = t.block ?? null;
236
+ if (block === null)
237
+ block = blockHash(blobText(top, t.blob), t.testName);
238
+ if (block === null) {
239
+ if (git(top, ["hash-object", "--", t.test]) !== t.blob)
240
+ touched.push({ test: t.test, name: t.testName });
241
+ continue;
242
+ }
243
+ if (blockHash(textOf(t.test), t.testName) !== block)
244
+ touched.push({ test: t.test, name: t.testName });
245
+ }
246
+ return touched;
247
+ }
248
+ /** The text a recorded blob holds, untrimmed; null when the object store lacks it. */
249
+ function blobText(top, blob) {
250
+ if (blob === null)
251
+ return null;
252
+ const res = spawnSync("git", ["cat-file", "-p", blob], { cwd: top, encoding: "utf-8" });
253
+ return res.status === 0 ? res.stdout : null;
254
+ }
255
+ /** Leading whitespace width, a tab counting as one column. */
256
+ const indentOf = (line) => line.length - line.trimStart().length;
257
+ /** A line that only closes the block opened at its own indent. */
258
+ const CLOSER = /^(?:[)\]}]|end\b)/;
259
+ const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
260
+ /** A comment line: a name in it is prose, not the test. */
261
+ const COMMENT = /^(?:\/\/|\/\*|\*|#|--|<!--)/;
262
+ /** A line opening a suite (`describe`, `context`, `suite`, a class), not a test. */
263
+ const SUITE = /^(?:[\w$]+\.)?(?:describe|context|suite|class)\b/;
264
+ /**
265
+ * The first line `matches` that is no comment and opens no suite; else the first matching
266
+ * suite line, so a suite that alone carries the name still yields a block; else -1.
267
+ */
268
+ function testStart(lines, matches) {
269
+ let suite = -1;
270
+ for (let i = 0; i < lines.length; i++) {
271
+ const line = lines[i].trimStart();
272
+ if (!matches(lines[i]) || COMMENT.test(line))
273
+ continue;
274
+ if (!SUITE.test(line))
275
+ return i;
276
+ if (suite < 0)
277
+ suite = i;
278
+ }
279
+ return suite;
280
+ }
281
+ /**
282
+ * The lines of the test named `name` in `text`, or null when no line names it. The test
283
+ * starts on the first line naming it as a quoted string (else as a whole word) that is no
284
+ * comment and opens no suite, or on the line before when the name opens its line and that
285
+ * line ends with `(`; it runs through every deeper-indented line after the start, and one
286
+ * closing line (`}`, `)`, `]`, `end`) at the start's indent. Framework-agnostic: it needs
287
+ * only a name and indentation.
288
+ */
289
+ export function testBlock(text, name) {
290
+ if (text === null)
291
+ return null;
292
+ const span = testSpan(text, name);
293
+ return span === null
294
+ ? null
295
+ : text
296
+ .split("\n")
297
+ .slice(span.start - 1, span.end)
298
+ .join("\n");
299
+ }
300
+ /**
301
+ * The 1-based first and last line of the test named `name` in `text` (the lines
302
+ * `testBlock` returns), or null when no line names it.
303
+ */
304
+ export function testSpan(text, name) {
305
+ const lines = text.split("\n");
306
+ const quoted = [`"${name}"`, `'${name}'`, `\`${name}\``];
307
+ let at = testStart(lines, (l) => quoted.some((q) => l.includes(q)));
308
+ if (at < 0) {
309
+ const word = new RegExp(`(^|[^\\w])${escapeRegExp(name)}([^\\w]|$)`);
310
+ at = testStart(lines, (l) => word.test(l));
311
+ }
312
+ if (at < 0) {
313
+ // A suite path (`suite > test`, as a JUnit report names it): the last segment is the test.
314
+ const last = name.split(" > ").pop();
315
+ return last === name ? null : testSpan(text, last);
316
+ }
317
+ let start = at;
318
+ while (start > 0 &&
319
+ /^["'`]/.test(lines[start].trimStart()) &&
320
+ /\($/.test(lines[start - 1].trimEnd()))
321
+ start -= 1;
322
+ const base = indentOf(lines[start]);
323
+ let end = start;
324
+ for (let i = start + 1; i < lines.length; i++) {
325
+ const line = lines[i];
326
+ if (line.trim() === "")
327
+ continue;
328
+ if (indentOf(line) > base) {
329
+ end = i;
330
+ continue;
331
+ }
332
+ if (indentOf(line) === base && CLOSER.test(line.trimStart()))
333
+ end = i;
334
+ break;
335
+ }
336
+ return { start: start + 1, end: end + 1 };
337
+ }
338
+ /**
339
+ * The line diff of a test's own lines, `before` to `after`: unified lines (` `, `-`, `+`)
340
+ * over a longest common subsequence, and the counts of lines removed and added. A change
341
+ * that removes no line cannot have dropped an expectation; it can still have disabled one,
342
+ * which only a read of the added lines tells.
343
+ */
344
+ export function lineDiff(before, after) {
345
+ const a = before.split("\n");
346
+ const b = after.split("\n");
347
+ const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
348
+ for (let i = a.length - 1; i >= 0; i--)
349
+ for (let j = b.length - 1; j >= 0; j--)
350
+ lcs[i][j] =
351
+ a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
352
+ const out = [];
353
+ let removed = 0;
354
+ let added = 0;
355
+ let i = 0;
356
+ let j = 0;
357
+ while (i < a.length || j < b.length) {
358
+ if (i < a.length && j < b.length && a[i] === b[j]) {
359
+ out.push(` ${a[i]}`);
360
+ i++;
361
+ j++;
362
+ }
363
+ else if (i < a.length && (j >= b.length || lcs[i + 1][j] >= lcs[i][j + 1])) {
364
+ out.push(`-${a[i]}`);
365
+ removed++;
366
+ i++;
367
+ }
368
+ else {
369
+ out.push(`+${b[j]}`);
370
+ added++;
371
+ j++;
372
+ }
373
+ }
374
+ return { text: out.join("\n"), removed, added };
375
+ }
376
+ /** The sha-1 of a test's own lines (`testBlock`), or null when `text` holds no such test. */
377
+ export function blockHash(text, name) {
378
+ const block = testBlock(text, name);
379
+ return block === null ? null : createHash("sha1").update(block).digest("hex");
380
+ }
381
+ /** The commit the group started at: its `build-group-start` row's `parentSha`. */
382
+ function groupStartSha(file, workflow, group) {
383
+ if (!fs.existsSync(file))
384
+ return undefined;
385
+ const row = readStatusRows(file)
386
+ .filter((r) => r.type === "step-done" &&
387
+ r.workflow === workflow &&
388
+ r.step === "build-group-start" &&
389
+ r.group === group)
390
+ .at(-1);
391
+ return typeof row?.parentSha === "string" ? row.parentSha : undefined;
392
+ }
78
393
  const NO_TEST_FILE_HINT = `declare "${BKIT_TEST_FILE_SCRIPT}" in package.json: it runs the one test file passed as its ` +
79
394
  `argument and writes a JUnit report to $${REPORT_ENV} ` +
80
395
  "(.bkit/workflows.md § Local gate scripts)";
@@ -98,18 +413,21 @@ function attr(attrs, name) {
98
413
  const m = new RegExp(String.raw `\s${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`).exec(attrs);
99
414
  return m ? decodeXml(m[1] ?? m[2] ?? "") : undefined;
100
415
  }
101
- /** Every `<testcase>` in a JUnit report: its name, outcome and first failure message. */
416
+ /** CDATA text as escaped character data, so a tag inside it never ends an element early. */
417
+ const escapeCdata = (xml) => xml.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"));
418
+ /** Every `<testcase>` in a JUnit report: its name, outcome, first failure message and detail. */
102
419
  export function parseJunit(xml) {
103
- const body = xml.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, "").replace(/<!--[\s\S]*?-->/g, "");
420
+ const body = escapeCdata(xml).replace(/<!--[\s\S]*?-->/g, "");
104
421
  const cases = [];
105
422
  const testcase = new RegExp(String.raw `<testcase${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/testcase>)`, "g");
106
- const outcome = new RegExp(String.raw `<(failure|error|skipped)${ATTRS}`);
423
+ const outcome = new RegExp(String.raw `<(failure|error|skipped)${ATTRS}\s*(?:\/>|>([\s\S]*?)<\/\1>)`);
107
424
  for (const m of body.matchAll(testcase)) {
108
425
  const child = outcome.exec(m[2] ?? "");
109
426
  cases.push({
110
427
  name: attr(m[1] ?? "", "name") ?? "",
111
428
  state: child ? child[1] : "passed",
112
429
  message: child ? (attr(child[2] ?? "", "message") ?? "") : "",
430
+ detail: child ? decodeXml((child[3] ?? "").replace(/<[^>]*>/g, "")).trim() : "",
113
431
  });
114
432
  }
115
433
  return cases;
@@ -122,29 +440,40 @@ const caseNames = (cases) => cases.length === 0
122
440
  .slice(0, 5)
123
441
  .map((c) => `"${c.name}"`)
124
442
  .join(", ")}${cases.length > 5 ? ", …" : ""}`;
125
- /** Why a run is not a valid red for `want` (kind + reason), or null when it is one. */
126
- export function judgeRed(exitCode, cases, want) {
443
+ /** The stem a load error names: the test file's base name without its extension. */
444
+ const fileStem = (file) => path.posix.basename(file).replace(/\.[^.]*$/, "");
445
+ /**
446
+ * How `want` stood in a red run of `file`, from its JUnit report: `red` (the named test
447
+ * failed or errored), `red-not-loaded` (the file ran no test, or the only cases are failures
448
+ * named after the file itself: a load error, which an import of unwritten code is),
449
+ * `vacuous` (the named test passed, so it proves nothing before the task's code), `missing`
450
+ * (it did not run, or was skipped) or `no-report`.
451
+ */
452
+ export function judgeRed(cases, want, file) {
127
453
  if (cases === null)
128
454
  return {
129
- kind: "no-report",
130
- reason: `no JUnit report at $${REPORT_ENV} — ${BKIT_TEST_FILE_SCRIPT} must write one`,
455
+ state: "no-report",
456
+ detail: `no JUnit report at $${REPORT_ENV} — ${BKIT_TEST_FILE_SCRIPT} must write one`,
131
457
  };
132
458
  const named = cases.filter((c) => isNamedCase(c.name, want));
133
- if (named.length === 0)
134
- return { kind: "not-run", reason: `the named test "${want}" did not run; ${caseNames(cases)}` };
459
+ if (named.length === 0) {
460
+ const stem = fileStem(file);
461
+ if (cases.length === 0 || cases.every((c) => c.state !== "passed" && c.name.includes(stem)))
462
+ return {
463
+ state: "red-not-loaded",
464
+ detail: `\`${file}\` did not load${cases[0]?.message ? `: ${cases[0].message}` : ""}`,
465
+ };
466
+ return { state: "missing", detail: `"${want}" did not run; ${caseNames(cases)}` };
467
+ }
135
468
  if (named.some((c) => c.state === "passed"))
136
469
  return {
137
- kind: "passed",
138
- reason: `"${want}" passed — a red must fail before the task's code exists`,
470
+ state: "vacuous",
471
+ detail: `"${want}" passes at its red, so it proves nothing`,
139
472
  };
140
473
  if (named.some((c) => c.state === "skipped"))
141
- return { kind: "skipped", reason: `"${want}" was skipped, not run` };
142
- if (exitCode === 0)
143
- return {
144
- kind: "exit-mismatch",
145
- reason: `"${want}" failed in the report but the script exited 0`,
146
- };
147
- return null;
474
+ return { state: "missing", detail: `"${want}" was skipped, not run` };
475
+ const failed = named.find((c) => c.state !== "passed");
476
+ return { state: "red", detail: `${failed.state}${failed.message ? `: ${failed.message}` : ""}` };
148
477
  }
149
478
  /** Why a run is not green for `want`, or null when every case of the named test passed. */
150
479
  export function judgeGreen(cases, want) {
@@ -158,70 +487,365 @@ export function judgeGreen(cases, want) {
158
487
  ? null
159
488
  : `"${want}" ${bad.state}${bad.message ? `: ${bad.message}` : ""}`;
160
489
  }
161
- const TASK_LINE = /^\s*- \[[ xX]\] \*\*Task (\d+):\*\*/;
162
- const TEST_FIRST = "**Test first:**";
163
- /** `text` split on `;` outside backticks. */
164
- function splitEntries(text) {
490
+ /** The task field naming a task's tests, and the one recording an accepted missing red. */
491
+ export const TEST_FIRST = "**TEST FIRST:**";
492
+ export const TEST_EXCEPTION = "**TEST EXCEPTION:**";
493
+ /** The plan caps `package.json` `bkit.workflows.tasks` sets for the checkout `cwd` sits in. */
494
+ export const planCaps = (cwd) => readBkitConfig(toplevel(cwd)).tasks;
495
+ /** The caps as the plan-check report and help state them. */
496
+ 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`;
497
+ /** A task block's TEST FIRST read as one `TestFirst`; a TEST EXCEPTION with no TEST FIRST is its `n/a`. */
498
+ /**
499
+ * Planned tests of open tasks whose name a test in their file already carries: the tests
500
+ * step cannot write a new test under that name, so it either updates the existing one or
501
+ * finds it passing. Reported only — the plan names the update, or a new name.
502
+ */
503
+ function existingTestNames(text, top) {
165
504
  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 = "";
505
+ for (const t of parsePlanBlocks(text).tasks) {
506
+ if (t.done)
507
+ continue;
508
+ const s = testFirstOf(t);
509
+ if (s.kind !== "test")
510
+ continue;
511
+ for (const x of s.tests) {
512
+ const abs = path.join(top, x.test);
513
+ if (!fs.existsSync(abs))
514
+ continue;
515
+ if (testBlock(fs.readFileSync(abs, "utf-8"), x.name) !== null)
516
+ out.push({ line: t.testFirst?.line ?? t.line, task: t.task, test: x.test, name: x.name });
174
517
  }
175
- else
176
- cur += ch;
177
518
  }
178
- return [...out, cur];
519
+ return out;
520
+ }
521
+ function testFirstOf(t) {
522
+ const { task, testFirst: tf, testException: exc } = t;
523
+ const plain = (tests) => tests.map(({ test, name }) => ({ test, name }));
524
+ if (tf === undefined)
525
+ return exc === undefined ? { task, kind: "missing" } : { task, kind: "na", reason: exc.text };
526
+ if (tf.malformed.length > 0 || (tf.tests.length === 0 && tf.na === undefined))
527
+ return { task, kind: "malformed" };
528
+ if (tf.tests.length === 0)
529
+ return { task, kind: "na", reason: tf.na };
530
+ const tests = plain(tf.tests);
531
+ return exc === undefined || exc.tests.length === 0
532
+ ? { task, kind: "test", tests }
533
+ : { task, kind: "test", tests, exception: { tests: plain(exc.tests), lines: exc.lines } };
179
534
  }
180
535
  /**
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.
536
+ * Each task block's TEST FIRST field (`plan-blocks.ts`): one test per sub-bullet (first
537
+ * backticked span = file, second = test name), `n/a — {reason}`, missing, or malformed
538
+ * (an entry with fewer than two spans, or no entry). A TEST EXCEPTION field names, in
539
+ * the same entry form, the tests whose missing reds it accepts. `group` narrows to
540
+ * one group's tasks.
185
541
  */
186
- export function readTestFirst(plan) {
187
- 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" });
542
+ export function readTestFirst(plan, group) {
543
+ return parsePlanBlocks(plan)
544
+ .tasks.filter((t) => group === undefined || t.group === group)
545
+ .map(testFirstOf);
546
+ }
547
+ /** Per task, the planned tests and distinct test files it names (`n/a`, missing and malformed count 0). */
548
+ export const taskSizes = (specs) => specs.map((s) => s.kind === "test"
549
+ ? { task: s.task, tests: s.tests.length, files: new Set(s.tests.map((t) => t.test)).size }
550
+ : { task: s.task, tests: 0, files: 0 });
551
+ /**
552
+ * Files with a NEW row in the plan's Reuse Inventory table (`reuseInventory`): the
553
+ * paths in the `File` cell of each row whose `Decision` cell reads NEW.
554
+ */
555
+ export function inventoryNewFiles(text) {
556
+ const rows = reuseInventory(text)?.rows ?? [];
557
+ return new Set(rows.filter((r) => /^\**new\b/i.test(r.decision)).flatMap((r) => r.files));
558
+ }
559
+ const kb1 = (bytes) => Math.round((bytes / 1024) * 10) / 10;
560
+ /**
561
+ * One plan's groups and tasks against the caps and the block format: parse errors and
562
+ * task-like text outside every block, a task without DONE WHEN or without TEST FIRST and
563
+ * TEST EXCEPTION, a malformed TEST FIRST, a DEPENDS ON naming a missing task or one in a
564
+ * later group, a group or task over a cap in `caps`, a CREATE file with no NEW Reuse
565
+ * Inventory row, a `Derived Test Matrix` row naming no task / an undefined task / two
566
+ * tasks or a test-bearing task no row names, and a DELETE file with no Supersession row.
567
+ */
568
+ export function checkPlanText(text, caps = CONFIG_DEFAULTS.tasks) {
569
+ const blocks = parsePlanBlocks(text);
570
+ const lines = text.split(/\r?\n/);
571
+ const problems = blocks.errors.map((e) => ({
572
+ line: e.line,
573
+ kind: e.kind,
574
+ message: e.message,
575
+ }));
576
+ if (blocks.tasks.length === 0 && blocks.fenceOpen === undefined)
577
+ problems.push({
578
+ line: 1,
579
+ kind: "markers",
580
+ message: "no task markers: write each task as a `<!-- bkit:task N start -->` block inside a `<!-- bkit:group N start -->` block",
581
+ });
582
+ const specs = new Map(blocks.tasks.map((t) => [t.task, testFirstOf(t)]));
583
+ const sizes = blocks.tasks.map((t) => {
584
+ const s = specs.get(t.task);
585
+ const tests = s.kind === "test" ? s.tests : [];
586
+ return {
587
+ task: t.task,
588
+ group: t.group,
589
+ tests: tests.length,
590
+ files: new Set(tests.map((x) => x.test)).size,
591
+ };
592
+ });
593
+ const overCap = sizes.filter((t) => t.tests > caps.maxTestsPerTask || t.files > caps.maxTestFilesPerTask);
594
+ const byTask = new Map(blocks.tasks.map((t) => [t.task, t]));
595
+ const newFiles = inventoryNewFiles(text);
596
+ for (const t of blocks.tasks) {
597
+ const field = (message, line = t.line) => problems.push({ line, kind: "field", message: `TASK ${t.task}: ${message}` });
598
+ if (t.doneWhen === undefined || t.doneWhen === "")
599
+ field("has no **DONE WHEN:** field");
600
+ const s = specs.get(t.task);
601
+ if (s.kind === "missing")
602
+ field("has neither **TEST FIRST:** nor **TEST EXCEPTION:**");
603
+ for (const line of t.testFirst?.malformed ?? [])
604
+ field("TEST FIRST entry is neither `test file` `test name` nor `n/a — {reason}`", line);
605
+ if (s.kind === "malformed" && (t.testFirst?.malformed.length ?? 0) === 0)
606
+ field("TEST FIRST names no test", t.testFirst.line);
607
+ for (const d of t.dependsOn) {
608
+ const dep = byTask.get(d);
609
+ const message = d === t.task
610
+ ? `TASK ${t.task} depends on itself`
611
+ : dep === undefined
612
+ ? `TASK ${t.task} depends on TASK ${d}, but TASK ${d} does not exist`
613
+ : dep.group > t.group
614
+ ? `TASK ${t.task} depends on TASK ${d}, which is in a later group (GROUP ${dep.group}); groups build in order`
615
+ : undefined;
616
+ if (message !== undefined)
617
+ problems.push({ line: t.line, kind: "depends", message });
618
+ }
619
+ const size = sizes.find((x) => x.task === t.task);
620
+ if (size.tests > caps.maxTestsPerTask)
621
+ problems.push({
622
+ line: t.line,
623
+ kind: "cap",
624
+ message: `TASK ${t.task} names ${size.tests} TEST FIRST tests, over the cap of ${caps.maxTestsPerTask}`,
625
+ });
626
+ if (size.files > caps.maxTestFilesPerTask)
627
+ problems.push({
628
+ line: t.line,
629
+ kind: "cap",
630
+ message: `TASK ${t.task} names ${size.files} test files, over the cap of ${caps.maxTestFilesPerTask}`,
631
+ });
632
+ for (const c of t.create)
633
+ if (!newFiles.has(path.posix.normalize(c.file)))
634
+ problems.push({
635
+ line: c.line,
636
+ kind: "inventory",
637
+ message: `TASK ${t.task}: CREATE in \`${c.file}\` has no NEW row naming it in the Reuse Inventory's File column`,
638
+ });
639
+ }
640
+ // The matrix maps each row to one task and each test-bearing task to a row. A plan with no
641
+ // matrix section yields no problem: the refusal is on a row, and issue-form plans carry none.
642
+ const matrix = derivedTestMatrix(text);
643
+ if (matrix !== null) {
644
+ if (matrix.taskColumn === null)
645
+ problems.push({
646
+ line: matrix.line,
647
+ kind: "matrix",
648
+ message: "the Derived Test Matrix header has no `Task` column; add one naming the task each row's test belongs to",
649
+ });
650
+ else {
651
+ const mapped = new Set();
652
+ for (const row of matrix.rows) {
653
+ const named = row.tasks.map((n) => `TASK ${n}`);
654
+ if (row.tasks.length === 0)
655
+ problems.push({
656
+ line: row.number,
657
+ kind: "matrix",
658
+ message: `Derived Test Matrix row maps to no task: name one in its \`Task\` cell`,
659
+ });
660
+ else if (row.tasks.length > 1)
661
+ problems.push({
662
+ line: row.number,
663
+ kind: "matrix",
664
+ message: `Derived Test Matrix row maps to ${named.join(" and ")}; name exactly one task`,
665
+ });
666
+ else {
667
+ const n = row.tasks[0];
668
+ if (!byTask.has(n))
669
+ problems.push({
670
+ line: row.number,
671
+ kind: "matrix",
672
+ message: `Derived Test Matrix row maps to TASK ${n}, which the plan does not define`,
673
+ });
674
+ mapped.add(n);
675
+ }
676
+ }
677
+ for (const t of blocks.tasks)
678
+ if (specs.get(t.task).kind === "test" && !mapped.has(t.task))
679
+ problems.push({
680
+ line: t.line,
681
+ kind: "matrix",
682
+ message: `TASK ${t.task} names TEST FIRST tests but no Derived Test Matrix row maps to it`,
683
+ });
684
+ }
685
+ }
686
+ const superseded = new Set((supersessionInventory(text) ?? []).flatMap((r) => r.files));
687
+ for (const t of blocks.tasks)
688
+ for (const d of t.delete)
689
+ if (!superseded.has(path.posix.normalize(d.file)))
690
+ problems.push({
691
+ line: d.line,
692
+ kind: "supersession",
693
+ message: `TASK ${t.task}: DELETE in \`${d.file}\` has no row naming it in the Supersession Inventory`,
694
+ });
695
+ const groups = blocks.groups.map((g) => {
696
+ const tests = sizes.filter((s) => s.group === g.group).reduce((n, s) => n + s.tests, 0);
697
+ const bytes = Buffer.byteLength(lines.slice(g.line - 1, g.end).join("\n"));
698
+ return { group: g.group, title: g.title, tasks: g.tasks.length, tests, kb: kb1(bytes) };
699
+ });
700
+ for (const g of groups) {
701
+ const at = blocks.groups.find((x) => x.group === g.group).line;
702
+ if (g.tasks > caps.maxPerGroup)
703
+ problems.push({
704
+ line: at,
705
+ kind: "cap",
706
+ message: `GROUP ${g.group} has ${g.tasks} tasks, over the cap of ${caps.maxPerGroup}`,
707
+ });
708
+ if (g.tests > caps.maxTestsPerGroup)
709
+ problems.push({
710
+ line: at,
711
+ kind: "cap",
712
+ message: `GROUP ${g.group} has ${g.tests} TEST FIRST tests, over the cap of ${caps.maxTestsPerGroup}`,
713
+ });
714
+ }
715
+ problems.sort((a, b) => a.line - b.line);
716
+ return { groups, sizes, overCap, problems };
717
+ }
718
+ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
719
+ const wordIn = (body, word) => new RegExp(`(?<![\\w$])${escapeRe(word)}(?![\\w$])`).test(body);
720
+ /** The 1-based lines of `body` that are a Markdown heading reading exactly `heading`. */
721
+ const headingLines = (body, heading) => body.split(/\r?\n/).flatMap((l, i) => {
722
+ const h = /^#{1,6}\s+(.*?)(?:\s+#+)?\s*$/.exec(l);
723
+ return h !== null && h[1].trim() === heading ? [i + 1] : [];
724
+ });
725
+ /** A key path's segments nested in indented `key:` lines (YAML): each one inside the block of the one before. */
726
+ function nestedKeys(body, segs) {
727
+ const lines = body.split(/\r?\n/);
728
+ const indent = (l) => /^\s*/.exec(l)[0].length;
729
+ const walk = (from, to, k, above) => {
730
+ const key = new RegExp(`^\\s*["']?${escapeRe(segs[k])}["']?\\s*:`);
731
+ for (let i = from; i < to; i++) {
732
+ const l = lines[i];
733
+ if (l.trim() === "" || indent(l) <= above || !key.test(l))
734
+ continue;
735
+ if (k === segs.length - 1)
736
+ return true;
737
+ let end = i + 1;
738
+ while (end < to && (lines[end].trim() === "" || indent(lines[end]) > indent(l)))
739
+ end++;
740
+ if (walk(i + 1, end, k + 1, indent(l)))
741
+ return true;
742
+ }
743
+ return false;
744
+ };
745
+ return walk(0, lines.length, 0, -1);
746
+ }
747
+ /** A key path as a `[table]` header holding its first segments and a `key =` line for the rest (TOML). */
748
+ function tableKey(body, segs) {
749
+ const lines = body.split(/\r?\n/);
750
+ for (let k = 1; k < segs.length; k++) {
751
+ const table = segs.slice(0, k).join(".");
752
+ const key = segs.slice(k).join(".");
753
+ const start = lines.findIndex((l) => l.trim() === `[${table}]`);
754
+ if (start < 0)
200
755
  continue;
756
+ const end = lines.findIndex((l, i) => i > start && /^\s*\[/.test(l));
757
+ const keyRe = new RegExp(`^\\s*${escapeRe(key)}\\s*=`);
758
+ if (lines.slice(start + 1, end < 0 ? undefined : end).some((l) => keyRe.test(l)))
759
+ return true;
760
+ }
761
+ return false;
762
+ }
763
+ /** Config files whose dotted keys must be there as the whole key path. */
764
+ const CONFIG_EXTS = new Set([".json", ".jsonc", ".yaml", ".yml", ".toml"]);
765
+ /** Whether parsed JSON `value` holds `segs` as nested object keys. */
766
+ function jsonPath(value, segs) {
767
+ let at = value;
768
+ for (const s of segs) {
769
+ if (typeof at !== "object" || at === null || Array.isArray(at) || !Object.hasOwn(at, s))
770
+ return false;
771
+ at = at[s];
772
+ }
773
+ return true;
774
+ }
775
+ /**
776
+ * Whether config `body` of `file` holds the dotted key `bare` as the whole key path: a
777
+ * `.json` file that parses is walked as JSON; otherwise the key is written whole, nested
778
+ * in indented `key:` / `"key":` lines (YAML, indented JSON), or a `[table]` and its
779
+ * `key =` line (TOML).
780
+ */
781
+ function hasDottedKey(file, body, bare) {
782
+ const segs = bare.split(".");
783
+ const json = path.posix.extname(file).toLowerCase() === ".json" ? parseJson(body) : { ok: false };
784
+ if (json.ok)
785
+ return jsonPath(json.value, segs);
786
+ return wordIn(body, bare) || nestedKeys(body, segs) || tableKey(body, segs);
787
+ }
788
+ /**
789
+ * Each READ / UPDATE / DELETE line of an unticked task whose file or symbol is not
790
+ * there, read from `root`: a plain word-boundary search in the named file. `§ heading`
791
+ * must equal one of the file's heading lines; a dotted key in a config file (`CONFIG_EXTS`)
792
+ * must be there as the whole key path, and in any other file matches on its last segment;
793
+ * a file-only line checks the file exists. A line naming
794
+ * what the task itself or a task it DEPENDS ON creates is not checked: it does not
795
+ * exist yet.
796
+ */
797
+ export function planExistence(text, root) {
798
+ const blocks = parsePlanBlocks(text);
799
+ const byTask = new Map(blocks.tasks.map((t) => [t.task, t]));
800
+ const out = [];
801
+ const cache = new Map();
802
+ const read = (file) => {
803
+ if (!cache.has(file)) {
804
+ const abs = path.resolve(root, file);
805
+ const inside = !path.relative(root, abs).startsWith("..");
806
+ cache.set(file, inside && fs.statSync(abs, { throwIfNoEntry: false })?.isFile()
807
+ ? fs.readFileSync(abs, "utf-8")
808
+ : null);
201
809
  }
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, "") });
810
+ return cache.get(file);
811
+ };
812
+ for (const t of blocks.tasks) {
813
+ if (t.done)
205
814
  continue;
815
+ const created = [t, ...t.dependsOn.map((d) => byTask.get(d)).filter((d) => d !== undefined)]
816
+ .flatMap((d) => d.create)
817
+ .map((c) => ({ file: path.posix.normalize(c.file), symbol: c.symbol }));
818
+ for (const ref of [...t.read, ...t.update, ...t.delete]) {
819
+ const file = path.posix.normalize(ref.file);
820
+ if (created.some((c) => c.file === file && (c.symbol === undefined || c.symbol === ref.symbol)))
821
+ continue;
822
+ const body = read(file);
823
+ const miss = (message) => out.push({ line: ref.line, task: t.task, message });
824
+ if (body === null) {
825
+ miss(`TASK ${t.task}: \`${ref.file}\` does not exist`);
826
+ continue;
827
+ }
828
+ if (ref.symbol === undefined)
829
+ continue;
830
+ if (ref.symbol.startsWith("§")) {
831
+ const heading = ref.symbol.replace(/^§\s*/, "").trim();
832
+ if (headingLines(body, heading).length === 0)
833
+ miss(`TASK ${t.task}: no heading \`${heading}\` in \`${ref.file}\``);
834
+ continue;
835
+ }
836
+ const bare = ref.symbol.replace(/\(\)$/, "");
837
+ const key = bare.split(".").at(-1);
838
+ if (bare.includes(".") && CONFIG_EXTS.has(path.posix.extname(file).toLowerCase())) {
839
+ if (!hasDottedKey(file, body, bare))
840
+ miss(`TASK ${t.task}: \`${bare}\` is not in \`${ref.file}\``);
841
+ }
842
+ else if (!wordIn(body, key))
843
+ miss(key === bare
844
+ ? `TASK ${t.task}: \`${key}\` is not in \`${ref.file}\``
845
+ : `TASK ${t.task}: \`${key}\` (last segment of \`${ref.symbol}\`) is not in \`${ref.file}\``);
206
846
  }
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
847
  }
215
- return out;
216
- }
217
- /** `test` as a repo-relative path inside `top`; usage error when absolute, outside, or absent. */
218
- function repoTestPath(top, test) {
219
- const rel = path.relative(top, path.resolve(top, test));
220
- if (path.isAbsolute(test) || rel.startsWith("..") || rel === "")
221
- throw new CommandError(EXIT.USAGE, `--test must be a path inside the repo, got "${test}"`);
222
- if (!fs.statSync(path.join(top, rel), { throwIfNoEntry: false })?.isFile())
223
- throw new CommandError(EXIT.USAGE, `--test ${rel} is not a file`);
224
- return rel.split(path.sep).join("/");
848
+ return out.sort((a, b) => a.line - b.line);
225
849
  }
226
850
  /** Run one test file through `bkit:test:file`; the report is read and removed. */
227
851
  function runTestFile(top, test, log) {
@@ -235,43 +859,327 @@ function runTestFile(top, test, log) {
235
859
  return { exitCode, cases };
236
860
  }
237
861
  const couldNotRunMessage = (exitCode) => `${gateScope(BKIT_TEST_FILE_SCRIPT)} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no test executed`;
238
- /** The copy of the test file a red keeps beside its log. */
239
- export const snapshotPath = (log) => `${log.replace(/\.md$/, "")}.snapshot`;
240
862
  const toplevel = (cwd) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
241
863
  /** A fence longer than any backtick run in `text`. */
242
864
  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) {
245
- return readStatusRows(file).filter((r) => {
246
- const row = r;
247
- return (row.type === "step-done" &&
248
- row.workflow === workflow &&
249
- row.step === RED_STEP &&
250
- (subPlan === undefined || row.subPlan === subPlan));
251
- });
865
+ /**
866
+ * Every gap the audit emits, and the verifier's `Fixable` for it: `null` = the
867
+ * answer needs a diff read, which only the verifier can make. A test with no proven red
868
+ * is no gap: the audit lists it as unproven, and the owner answers every unproven test
869
+ * once, at the end of the build.
870
+ */
871
+ const GAP_FIXABLE = {
872
+ "not-green": true,
873
+ "delete-still-referenced": null,
874
+ "no-test-first": false,
875
+ "test-first-malformed": false,
876
+ "test-first-unread": false,
877
+ "exception-refused": false,
878
+ };
879
+ /** One gap, with the `fixable` its kind settles and the ready-to-append log line. */
880
+ function gapOf(task, kind, detail, test) {
881
+ const fixable = GAP_FIXABLE[kind];
882
+ const subject = test === undefined ? "" : `\`${test.file}\` \`${test.name}\` — `;
883
+ return {
884
+ task,
885
+ kind,
886
+ detail,
887
+ fixable,
888
+ logLine: `${task === null ? "Plan" : `TASK ${task}`}: ${subject}${kind} — Fixable: ${fixable}`,
889
+ };
890
+ }
891
+ /** The report's verdict from its gaps: a decision one gap still needs (`null`) outranks one it refuses. */
892
+ const verdictOf = (gaps) => gaps.length === 0
893
+ ? "PASS"
894
+ : gaps.some((g) => g.fixable === null)
895
+ ? null
896
+ : gaps.some((g) => g.fixable === false)
897
+ ? "FAIL"
898
+ : "CONCERNS";
899
+ /** The gap for a task whose only test field is a TEST EXCEPTION that is not honoured. */
900
+ export const EXCEPTION_REFUSED = "exception-refused";
901
+ /** The status row step plan-execute's finish writes; its commit carries the code of each task its log records DONE. */
902
+ export const PLAN_TASKS_STEP = "build-plan-tasks";
903
+ const repoRel = (top, cwd, p) => path.relative(top, path.resolve(cwd, p)).split(path.sep).join("/");
904
+ /**
905
+ * The task numbers a plan-execute log records `DONE — TASK N` for, in log order. `verbs`
906
+ * widens the reader to the log's other closing lines (`BLOCKED`), so one parser serves
907
+ * every caller; the default reads `DONE` only, which is what "the task is done" means.
908
+ */
909
+ export function doneTasks(log, verbs = ["DONE"]) {
910
+ const closing = verbs.map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
911
+ return [...log.matchAll(new RegExp(`^(?:${closing})\\s*[—–-]+\\s*TASK\\s+(\\d+)\\b`, "gim"))].map((m) => Number(m[1]));
912
+ }
913
+ /**
914
+ * Why a task's `TEST EXCEPTION` lines do not count, or null when they do: every
915
+ * line committed, and last changed by a commit that does not write the status file.
916
+ * Every workflow step commit writes it, so a line riding one is refused; agents are
917
+ * barred from committing, so the remaining commits are human-made.
918
+ */
919
+ function exceptionRefusal(top, plan, lines, statusRel) {
920
+ const blame = git(top, ["blame", "--porcelain", "-L", `${lines[0]},${lines.at(-1)}`, "--", plan]);
921
+ if (blame === null)
922
+ return "the plan file is not committed";
923
+ const shas = new Set([...blame.matchAll(/^([0-9a-f]{40}) \d+ \d+/gm)].map((m) => m[1]));
924
+ if ([...shas].some((s) => /^0+$/.test(s)))
925
+ return "the line is not committed — a human commits it before the build re-runs";
926
+ for (const sha of shas) {
927
+ const files = git(top, ["show", "--name-only", "--format=", sha])?.split("\n") ?? [];
928
+ if (files.includes(statusRel))
929
+ 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`;
930
+ }
931
+ return null;
932
+ }
933
+ const withoutExt = (p) => p.replace(/\.[^./]*$/, "");
934
+ /**
935
+ * Whether a grep hit for `stem` in `file` refers to something other than the files of
936
+ * `targets` (repo-relative): false for a hit inside a target, or a line whose every
937
+ * path-like mention of `stem` resolves to a target. A `./` or `../` path resolves
938
+ * against `file`'s folder; any other path with a `/` matches a target ending in it.
939
+ */
940
+ function namesOldPath(stem, targets) {
941
+ const bare = targets.map(withoutExt);
942
+ const isTarget = (token, file) => {
943
+ const t = withoutExt(token);
944
+ if (t.startsWith("./") || t.startsWith("../"))
945
+ return bare.includes(path.posix.join(path.posix.dirname(file), t));
946
+ return t.includes("/") && bare.some((b) => b === t || b.endsWith(`/${t}`));
947
+ };
948
+ return (file, text) => {
949
+ if (targets.includes(file))
950
+ return false;
951
+ const mentions = text
952
+ .split(/[^\w./@-]+/)
953
+ .filter((tok) => path.posix.basename(withoutExt(tok)) === stem);
954
+ return mentions.length === 0 || mentions.some((tok) => !isTarget(tok, file));
955
+ };
956
+ }
957
+ /** The gap for a DELETE line whose file or symbol the tree still holds or refers to. */
958
+ export const DELETE_STILL_REFERENCED = "delete-still-referenced";
959
+ /**
960
+ * One `delete-still-referenced` gap per DELETE line of `tasks` the tree at `top` still
961
+ * holds: a file-only line whose file exists, or whose file name (no extension) a tracked
962
+ * or untracked file names as a word; a symbol (a dotted key's last segment) named as a
963
+ * word; a `§ heading` written as `§ heading`, or still a heading of its file. The plan
964
+ * file and the folder it sits in are not searched. A line naming what a task of
965
+ * `planTasks` CREATEs is a move, not checked. A file-only line whose file name a CREATE
966
+ * of `planTasks` reuses is a file move: the created file, and lines whose every mention
967
+ * of the name is a path to the created file, are not references. A word search hits
968
+ * other things of the same name, so this is a gap for verify to judge, never a refusal.
969
+ */
970
+ function deleteGaps(top, planRel, tasks, planTasks) {
971
+ const created = planTasks.flatMap((t) => t.create);
972
+ const planDir = path.posix.dirname(planRel);
973
+ const excludes = [`:(exclude)${planRel}`, ...(planDir === "." ? [] : [`:(exclude)${planDir}`])];
974
+ const grep = (term, word, keep) => {
975
+ const res = spawnSync("git", [
976
+ "grep",
977
+ "-n",
978
+ "-z",
979
+ "-I",
980
+ "--untracked",
981
+ ...(word ? ["-w"] : []),
982
+ "-F",
983
+ "-e",
984
+ term,
985
+ "--",
986
+ ".",
987
+ ...excludes,
988
+ ], { cwd: top, encoding: "utf-8" });
989
+ if (res.status === 1)
990
+ return { hits: [] };
991
+ if (res.status !== 0)
992
+ return {
993
+ failed: `git grep exited ${res.status ?? res.signal}: ${(res.stderr ?? "").trim()}`,
994
+ };
995
+ const hits = res.stdout
996
+ .split("\n")
997
+ .filter(Boolean)
998
+ .map((l) => l.split("\0"))
999
+ .filter(([file, , text]) => keep === undefined || keep(file, text ?? ""))
1000
+ .map((parts) => parts.slice(0, 2).join(":"));
1001
+ return { hits };
1002
+ };
1003
+ const listed = (hits) => hits
1004
+ .slice(0, 5)
1005
+ .map((h) => `\`${h}\``)
1006
+ .join(", ") + (hits.length > 5 ? `, and ${hits.length - 5} more` : "");
1007
+ const gaps = [];
1008
+ for (const t of tasks)
1009
+ for (const ref of t.delete) {
1010
+ const file = path.posix.normalize(ref.file);
1011
+ const moved = created.some((c) => ref.symbol === undefined ? path.posix.normalize(c.file) === file : c.symbol === ref.symbol);
1012
+ if (moved)
1013
+ continue;
1014
+ const movedTo = ref.symbol === undefined
1015
+ ? created
1016
+ .filter((c) => c.symbol === undefined &&
1017
+ path.posix.basename(path.posix.normalize(c.file)) === path.posix.basename(file))
1018
+ .map((c) => path.posix.normalize(c.file))
1019
+ : [];
1020
+ const gap = (detail) => gaps.push(gapOf(t.task, DELETE_STILL_REFERENCED, detail));
1021
+ const abs = path.join(top, file);
1022
+ const exists = fs.statSync(abs, { throwIfNoEntry: false })?.isFile() === true;
1023
+ let what;
1024
+ let found;
1025
+ if (ref.symbol === undefined) {
1026
+ if (exists) {
1027
+ gap(`DELETE \`${ref.file}\`: the file still exists`);
1028
+ continue;
1029
+ }
1030
+ const stem = path.posix.basename(file).replace(/\.[^.]*$/, "");
1031
+ what = `DELETE \`${ref.file}\` is still referenced as \`${stem}\``;
1032
+ found = grep(stem, true, movedTo.length === 0 ? undefined : namesOldPath(stem, movedTo));
1033
+ }
1034
+ else if (ref.symbol.startsWith("§")) {
1035
+ const heading = ref.symbol.replace(/^§\s*/, "").trim();
1036
+ what = `DELETE ${ref.symbol} in \`${ref.file}\` is still referenced`;
1037
+ found = grep(`§ ${heading}`, false);
1038
+ if (exists && found.hits !== undefined)
1039
+ found.hits.push(...headingLines(fs.readFileSync(abs, "utf-8"), heading).map((n) => `${file}:${n}`));
1040
+ }
1041
+ else {
1042
+ const bare = ref.symbol.replace(/\(\)$/, "");
1043
+ what = `DELETE \`${ref.symbol}\` in \`${ref.file}\` is still referenced`;
1044
+ found = grep(bare.split(".").at(-1), true);
1045
+ }
1046
+ if (found.failed !== undefined)
1047
+ gap(`${what.replace(/ is still referenced.*$/, "")}: references not checked — ${found.failed}`);
1048
+ else if (found.hits.length > 0)
1049
+ gap(`${what}: ${listed([...new Set(found.hits)].sort())}`);
1050
+ }
1051
+ return gaps;
1052
+ }
1053
+ /** The `Updated` entry for a planned test: its own lines at `base` against the file now. */
1054
+ function updatedEntry(top, task, t, base) {
1055
+ const entry = { task, test: t.test, name: t.name, base, additive: null, diff: null };
1056
+ if (base === null)
1057
+ return entry;
1058
+ const shown = runGit(top, ["show", `${base}:${t.test}`]);
1059
+ const abs = path.join(top, t.test);
1060
+ if (!shown.ok || !fs.existsSync(abs))
1061
+ return entry;
1062
+ const was = testBlock(shown.stdout, t.name);
1063
+ const now = testBlock(fs.readFileSync(abs, "utf-8"), t.name);
1064
+ if (was === null || now === null)
1065
+ return entry;
1066
+ const d = lineDiff(was, now);
1067
+ return { ...entry, additive: d.removed === 0, diff: d.text };
1068
+ }
1069
+ /** Every PASSES line of a tests step's log: the tests the writer saw passing and vouches for. */
1070
+ function passesLines(log) {
1071
+ return [
1072
+ ...log.matchAll(/^PASSES\s*[—–-]+\s*TASK\s+(\d+):\s*`([^`]+)`\s+`([^`]+)`\s*:\s*(.+)$/gm),
1073
+ ].map((m) => ({
1074
+ task: Number(m[1]),
1075
+ test: m[2].trim(),
1076
+ name: m[3].trim(),
1077
+ reason: m[4].trim(),
1078
+ }));
1079
+ }
1080
+ /** Why a plan cannot be read for its tests (no file, no task markers, a fence never closed), or undefined. */
1081
+ const planRefusal = (plan, parsed) => plan === undefined
1082
+ ? `no plan file; ${NO_MARKERS_REASON}`
1083
+ : parsed.tasks.length === 0
1084
+ ? parsed.fenceOpen === undefined
1085
+ ? NO_MARKERS_REASON
1086
+ : fenceNeverClosed(parsed.fenceOpen)
1087
+ : undefined;
1088
+ /** A table cell: pipes escaped, line breaks folded. */
1089
+ const cell = (s) => s.replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
1090
+ function writeRedReport(log, o) {
1091
+ const red = o.tests.filter((t) => t.state === "red" || t.state === "red-not-loaded").length;
1092
+ const accepted = o.tests.filter((t) => t.state === "passed-accepted").length;
1093
+ const updated = o.tests.filter((t) => t.state === "updated").length;
1094
+ const out = [
1095
+ `Enforced: ${o.enforced}`,
1096
+ `Red: ${red}`,
1097
+ `Accepted: ${accepted}`,
1098
+ `Updated: ${updated}`,
1099
+ `Gaps: ${o.gaps.length}`,
1100
+ "",
1101
+ "<!-- verdict:end -->",
1102
+ "",
1103
+ `# Tests Red — group ${o.group}, attempt ${o.attempt}`,
1104
+ "",
1105
+ ];
1106
+ if (o.plan)
1107
+ out.push(`Plan: \`${o.plan}\``, "");
1108
+ if (!o.enforced)
1109
+ out.push(`Not enforced: ${o.reason}.`, "");
1110
+ if (o.tests.length > 0) {
1111
+ out.push("| Task | Test | State | Detail |", "| --- | --- | --- | --- |");
1112
+ for (const t of o.tests)
1113
+ out.push(`| ${t.task} | \`${t.test}\` "${cell(t.testName)}" | ${t.state} | ${cell(o.details.get(t) ?? "")} |`);
1114
+ out.push("");
1115
+ }
1116
+ out.push("## Gaps", "");
1117
+ if (o.gaps.length === 0)
1118
+ out.push("None.");
1119
+ for (const g of o.gaps)
1120
+ out.push(`- TASK ${g.task} \`${g.test}\` "${g.name}" \`${g.kind}\` — ${g.detail}`);
1121
+ for (const t of o.outputs) {
1122
+ const fence = fenceFor(t.text);
1123
+ out.push("", `## ${t.title}`, "", fence, t.text.replace(/\n$/, ""), fence);
1124
+ }
1125
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1126
+ fs.writeFileSync(log, `${out.join("\n")}\n`);
252
1127
  }
253
1128
  function writeAuditReport(log, o) {
254
- const out = [`Enforced: ${o.enforced}`, `Gaps: ${o.gaps.length}`, "", "<!-- verdict:end -->", ""];
1129
+ const out = [
1130
+ `Enforced: ${o.enforced}`,
1131
+ `Verdict: ${o.verdict}`,
1132
+ `Gaps: ${o.gaps.length}`,
1133
+ `Unproven: ${o.unproven.length}`,
1134
+ "",
1135
+ "<!-- verdict:end -->",
1136
+ "",
1137
+ ];
255
1138
  out.push("# Test-First Audit", "");
256
1139
  if (o.plan)
257
1140
  out.push(`Plan: \`${o.plan}\``, "");
258
1141
  if (!o.enforced)
259
1142
  out.push(`Not enforced: ${o.reason}.`, "");
260
1143
  if (o.rows.length > 0) {
261
- out.push("| Task | Test | Red | Changed since red | Green |", "| --- | --- | --- | --- | --- |");
1144
+ out.push("| Task | Test | Red | Green |", "| --- | --- | --- | --- |");
262
1145
  for (const r of o.rows)
263
- out.push(`| ${r.task} | ${r.test} | ${r.red} | ${r.changed} | ${r.green} |`);
1146
+ out.push(`| ${r.task} | ${r.test} | ${r.red} | ${r.green} |`);
264
1147
  out.push("");
265
1148
  }
266
1149
  out.push("## Gaps", "");
267
1150
  if (o.gaps.length === 0)
268
1151
  out.push("None.");
269
1152
  for (const g of o.gaps)
270
- out.push(`- Task ${g.task} \`${g.kind}\` — ${g.detail}`);
271
- for (const d of o.diffs) {
272
- const fence = fenceFor(d.diff);
273
- out.push("", `## Diff since red — Task ${d.task} \`${d.test}\``, "", `${fence}diff`, d.diff, fence);
1153
+ out.push(`- ${g.task === null ? "Plan" : `Task ${g.task}`} \`${g.kind}\` — ${g.detail} — Fixable: ${g.fixable} — log: ${g.logLine}`);
1154
+ if (o.exceptions.length > 0)
1155
+ out.push("", "## Test exceptions", "");
1156
+ for (const e of o.exceptions)
1157
+ out.push(e.refusal === null
1158
+ ? `- Task ${e.task} — honoured; cleared ${e.cleared.length > 0 ? e.cleared.join(", ") : "nothing"}`
1159
+ : `- Task ${e.task} — not honoured: ${e.refusal}`);
1160
+ if (o.landed.length > 0)
1161
+ out.push("", "## Already landed", "");
1162
+ for (const l of o.landed)
1163
+ out.push(`- Task ${l.task} \`${l.test}\` "${l.name}" — passed at the group's red, and the tests step accepted it: ${l.reason}; no red is due`);
1164
+ if (o.updated.length > 0)
1165
+ out.push("", "## Updated tests", "");
1166
+ for (const u of o.updated) {
1167
+ const since = u.base === null ? "" : ` since \`${u.base.slice(0, 9)}\``;
1168
+ const judged = u.additive === null
1169
+ ? "its lines at the base commit could not be read, so read the group diff"
1170
+ : u.additive
1171
+ ? "additive: no line of the test was removed, so no expectation was dropped — read the added lines for one that disables an earlier expectation"
1172
+ : "not additive: a line of the test was removed or changed — read the diff for an expectation removed or loosened";
1173
+ out.push(`- Task ${u.task} \`${u.test}\` "${u.name}" — an existing test the tests step changed${since}; the update may add expectations, never remove or loosen one. ${judged}`);
1174
+ if (u.diff !== null) {
1175
+ const fence = fenceFor(u.diff);
1176
+ out.push("", ` ${fence}diff`, ...u.diff.split("\n").map((l) => ` ${l}`), ` ${fence}`, "");
1177
+ }
274
1178
  }
1179
+ if (o.unproven.length > 0)
1180
+ out.push("", "## Unproven", "");
1181
+ for (const u of o.unproven)
1182
+ out.push(`- Task ${u.task} \`${u.test}\` "${u.name}" — ${u.detail}; the owner answers it at the end of the build`);
275
1183
  for (const t of o.outputs) {
276
1184
  const fence = fenceFor(t.tail);
277
1185
  out.push("", `## Runner output — \`${t.test}\``, "", fence, t.tail, fence);
@@ -283,8 +1191,10 @@ export const testsCommand = {
283
1191
  noun: "tests",
284
1192
  summary: "Run the deepest declared local gate, or one test file to record a red and audit a green.",
285
1193
  verbs: {
1194
+ changed: testsChangedVerb,
286
1195
  run: {
287
- summary: "Run the first declared --gate; exit 0 PASS, 1 FAIL, 4 could not run.",
1196
+ summary: "Run the first declared --gate, and with --file append a test-run status row for the run; exit 0 PASS, 1 FAIL, 4 could not run, 81 tests lock held.",
1197
+ use: "by-hand",
288
1198
  flags: [
289
1199
  {
290
1200
  name: "gate",
@@ -304,25 +1214,172 @@ export const testsCommand = {
304
1214
  type: "string",
305
1215
  help: `lines of the log echoed to stderr afterwards (default ${DEFAULT_TAIL}; 0 for none)`,
306
1216
  },
1217
+ {
1218
+ name: "lock-wait-s",
1219
+ type: "string",
1220
+ help: "whole-number lock wait >= 0, passed as LOCAL_STACK_LOCK_WAIT_S (default BKIT_LOCK_WAIT_S, else 60)",
1221
+ },
1222
+ {
1223
+ name: "artifact",
1224
+ type: "string",
1225
+ help: "copy the log here, trim the copy (debug-evidence) and record the clamp; needs --fid and --step",
1226
+ },
1227
+ { name: "fid", type: "string", help: "--artifact: feature id, for the clamp log" },
1228
+ {
1229
+ name: "step",
1230
+ type: "string",
1231
+ help: "step name: the test-run row's (--file) and the clamp log's (--artifact)",
1232
+ },
1233
+ {
1234
+ name: "attempt",
1235
+ type: "string",
1236
+ help: "attempt: on the test-run row (--file) and in the clamp log's name (--artifact)",
1237
+ },
1238
+ {
1239
+ name: "file",
1240
+ type: "string",
1241
+ help: "status.jsonl: append one test-run row for this run, pass or fail; needs --workflow and --step",
1242
+ },
1243
+ { name: "workflow", type: "string", help: "--file: workflow name, for the test-run row" },
1244
+ { name: "ci-run", type: "string", help: "selected GitHub evidence run ID" },
1245
+ { name: "ci-url", type: "string", help: "selected GitHub evidence attempt URL" },
307
1246
  ],
308
1247
  output: {
1248
+ source: "ci for pinned red evidence; local for every executed gate",
1249
+ runAttempt: "selected CI attempt for a CI evidence round",
1250
+ ciGeneration: "active selection generation for a CI evidence round",
1251
+ ciRun: "selected CI run ID for a CI evidence round",
1252
+ ciUrl: "selected CI attempt URL for a CI evidence round",
1253
+ repo: "selected repository for a CI evidence round",
1254
+ workflowId: "selected workflow ID for a CI evidence round",
1255
+ workflowPath: "selected workflow path for a CI evidence round",
1256
+ headSha: "selected commit for a CI evidence round",
309
1257
  verdict: "PASS | FAIL (null when the gate could not run)",
310
1258
  exitCode: "the gate's exit code",
311
1259
  gate: "the script that ran",
312
1260
  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)",
1261
+ 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)`,
1262
+ reports: `{log}.reports — emptied before the run and passed to the gate as $${REPORT_DIR_ENV}`,
1263
+ log: "where the full output was saved (as given); the untouched original",
315
1264
  logBytes: "size of the saved output",
1265
+ artifact: "--artifact as given, else null",
1266
+ clamp: "the artifact's clamp record (raw = the log, source = scope), else null",
1267
+ row: `the ${TEST_RUN_ROW} row appended to --file ({type, workflow, at, step, attempt?, run, verdict, exitCode, failures, scope, log, artifact?}; run = this step's test-run rows in the workflow's active run, this one included), else null; a tests-lock wait writes no row`,
1268
+ lockHolder: "tests-lock holder when the wait gave up, else null",
316
1269
  },
1270
+ textOmit: ["clamp", "row"],
317
1271
  exitCodes: {
318
1272
  [EXIT_NO_GATE]: "no candidate gate is declared in package.json",
319
1273
  [EXIT_COULD_NOT_RUN]: "the gate could not run (exit 126 / 127): not a test failure",
1274
+ [EXIT_ARTIFACT_STEP]: "--artifact could not be written, trimmed or recorded",
320
1275
  },
321
1276
  run: (ctx) => {
1277
+ const waitSource = ctx.flags.lockWaitS ?? process.env.BKIT_LOCK_WAIT_S;
1278
+ const waitS = wholeNumber(waitSource, ctx.flags.lockWaitS === undefined && process.env.BKIT_LOCK_WAIT_S !== undefined
1279
+ ? "lock-wait-s (BKIT_LOCK_WAIT_S)"
1280
+ : "lock-wait-s", 60);
322
1281
  const candidates = ctx.flags.gate;
323
1282
  const logArg = String(ctx.flags.log);
324
1283
  if (logArg === "")
325
1284
  throw new CommandError(EXIT.USAGE, "--log must be non-empty");
1285
+ const artifact = str(ctx.flags.artifact);
1286
+ const fid = str(ctx.flags.fid);
1287
+ const step = str(ctx.flags.step);
1288
+ const attempt = positiveInt(ctx.flags.attempt, "attempt");
1289
+ if (artifact !== undefined && (!fid || !step))
1290
+ throw new CommandError(EXIT.USAGE, "--artifact needs --fid and --step");
1291
+ const statusArg = str(ctx.flags.file);
1292
+ const workflow = str(ctx.flags.workflow);
1293
+ if (statusArg !== undefined && (!workflow || !step))
1294
+ throw new CommandError(EXIT.USAGE, "--file needs --workflow and --step");
1295
+ const status = statusArg === undefined ? undefined : path.resolve(ctx.cwd, statusArg);
1296
+ if (status !== undefined && !fs.existsSync(status))
1297
+ throw new CommandError(EXIT.USAGE, `--file ${statusArg} does not exist (a test-run row never starts a log)`);
1298
+ if (ctx.flags.ciRun !== undefined || ctx.flags.ciUrl !== undefined) {
1299
+ const active = status === undefined ? undefined : readRuns(status).at(-1);
1300
+ const selection = active?.ciSelection;
1301
+ if (!status ||
1302
+ workflow !== "debug" ||
1303
+ active?.workflow !== "debug" ||
1304
+ active.status !== "IN_PROGRESS" ||
1305
+ !validateCiSelection(selection) ||
1306
+ selection.mode !== "ci" ||
1307
+ ctx.flags.ciRun !== selection.runId ||
1308
+ ctx.flags.ciUrl !== selection.runUrl ||
1309
+ !Number.isSafeInteger(active.ciGeneration) ||
1310
+ Number(active.ciGeneration) < 1 ||
1311
+ !artifact)
1312
+ throw new CommandError(EXIT.USAGE, "CI round needs an active matching debug selection and artifact");
1313
+ const fixed = active.steps.some((s) => s.status === "DONE" &&
1314
+ s.ciGeneration === active.ciGeneration &&
1315
+ ["debug-failure-remediate", "debug-failure-soak"].includes(s.step));
1316
+ if (!fixed) {
1317
+ const scope = `ci:${selection.runId}`;
1318
+ const text = [
1319
+ "Verdict: FAIL",
1320
+ "Source: ci",
1321
+ `Scope: ${scope}`,
1322
+ `Repository: ${selection.repo}`,
1323
+ `Workflow: ${selection.workflowPath} (${selection.workflowId})`,
1324
+ `Run: ${selection.runId}`,
1325
+ `Run attempt: ${selection.runAttempt}`,
1326
+ `CI generation: ${active.ciGeneration}`,
1327
+ `Commit: ${selection.headSha}`,
1328
+ `URL: ${selection.runUrl}`,
1329
+ "",
1330
+ "<!-- verdict:end -->",
1331
+ "",
1332
+ "# CI evidence",
1333
+ "",
1334
+ "The local gate was not run.",
1335
+ "",
1336
+ ].join("\n");
1337
+ for (const dest of new Set([artifact, logArg])) {
1338
+ const out = path.resolve(ctx.cwd, dest);
1339
+ fs.mkdirSync(path.dirname(out), { recursive: true });
1340
+ fs.writeFileSync(out, text);
1341
+ }
1342
+ const evidence = {
1343
+ gate: null,
1344
+ ciRun: selection.runId,
1345
+ ciUrl: selection.runUrl,
1346
+ runAttempt: selection.runAttempt,
1347
+ ciGeneration: active.ciGeneration,
1348
+ repo: selection.repo,
1349
+ workflowId: selection.workflowId,
1350
+ workflowPath: selection.workflowPath,
1351
+ headSha: selection.headSha,
1352
+ };
1353
+ const row = appendTestRun(status, {
1354
+ workflow,
1355
+ step: step,
1356
+ attempt,
1357
+ source: "ci",
1358
+ verdict: "FAIL",
1359
+ exitCode: null,
1360
+ failures: null,
1361
+ scope,
1362
+ log: logArg,
1363
+ artifact,
1364
+ evidence,
1365
+ });
1366
+ ctx.emit({
1367
+ source: "ci",
1368
+ verdict: "FAIL",
1369
+ scope,
1370
+ exitCode: null,
1371
+ failures: null,
1372
+ ...evidence,
1373
+ artifact,
1374
+ log: logArg,
1375
+ logBytes: Buffer.byteLength(text),
1376
+ reports: null,
1377
+ clamp: null,
1378
+ row,
1379
+ });
1380
+ return EXIT.NO;
1381
+ }
1382
+ }
326
1383
  const tailRaw = str(ctx.flags.tail) ?? String(DEFAULT_TAIL);
327
1384
  if (!/^[0-9]+$/.test(tailRaw)) {
328
1385
  throw new CommandError(EXIT.USAGE, `--tail must be a non-negative integer, got "${tailRaw}"`);
@@ -340,23 +1397,95 @@ export const testsCommand = {
340
1397
  }
341
1398
  const scope = gateScope(gate);
342
1399
  const log = path.resolve(ctx.cwd, logArg);
1400
+ const reports = freshReportDir(log);
343
1401
  ctx.log(`running ${scope} — full output in ${logArg}`);
344
- const exitCode = runToLog(scriptCommand(gate), top, log);
345
- for (const line of Number(tailRaw) > 0 ? tailLines(log, Number(tailRaw)) : [])
1402
+ const fetchedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
1403
+ const who = ["bkit tests run", gate, fid, step].filter(Boolean).join(" ");
1404
+ const exitCode = runToLog(scriptCommand(gate), top, log, {
1405
+ [REPORT_DIR_ENV]: reports,
1406
+ LOCAL_STACK_LOCK_WAIT_S: String(waitS),
1407
+ LOCAL_STACK_LOCK_WHO: who,
1408
+ });
1409
+ const logText = fs.readFileSync(log, "utf-8");
1410
+ const lockExit = classifyLockExit({ exitCode, log: logText, who });
1411
+ const lockWait = lockExit === "lock-wait";
1412
+ const lockHolder = lockWait ? testsLockHolder(logText, who) : null;
1413
+ const lines = lockExit === "gate"
1414
+ ? Number(tailRaw) > 0
1415
+ ? tailLines(log, Number(tailRaw))
1416
+ : []
1417
+ : logText.split(/\r?\n/).filter((line) => line.startsWith("[machine-lock]"));
1418
+ for (const line of lines)
346
1419
  ctx.log(line);
347
- const couldNotRun = COULD_NOT_RUN_EXIT_CODES.has(exitCode);
348
- const verdict = couldNotRun ? null : exitCode === 0 ? "PASS" : "FAIL";
1420
+ const couldNotRun = lockExit === "could-not-run" || COULD_NOT_RUN_EXIT_CODES.has(exitCode);
1421
+ const verdict = couldNotRun || lockWait ? null : exitCode === 0 ? "PASS" : "FAIL";
1422
+ const counted = lockExit === "gate" ? countReportFailures(reports) : null;
1423
+ if (counted === null && lockExit === "gate")
1424
+ ctx.log(NO_REPORT_HINT);
1425
+ else if (verdict === "FAIL" && counted === 0)
1426
+ ctx.log(`the JUnit reports in $${REPORT_DIR_ENV} hold no failing case — the gate failed outside its reported tests; failures unknown`);
1427
+ const failures = verdict === "PASS" ? 0 : counted !== null && counted > 0 ? counted : null;
1428
+ let clamp = null;
1429
+ let artifactFailed = null;
1430
+ if (artifact !== undefined && !lockWait) {
1431
+ try {
1432
+ const out = path.resolve(ctx.cwd, artifact);
1433
+ fs.mkdirSync(path.dirname(out), { recursive: true });
1434
+ fs.copyFileSync(log, out);
1435
+ const clampLog = clampLogPath(ctx.cwd, fid, step, attempt);
1436
+ fs.mkdirSync(path.dirname(clampLog), { recursive: true });
1437
+ fs.writeFileSync(clampLog, "");
1438
+ clamp = clampFile(out, "debug-evidence", artifact, {
1439
+ rawDir: null,
1440
+ source: scope,
1441
+ fetchedAt,
1442
+ original: log,
1443
+ });
1444
+ appendRecord(clampLog, clamp);
1445
+ }
1446
+ catch (err) {
1447
+ // The verdict stands; the step's artifact is what failed.
1448
+ clamp = null;
1449
+ artifactFailed = err.message;
1450
+ }
1451
+ }
1452
+ const row = status === undefined || lockWait
1453
+ ? null
1454
+ : appendTestRun(status, {
1455
+ workflow: workflow,
1456
+ step: step,
1457
+ attempt,
1458
+ verdict,
1459
+ exitCode,
1460
+ failures,
1461
+ scope,
1462
+ log: logArg,
1463
+ artifact,
1464
+ source: "local",
1465
+ });
349
1466
  ctx.emit({
1467
+ source: "local",
350
1468
  verdict,
351
1469
  exitCode,
352
1470
  gate,
353
1471
  scope,
354
- failures: verdict === "PASS" ? 0 : null,
1472
+ failures,
1473
+ reports: `${logArg}.reports`,
355
1474
  log: logArg,
356
1475
  logBytes: fs.statSync(log).size,
1476
+ artifact: lockWait ? null : (artifact ?? null),
1477
+ clamp,
1478
+ row,
1479
+ lockHolder,
357
1480
  });
1481
+ if (artifactFailed !== null) {
1482
+ ctx.log(`--artifact ${artifact}: ${artifactFailed}`);
1483
+ return EXIT_ARTIFACT_STEP;
1484
+ }
1485
+ if (lockWait)
1486
+ return EXIT.AGENT_WAIT;
358
1487
  if (couldNotRun) {
359
- ctx.log(`${scope} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no tests executed; this is not a FAIL verdict`);
1488
+ ctx.log(`${scope} could not run (exit ${exitCode}: ${lockExit === "could-not-run" ? "tests lock refused" : exitCode === 126 ? "not executable" : "command not found"}) — no tests executed; this is not a FAIL verdict`);
360
1489
  return EXIT_COULD_NOT_RUN;
361
1490
  }
362
1491
  ctx.log(`verdict ${verdict} (exit ${exitCode})`);
@@ -364,126 +1493,275 @@ export const testsCommand = {
364
1493
  },
365
1494
  },
366
1495
  red: {
367
- summary: "Run a task's new test before its code exists; exit 0 red recorded, 1 not a red (the named test did not run, passed, or was skipped).",
1496
+ summary: "Run every TEST FIRST test of one group's open tasks before any task code exists, and write one build-tests-red row holding a state and blob per planned test; a test an earlier row of the group proved red, its file unchanged since, is not run again. Exit 0 every test red, 1 a gap (a test passing, absent from its report, failing lint, or its file missing), 3 bkit:test:file undeclared (blobs recorded, nothing ran), 4 a script could not run.",
1497
+ use: "workflow",
368
1498
  flags: [
369
1499
  FILE_FLAG,
370
1500
  WORKFLOW_FLAG,
371
- SUB_PLAN_FLAG,
372
1501
  {
373
- name: "task",
374
- type: "string",
1502
+ ...GROUP_FLAG,
375
1503
  required: true,
376
- help: "plan task number (positive integer)",
1504
+ help: "the group whose planned tests run (positive integer)",
377
1505
  },
378
1506
  {
379
- name: "test",
1507
+ name: "plan",
380
1508
  type: "string",
381
1509
  required: true,
382
- help: "the test file, repo-relative — passed whole to bkit:test:file",
1510
+ repeatable: true,
1511
+ help: "candidate plan file; the first that exists is read",
383
1512
  },
384
1513
  {
385
- name: "name",
1514
+ name: "log",
386
1515
  type: "string",
387
1516
  required: true,
388
- help: "the test's name as the runner reports it, or its last segment",
1517
+ help: "file the red report is written to (directories are created)",
389
1518
  },
390
1519
  {
391
- name: "log",
1520
+ name: "writer-log",
392
1521
  type: "string",
393
- required: true,
394
- help: "file the runner output is saved to; the test file's copy lands beside it as .snapshot",
1522
+ help: "the tests step's log: a `PASSES — TASK N: `file` `name`: reason` line there accepts that test's pass as passed-accepted",
395
1523
  },
396
1524
  ],
397
1525
  output: {
398
- recorded: "true when the red row was written, or already recorded for this unchanged test",
399
- already: "true when an earlier red for this task, test and name stands (test unchanged); nothing ran",
400
- refused: "no-report | not-run | passed | skipped | exit-mismatch (when recorded is false)",
401
- reason: "why the run is not a red (when recorded is false)",
402
- exitCode: "the script's exit code",
403
- row: "the build-task-red row written (when recorded)",
404
- log: "where the runner output was saved (as given)",
1526
+ enforced: "false when bkit:test:file is not declared (the row records the blobs, every state unknown, exit 3) or the plan could not be read (no row, exit 1)",
1527
+ reason: "why test-first is not enforced",
1528
+ attempt: "this group's build-tests-red rows so far, this one included",
1529
+ tests: "[{task, test, testName, state, blob, reason?}] in plan order, the tests run now: state red | red-not-loaded | passed-accepted | vacuous | missing | no-report | lint | unknown; blob the test file's git blob as it stood (null when the file is missing); reason the tests step's, on passed-accepted",
1530
+ skipped: "planned tests an earlier row of the group proved red, their file unchanged since: not run again, and not on this row",
1531
+ gaps: "[{task, test, name, kind, detail}]: every planned test whose state is not red, red-not-loaded or passed-accepted; kind is the state",
1532
+ row: "the build-tests-red row written",
1533
+ log: "where the report was written (as given)",
405
1534
  },
406
1535
  exitCodes: {
407
- [EXIT_NO_GATE]: `${BKIT_TEST_FILE_SCRIPT} is not declared in package.json`,
408
- [EXIT_COULD_NOT_RUN]: "the script could not run (exit 126 / 127)",
1536
+ [EXIT_NO_GATE]: `${BKIT_TEST_FILE_SCRIPT} is not declared in package.json: the row holds the blobs with enforced false, and no test ran`,
1537
+ [EXIT_COULD_NOT_RUN]: "bkit:lint:file or bkit:test:file could not run (exit 126 / 127); nothing written",
409
1538
  },
410
1539
  run: (ctx) => {
411
1540
  const workflow = String(ctx.flags.workflow);
412
- const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
413
- const task = positiveInt(ctx.flags.task, "task");
414
- const name = String(ctx.flags.name).trim();
415
- if (name === "")
416
- throw new CommandError(EXIT.USAGE, "--name must be non-empty");
1541
+ const group = positiveInt(ctx.flags.group, "group");
417
1542
  const logArg = String(ctx.flags.log);
418
1543
  if (logArg === "")
419
1544
  throw new CommandError(EXIT.USAGE, "--log must be non-empty");
1545
+ const log = path.resolve(ctx.cwd, logArg);
420
1546
  const top = toplevel(ctx.cwd);
421
- if (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null) {
422
- ctx.log(`${BKIT_TEST_FILE_SCRIPT} is not declared — ${NO_TEST_FILE_HINT}`);
423
- return EXIT_NO_GATE;
424
- }
425
- const test = repoTestPath(top, String(ctx.flags.test));
426
- const blob = git(top, ["hash-object", "--", test]);
1547
+ const exists = (p) => fs.existsSync(path.resolve(ctx.cwd, p));
1548
+ const plan = ctx.flags.plan.find(exists);
1549
+ const planText = plan ? fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8") : "";
1550
+ const parsed = parsePlanBlocks(planText);
427
1551
  const status = statusFile(ctx);
428
- const prior = fs.existsSync(status)
429
- ? redRows(status, workflow, subPlan)
430
- .reverse()
431
- .find((r) => r.task === task && r.test === test && r.testName === name)
432
- : undefined;
433
- if (prior !== undefined && prior.testBlob === blob) {
434
- const priorLog = Array.isArray(prior.artifacts) ? String(prior.artifacts[0]) : null;
435
- ctx.emit({ recorded: true, already: true, row: prior, log: priorLog });
436
- ctx.log(`red already recorded for task ${task}: "${name}" (test unchanged since)`);
437
- return EXIT.OK;
438
- }
439
- const log = path.resolve(ctx.cwd, logArg);
440
- const { exitCode, cases } = runTestFile(top, test, log);
441
- if (COULD_NOT_RUN_EXIT_CODES.has(exitCode)) {
442
- ctx.log(couldNotRunMessage(exitCode));
443
- return EXIT_COULD_NOT_RUN;
444
- }
445
- const refusal = judgeRed(exitCode, cases, name);
446
- if (refusal !== null) {
447
- ctx.emit({
448
- recorded: false,
449
- refused: refusal.kind,
450
- reason: refusal.reason,
451
- exitCode,
452
- log: logArg,
1552
+ const attempt = redAttempt(status, workflow, group);
1553
+ const refusal = planRefusal(plan, parsed);
1554
+ if (refusal !== undefined) {
1555
+ writeRedReport(log, {
1556
+ enforced: false,
1557
+ reason: refusal,
1558
+ plan,
1559
+ group,
1560
+ attempt,
1561
+ tests: [],
1562
+ details: new Map(),
1563
+ gaps: [],
1564
+ outputs: [],
453
1565
  });
454
- ctx.log(`not a red (${refusal.kind}): ${refusal.reason} — full output in ${logArg}`);
1566
+ ctx.emit({ enforced: false, reason: refusal, attempt, tests: [], gaps: [], log: logArg });
1567
+ ctx.log(`test-first not enforced: ${refusal}`);
455
1568
  return EXIT.NO;
456
1569
  }
457
- const snapshot = snapshotPath(log);
458
- fs.copyFileSync(path.join(top, test), snapshot);
459
- const failed = cases.find((c) => isNamedCase(c.name, name));
1570
+ const g = parsed.groups.find((x) => x.group === group);
1571
+ if (g === undefined)
1572
+ throw new CommandError(EXIT.USAGE, `the plan has no GROUP ${group}`);
1573
+ if (g.tasks.length === 0)
1574
+ throw new CommandError(EXIT.USAGE, `GROUP ${group} has no tasks; nothing to run`);
1575
+ const done = new Set(parsed.tasks.filter((t) => t.done).map((t) => t.task));
1576
+ // A red an earlier row proved stands while the test's own lines are unchanged, so a
1577
+ // retry, a handover or a task added to the group runs only what is left, and an edit
1578
+ // to another test of the same file costs no proof. A test whose lines could not be
1579
+ // found, and rows from before per-test locking, stand while the whole file is unchanged.
1580
+ const proven = redEntries(status, workflow, group);
1581
+ const textOf = (test) => {
1582
+ const abs = path.join(top, test);
1583
+ return fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
1584
+ };
1585
+ const standing = (t) => {
1586
+ const earlier = proven.get(redKey(t.task, t.test, t.testName));
1587
+ if (earlier === undefined || !RED_PROVEN.has(earlier.state))
1588
+ return false;
1589
+ if (earlier.block === undefined || earlier.block === null)
1590
+ return git(top, ["hash-object", "--", t.test]) === earlier.blob;
1591
+ return blockHash(textOf(t.test), t.testName) === earlier.block;
1592
+ };
1593
+ const startSha = groupStartSha(status, workflow, group);
1594
+ /** The test's lines at the group's start commit: it existed before this group's tests step. */
1595
+ const blockAtStart = (t) => {
1596
+ if (startSha === undefined)
1597
+ return null;
1598
+ const shown = runGit(top, ["show", `${startSha}:${t.test}`]);
1599
+ return shown.ok ? blockHash(shown.stdout, t.testName) : null;
1600
+ };
1601
+ const tests = [];
1602
+ let skipped = 0;
1603
+ for (const s of readTestFirst(planText, group)) {
1604
+ if (s.kind !== "test" || done.has(s.task))
1605
+ continue;
1606
+ for (const t of s.tests) {
1607
+ const planned = {
1608
+ task: s.task,
1609
+ test: t.test,
1610
+ testName: t.name,
1611
+ state: "unknown",
1612
+ blob: null,
1613
+ };
1614
+ if (standing(planned))
1615
+ skipped += 1;
1616
+ else
1617
+ tests.push(planned);
1618
+ }
1619
+ }
1620
+ if (skipped > 0)
1621
+ ctx.log(`tests red: ${skipped} planned test(s) already red, not run again`);
1622
+ const enforced = resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) !== null;
1623
+ const lint = resolveGate(top, [BKIT_LINT_FILE_SCRIPT]) !== null;
1624
+ if (enforced && !lint && tests.length > 0)
1625
+ ctx.log(`${BKIT_LINT_FILE_SCRIPT} is not declared — the tests are not linted before their red`);
1626
+ const writerLog = str(ctx.flags.writerLog);
1627
+ const writerPath = writerLog === undefined ? undefined : path.resolve(ctx.cwd, writerLog);
1628
+ const passes = writerPath !== undefined && fs.existsSync(writerPath)
1629
+ ? passesLines(fs.readFileSync(writerPath, "utf-8"))
1630
+ : [];
1631
+ const details = new Map();
1632
+ const outputs = [];
1633
+ const couldNotRun = (script, exitCode) => `${gateScope(script)} could not run (exit ${exitCode}: ${exitCode === 126 ? "not executable" : "command not found"}) — no test executed`;
1634
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bkit-tests-red-"));
1635
+ try {
1636
+ for (const file of [...new Set(tests.map((t) => t.test))]) {
1637
+ const mine = tests.filter((t) => t.test === file);
1638
+ if (!fs.existsSync(path.join(top, file))) {
1639
+ for (const t of mine) {
1640
+ t.state = "missing";
1641
+ details.set(t, `\`${file}\` does not exist`);
1642
+ }
1643
+ continue;
1644
+ }
1645
+ // `-w` stores the file in git: green and `steps finish` read the blob back later.
1646
+ const blob = git(top, ["hash-object", "-w", "--", file]);
1647
+ const text = textOf(file);
1648
+ for (const t of mine) {
1649
+ t.blob = blob;
1650
+ t.block = blockHash(text, t.testName);
1651
+ }
1652
+ if (!enforced)
1653
+ continue;
1654
+ const runLog = path.join(dir, "run.log");
1655
+ if (lint) {
1656
+ const linted = runToLog([...scriptCommand(BKIT_LINT_FILE_SCRIPT), file], top, runLog);
1657
+ outputs.push({
1658
+ title: `Lint output — \`${file}\``,
1659
+ text: fs.readFileSync(runLog, "utf-8"),
1660
+ });
1661
+ if (COULD_NOT_RUN_EXIT_CODES.has(linted)) {
1662
+ ctx.log(couldNotRun(BKIT_LINT_FILE_SCRIPT, linted));
1663
+ return EXIT_COULD_NOT_RUN;
1664
+ }
1665
+ if (linted !== 0) {
1666
+ for (const t of mine) {
1667
+ t.state = "lint";
1668
+ details.set(t, `${BKIT_LINT_FILE_SCRIPT} exited ${linted} on \`${file}\`: fix the test until it lints clean (output below)`);
1669
+ }
1670
+ continue;
1671
+ }
1672
+ }
1673
+ const { exitCode, cases } = runTestFile(top, file, runLog);
1674
+ outputs.push({
1675
+ title: `Runner output — \`${file}\``,
1676
+ text: fs.readFileSync(runLog, "utf-8"),
1677
+ });
1678
+ if (COULD_NOT_RUN_EXIT_CODES.has(exitCode)) {
1679
+ ctx.log(couldNotRun(BKIT_TEST_FILE_SCRIPT, exitCode));
1680
+ return EXIT_COULD_NOT_RUN;
1681
+ }
1682
+ for (const t of mine) {
1683
+ const judged = judgeRed(cases, t.testName, file);
1684
+ const accepted = judged.state === "vacuous"
1685
+ ? passes.find((p) => p.task === t.task && p.test === t.test && p.name === t.testName)
1686
+ : undefined;
1687
+ const before = judged.state === "vacuous" ? blockAtStart(t) : null;
1688
+ if (accepted !== undefined) {
1689
+ t.state = "passed-accepted";
1690
+ t.reason = accepted.reason;
1691
+ details.set(t, `passes; accepted by the tests step: ${accepted.reason}`);
1692
+ }
1693
+ else if (before !== null && before !== t.block) {
1694
+ t.state = "updated";
1695
+ t.base = startSha;
1696
+ details.set(t, `an existing test, changed since the group started (\`${startSha.slice(0, 9)}\`) and passing: the verifier judges its diff — it may add expectations, never remove or loosen one`);
1697
+ }
1698
+ else {
1699
+ t.state = judged.state;
1700
+ details.set(t, judged.detail);
1701
+ }
1702
+ }
1703
+ }
1704
+ }
1705
+ finally {
1706
+ fs.rmSync(dir, { recursive: true, force: true });
1707
+ }
1708
+ const gaps = [];
1709
+ for (const t of tests) {
1710
+ if (RED_PROVEN.has(t.state) || t.state === "unknown")
1711
+ continue;
1712
+ const gap = {
1713
+ task: t.task,
1714
+ test: t.test,
1715
+ name: t.testName,
1716
+ kind: t.state,
1717
+ detail: details.get(t) ?? t.state,
1718
+ };
1719
+ gaps.push(gap);
1720
+ ctx.log(`not a red (${gap.kind}): TASK ${gap.task} \`${gap.test}\` "${gap.name}" — ${gap.detail}`);
1721
+ }
1722
+ writeRedReport(log, {
1723
+ enforced,
1724
+ reason: enforced
1725
+ ? undefined
1726
+ : `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`,
1727
+ plan,
1728
+ group,
1729
+ attempt,
1730
+ tests,
1731
+ details,
1732
+ gaps,
1733
+ outputs,
1734
+ });
460
1735
  const written = writeStepRow(ctx.cwd, {
461
- file: statusFile(ctx),
1736
+ file: status,
462
1737
  workflow,
463
1738
  step: RED_STEP,
464
- subPlan,
465
- artifacts: [path.relative(ctx.cwd, log), path.relative(ctx.cwd, snapshot)],
466
- extras: {
467
- task,
468
- test,
469
- testName: name,
470
- testBlob: blob,
471
- exitCode,
472
- failure: failed.message.slice(0, 200),
473
- },
1739
+ group,
1740
+ attempt,
1741
+ artifacts: [path.relative(ctx.cwd, log)],
1742
+ extras: { enforced, tests },
474
1743
  commit: "none",
475
1744
  }, ctx.log);
476
- ctx.emit({ recorded: true, exitCode, row: written.row, log: logArg });
477
- ctx.log(`red recorded for task ${task}: "${name}" failed (${failed.state})`);
1745
+ ctx.emit({ enforced, attempt, tests, skipped, gaps, row: written.row, log: logArg });
1746
+ if (gaps.length > 0) {
1747
+ ctx.log(`tests red: ${gaps.length} gap(s) — report in ${logArg}`);
1748
+ return EXIT.NO;
1749
+ }
1750
+ if (!enforced) {
1751
+ ctx.log(`${BKIT_TEST_FILE_SCRIPT} is not declared — ${NO_TEST_FILE_HINT}`);
1752
+ return EXIT_NO_GATE;
1753
+ }
1754
+ ctx.log(`tests red: ${tests.length} planned test(s) red — report in ${logArg}`);
478
1755
  return EXIT.OK;
479
1756
  },
480
1757
  },
481
1758
  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.",
1759
+ summary: "Audit a plan's test-first evidence (each TEST FIRST test red at its group's tests step, by the build-tests-red row, or accepted there as passing before any task code; the named test passing now); exit 0 no gaps, 1 gaps or a plan with no task markers.",
1760
+ use: "workflow",
483
1761
  flags: [
484
1762
  FILE_FLAG,
485
1763
  WORKFLOW_FLAG,
486
- SUB_PLAN_FLAG,
1764
+ { ...GROUP_FLAG, help: "audit only this task group's tasks (positive integer)" },
487
1765
  {
488
1766
  name: "plan",
489
1767
  type: "string",
@@ -491,11 +1769,6 @@ export const testsCommand = {
491
1769
  repeatable: true,
492
1770
  help: "candidate plan file; the first that exists is audited",
493
1771
  },
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
1772
  {
500
1773
  name: "log",
501
1774
  type: "string",
@@ -504,10 +1777,14 @@ export const testsCommand = {
504
1777
  },
505
1778
  ],
506
1779
  output: {
507
- enforced: "false when there is nothing to audit (reason says why)",
1780
+ 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
1781
  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",
1782
+ plan: "the plan file audited",
1783
+ verdict: "PASS no gaps | FAIL a gap's fixable is false | CONCERNS every gap's fixable is true | null when a gap needs a diff read, or the audit could not run",
1784
+ gaps: "[{task, kind, detail, fixable, logLine}]: no-test-first | test-first-malformed | test-first-unread (task null: a plan-level format problem) | 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); fixable is null when the gap needs a diff read; logLine is the line the verifier appends",
1785
+ alreadyLanded: "[{task, test, name, reason}]: tests the tests step accepted as passing before any task code (passed-accepted on the red row); no red is due for them",
1786
+ unproven: "[{task, test, name, detail}]: tests with no proven red (no build-tests-red row, or a state other than red, red-not-loaded, updated or passed-accepted) and no honoured TEST EXCEPTION; never a gap — the owner answers them once, at the end of the build",
1787
+ updated: "[{task, test, name, base, additive, diff}]: existing tests the tests step changed (updated on the red row); base is the group's start commit; additive = the test's own lines since base gained lines and lost none (null when a side cannot be read), diff = their unified line diff; the verifier judges each diff — it may add expectations, never remove or loosen one",
511
1788
  log: "where the report was written (as given)",
512
1789
  },
513
1790
  exitCodes: {
@@ -515,42 +1792,66 @@ export const testsCommand = {
515
1792
  },
516
1793
  run: (ctx) => {
517
1794
  const workflow = String(ctx.flags.workflow);
518
- const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
1795
+ const group = positiveInt(ctx.flags.group, "group");
519
1796
  const logArg = String(ctx.flags.log);
520
1797
  if (logArg === "")
521
1798
  throw new CommandError(EXIT.USAGE, "--log must be non-empty");
522
1799
  const log = path.resolve(ctx.cwd, logArg);
523
1800
  const top = toplevel(ctx.cwd);
524
1801
  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: [] };
1802
+ const plan = ctx.flags.plan.find(exists);
1803
+ const planText = plan ? fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8") : "";
1804
+ const parsed = parsePlanBlocks(planText);
1805
+ const specs = readTestFirst(planText, group);
1806
+ // A plan with no task markers is an old-format plan: nothing it says can be audited,
1807
+ // and passing it would let its tests go unchecked.
1808
+ const refusal = planRefusal(plan, parsed);
1809
+ if (refusal === undefined && group !== undefined) {
1810
+ const g = parsed.groups.find((x) => x.group === group);
1811
+ if (g === undefined)
1812
+ throw new CommandError(EXIT.USAGE, `the plan has no GROUP ${group}`);
1813
+ if (g.tasks.length === 0)
1814
+ throw new CommandError(EXIT.USAGE, `GROUP ${group} has no tasks; nothing to audit`);
1815
+ }
1816
+ const reason = refusal ??
1817
+ (resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
1818
+ ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
1819
+ : undefined);
1820
+ const empty = {
1821
+ verdict: null,
1822
+ rows: [],
1823
+ gaps: [],
1824
+ exceptions: [],
1825
+ landed: [],
1826
+ unproven: [],
1827
+ updated: [],
1828
+ outputs: [],
1829
+ };
544
1830
  if (reason !== undefined) {
545
1831
  writeAuditReport(log, { enforced: false, reason, plan, ...empty });
546
- ctx.emit({ enforced: false, reason, plan: plan ?? null, gaps: [], log: logArg });
1832
+ ctx.emit({
1833
+ enforced: false,
1834
+ reason,
1835
+ plan: plan ?? null,
1836
+ verdict: null,
1837
+ gaps: [],
1838
+ alreadyLanded: [],
1839
+ unproven: [],
1840
+ updated: [],
1841
+ log: logArg,
1842
+ });
547
1843
  ctx.log(`test-first not enforced: ${reason}`);
548
- return EXIT.OK;
1844
+ return refusal === undefined ? EXIT.OK : EXIT.NO;
549
1845
  }
550
- const reds = redRows(statusFile(ctx), workflow, subPlan);
1846
+ const reds = redEntries(statusFile(ctx), workflow);
1847
+ const groupOf = (task) => parsed.tasks.find((b) => b.task === task)?.group;
1848
+ const landed = [];
1849
+ const unproven = [];
1850
+ const updated = [];
1851
+ const statusRel = repoRel(top, ctx.cwd, statusFile(ctx));
1852
+ const exceptions = [];
551
1853
  const gaps = [];
552
1854
  const rows = [];
553
- const diffs = [];
554
1855
  const outputs = [];
555
1856
  const greens = new Map();
556
1857
  /** One run per test file; null when the script could not run. */
@@ -572,104 +1873,74 @@ export const testsCommand = {
572
1873
  return run;
573
1874
  };
574
1875
  for (const s of specs) {
575
- if (s.kind === "na")
576
- continue;
577
- if (s.kind !== "test") {
578
- gaps.push({
1876
+ if (s.kind === "na") {
1877
+ const block = parsed.tasks.find((t) => t.task === s.task);
1878
+ if (block.testFirst !== undefined || block.testException === undefined)
1879
+ continue;
1880
+ const refused = exceptionRefusal(top, repoRel(top, ctx.cwd, plan), block.testException.lines, statusRel);
1881
+ exceptions.push({
579
1882
  task: s.task,
580
- kind: s.kind === "missing" ? "no-test-first" : "test-first-malformed",
581
- 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",
1883
+ refusal: refused,
1884
+ cleared: refused === null ? ["the task's `TEST FIRST` check"] : [],
584
1885
  });
1886
+ if (refused !== null)
1887
+ gaps.push(gapOf(s.task, EXCEPTION_REFUSED, `the task's only test field is a \`**TEST EXCEPTION:**\`, not honoured: ${refused}`));
1888
+ continue;
1889
+ }
1890
+ if (s.kind !== "test") {
1891
+ gaps.push(gapOf(s.task, s.kind === "missing" ? "no-test-first" : "test-first-malformed", s.kind === "missing"
1892
+ ? "the task has neither a `**TEST FIRST:**` nor a `**TEST EXCEPTION:**` field"
1893
+ : "`**TEST FIRST:**` is neither `n/a — {reason}` nor one sub-bullet per test naming a backticked test file and test name"));
585
1894
  continue;
586
1895
  }
587
- const taskReds = reds.filter((r) => r.task === s.task);
588
- const planned = (r) => s.tests.some((t) => t.test === r.test && t.name === r.testName);
1896
+ const excepted = s.exception;
1897
+ const exception = excepted === undefined
1898
+ ? undefined
1899
+ : {
1900
+ task: s.task,
1901
+ refusal: exceptionRefusal(top, repoRel(top, ctx.cwd, plan), excepted.lines, statusRel),
1902
+ cleared: [],
1903
+ };
1904
+ if (exception !== undefined)
1905
+ exceptions.push(exception);
589
1906
  for (const t of s.tests) {
590
1907
  const row = {
591
1908
  task: s.task,
592
1909
  test: `\`${t.test}\` "${t.name}"`,
593
- red: "missing",
594
- changed: "—",
1910
+ red: "no row",
595
1911
  green: "—",
596
1912
  };
597
1913
  rows.push(row);
598
- const red = [...taskReds]
599
- .reverse()
600
- .find((r) => r.test === t.test && r.testName === t.name);
601
- const unplanned = taskReds.filter((r) => !planned(r));
602
- if (red === undefined && unplanned.length > 0) {
603
- const recorded = [];
604
- for (const r of unplanned) {
605
- const rTest = String(r.test);
606
- const rName = String(r.testName);
607
- let now = "file missing";
608
- if (fs.existsSync(path.join(top, rTest))) {
609
- const run = greenRun(rTest);
610
- if (run === null)
611
- return EXIT_COULD_NOT_RUN;
612
- const why = judgeGreen(run.cases, rName);
613
- now = why === null ? "passes now" : `not passing: ${why}`;
614
- }
615
- recorded.push(`\`${rTest}\` "${rName}" (${now})`);
616
- }
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
- });
1914
+ const clearing = exception?.refusal === null &&
1915
+ excepted.tests.some((e) => e.test === t.test && e.name === t.name)
1916
+ ? exception
1917
+ : undefined;
1918
+ const gap = (kind, detail) => gaps.push(gapOf(s.task, kind, detail, { file: t.test, name: t.name }));
1919
+ const noRed = (detail) => {
1920
+ if (clearing !== undefined)
1921
+ clearing.cleared.push(`the red for \`${t.test}\` "${t.name}"`);
1922
+ else
1923
+ unproven.push({ task: s.task, test: t.test, name: t.name, detail });
1924
+ };
1925
+ const red = reds.get(redKey(s.task, t.test, t.name));
1926
+ if (red === undefined)
1927
+ noRed(`no tests step recorded a red for it (\`bkit tests red --group=${groupOf(s.task) ?? "N"}\`)`);
1928
+ else if (red.state === "passed-accepted") {
1929
+ row.red = red.state;
1930
+ landed.push({ task: s.task, test: t.test, name: t.name, reason: red.reason ?? "" });
622
1931
  }
623
- 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
- });
1932
+ else if (RED_PROVEN.has(red.state)) {
1933
+ row.red = red.state;
1934
+ if (red.state === "updated")
1935
+ updated.push(updatedEntry(top, s.task, t, red.base ?? null));
629
1936
  }
630
1937
  else {
631
- row.red = `recorded ${String(red.at)}`;
632
- const snap = (Array.isArray(red.artifacts) ? red.artifacts : [])
633
- .map(String)
634
- .find((a) => a.endsWith(".snapshot"));
635
- const snapAbs = snap === undefined ? undefined : path.resolve(ctx.cwd, snap);
636
- const testAbs = path.join(top, t.test);
637
- if (snapAbs === undefined || !fs.existsSync(snapAbs)) {
638
- 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
- });
644
- }
645
- else if (!fs.existsSync(testAbs)) {
646
- row.changed = "deleted";
647
- gaps.push({
648
- task: s.task,
649
- kind: "test-changed",
650
- detail: `\`${t.test}\` no longer exists`,
651
- });
652
- }
653
- 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() });
662
- }
663
- else
664
- row.changed = "no";
1938
+ row.red = red.state;
1939
+ noRed(`the tests step left it as \`${red.state}\`, not red`);
665
1940
  }
666
1941
  if (!fs.existsSync(path.join(top, t.test))) {
667
1942
  row.green = "file missing";
668
- gaps.push({
669
- task: s.task,
670
- kind: "not-green",
671
- detail: `\`${t.test}\` does not exist`,
672
- });
1943
+ gap("not-green", `\`${t.test}\` does not exist`);
673
1944
  continue;
674
1945
  }
675
1946
  const green = greenRun(t.test);
@@ -678,17 +1949,136 @@ export const testsCommand = {
678
1949
  const why = judgeGreen(green.cases, t.name);
679
1950
  row.green = why === null ? "passed" : "not passed";
680
1951
  if (why !== null) {
681
- gaps.push({ task: s.task, kind: "not-green", detail: why });
1952
+ gap("not-green", why);
682
1953
  if (!outputs.some((o) => o.test === t.test))
683
1954
  outputs.push({ test: t.test, tail: green.tail });
684
1955
  }
685
1956
  }
686
1957
  }
687
- writeAuditReport(log, { enforced: true, plan, rows, gaps, diffs, outputs });
688
- ctx.emit({ enforced: true, plan, gaps, log: logArg });
689
- ctx.log(`test-first audit: ${gaps.length} gap(s) — report in ${logArg}`);
1958
+ gaps.push(...deleteGaps(top, repoRel(top, ctx.cwd, plan), parsed.tasks.filter((t) => group === undefined || t.group === group), parsed.tasks));
1959
+ for (const e of parsed.errors)
1960
+ gaps.push(gapOf(null, "test-first-unread", `\`${plan}:${e.line}\` ${e.message} — tests there were not audited; the plan's blocks need fixing`));
1961
+ const verdict = verdictOf(gaps);
1962
+ writeAuditReport(log, {
1963
+ enforced: true,
1964
+ plan,
1965
+ verdict,
1966
+ rows,
1967
+ gaps,
1968
+ exceptions,
1969
+ landed,
1970
+ unproven,
1971
+ updated,
1972
+ outputs,
1973
+ });
1974
+ ctx.emit({
1975
+ enforced: true,
1976
+ plan,
1977
+ verdict,
1978
+ gaps,
1979
+ alreadyLanded: landed,
1980
+ unproven,
1981
+ updated,
1982
+ log: logArg,
1983
+ });
1984
+ ctx.log(`test-first audit: ${gaps.length} gap(s), ${unproven.length} unproven — report in ${logArg}`);
690
1985
  return gaps.length === 0 ? EXIT.OK : EXIT.NO;
691
1986
  },
692
1987
  },
1988
+ "plan-check": {
1989
+ 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, a Supersession Inventory row per DELETE, a \`Task\` on every Derived Test Matrix row and a row per test-bearing task, and that each READ / UPDATE / DELETE file and symbol exists; exit 0 no problems, 1 refused.`,
1990
+ use: "by-hand",
1991
+ flags: [
1992
+ {
1993
+ name: "plan",
1994
+ type: "string",
1995
+ required: true,
1996
+ help: "the plan file checked",
1997
+ },
1998
+ {
1999
+ name: "existence",
2000
+ type: "string",
2001
+ help: "refuse (default): a missing READ / UPDATE / DELETE file or symbol refuses the plan; report: it is listed only",
2002
+ },
2003
+ {
2004
+ name: "log",
2005
+ type: "string",
2006
+ required: true,
2007
+ help: "file the report is written to, `Problems:` header first (directories are created)",
2008
+ },
2009
+ ],
2010
+ output: {
2011
+ plan: "the plan file checked (as given)",
2012
+ groups: "[{group, title, tasks, tests, kb}]: each group's tasks, planned TEST FIRST tests and size",
2013
+ tasks: "[{task, group, tests, files}]: each task's planned tests and distinct test files",
2014
+ problems: "[{line, kind, message}]: format | stray | field | depends | cap | inventory | matrix | supersession | markers — each refuses the plan",
2015
+ existence: "[{line, task, message}]: READ / UPDATE / DELETE files or symbols not found; refuses only with --existence=refuse",
2016
+ existing: "[{line, task, test, name}]: planned tests of open tasks whose name a test in their file already carries; reported only, never refuses",
2017
+ log: "where the report was written (as given)",
2018
+ },
2019
+ run: (ctx) => {
2020
+ const logArg = String(ctx.flags.log);
2021
+ if (logArg === "")
2022
+ throw new CommandError(EXIT.USAGE, "--log must be non-empty");
2023
+ const existenceArg = str(ctx.flags.existence) ?? "refuse";
2024
+ if (existenceArg !== "refuse" && existenceArg !== "report")
2025
+ throw new CommandError(EXIT.USAGE, `--existence must be refuse or report, got "${existenceArg}"`);
2026
+ const plan = String(ctx.flags.plan);
2027
+ const planAbs = path.resolve(ctx.cwd, plan);
2028
+ if (!fs.statSync(planAbs, { throwIfNoEntry: false })?.isFile())
2029
+ throw new CommandError(EXIT.USAGE, `--plan ${plan} does not exist`);
2030
+ const text = fs.readFileSync(planAbs, "utf-8");
2031
+ const caps = planCaps(ctx.cwd);
2032
+ const { groups, sizes, problems } = checkPlanText(text, caps);
2033
+ const existence = planExistence(text, toplevel(ctx.cwd));
2034
+ const existing = existingTestNames(text, toplevel(ctx.cwd));
2035
+ const refused = problems.length > 0 || (existenceArg === "refuse" && existence.length > 0);
2036
+ const out = [
2037
+ `Problems: ${problems.length}`,
2038
+ `Existence: ${existence.length}`,
2039
+ "",
2040
+ "<!-- verdict:end -->",
2041
+ "",
2042
+ "# Plan Check",
2043
+ "",
2044
+ `Plan: \`${plan}\`. Caps: ${capsText(caps)}.`,
2045
+ "",
2046
+ "## Groups",
2047
+ "",
2048
+ ];
2049
+ if (groups.length === 0)
2050
+ out.push("No group blocks read.");
2051
+ else {
2052
+ out.push("| Group | Title | Tasks | TEST FIRST tests | KB |", "| --- | --- | --- | --- | --- |");
2053
+ for (const g of groups)
2054
+ out.push(`| ${g.group} | ${g.title} | ${g.tasks} | ${g.tests} | ${g.kb.toFixed(1)} |`);
2055
+ }
2056
+ if (sizes.length > 0) {
2057
+ out.push("", "## Tasks", "", "| Task | Group | Tests | Test files |", "| --- | --- | --- | --- |");
2058
+ for (const t of sizes)
2059
+ out.push(`| ${t.task} | ${t.group} | ${t.tests} | ${t.files} |`);
2060
+ }
2061
+ out.push("", "## Problems", "");
2062
+ if (problems.length === 0)
2063
+ out.push("None.");
2064
+ for (const p of problems)
2065
+ out.push(`- \`${plan}:${p.line}\` \`${p.kind}\` — ${p.message}`);
2066
+ out.push("", `## Existence (${existenceArg === "refuse" ? "refuses the plan" : "reported only"})`, "");
2067
+ if (existence.length === 0)
2068
+ out.push("None.");
2069
+ for (const e of existence)
2070
+ out.push(`- \`${plan}:${e.line}\` — ${e.message}`);
2071
+ if (existing.length > 0)
2072
+ out.push("", "## Planned test names already in use (reported only)", "");
2073
+ for (const e of existing)
2074
+ out.push(`- \`${plan}:${e.line}\` TASK ${e.task}: \`${e.test}\` already holds a test named "${e.name}" — name the update to it in TEST FIRST, or give the new test a new name`);
2075
+ const log = path.resolve(ctx.cwd, logArg);
2076
+ fs.mkdirSync(path.dirname(log), { recursive: true });
2077
+ fs.writeFileSync(log, `${out.join("\n")}\n`);
2078
+ ctx.emit({ plan, groups, tasks: sizes, problems, existence, existing, log: logArg });
2079
+ ctx.log(`plan check: ${problems.length} problem(s), ${existence.length} existence finding(s)${refused ? " — refused" : ""}; report in ${logArg}`);
2080
+ return refused ? EXIT.NO : EXIT.OK;
2081
+ },
2082
+ },
693
2083
  },
694
2084
  };