@cbartens/bkit 5.2.4 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/.bkit/README.md +27 -11
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +18 -1
  6. package/.bkit/core/.bkit/README.md +26 -10
  7. package/.bkit/core/.bkit/cloud.md +40 -39
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +16 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +346 -0
  12. package/.bkit/core/.bkit/prompts.md +90 -74
  13. package/.bkit/core/.bkit/providers.md +42 -23
  14. package/.bkit/core/.bkit/templates.md +138 -19
  15. package/.bkit/core/.bkit/trackers.md +49 -4
  16. package/.bkit/core/.bkit/workflows.md +144 -123
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -6
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +77 -26
  70. package/.bkit/core/engine/cli.ts +57 -27
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +42 -32
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +73 -130
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  78. package/.bkit/core/engine/commands/land.ts +156 -0
  79. package/.bkit/core/engine/commands/lib.ts +45 -18
  80. package/.bkit/core/engine/commands/registry.ts +2 -0
  81. package/.bkit/core/engine/commands/tips.ts +12 -5
  82. package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
  83. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  84. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  85. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  86. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  88. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  89. package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
  90. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  91. package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
  92. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  93. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  94. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  95. package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
  96. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  97. package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
  98. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
  99. package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
  100. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  101. package/.bkit/core/engine/install/manifest.ts +14 -7
  102. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  103. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  104. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  105. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  106. package/.bkit/core/engine/install/modules/core.ts +106 -70
  107. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  108. package/.bkit/core/engine/install/modules/index.ts +7 -1
  109. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  110. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  111. package/.bkit/core/engine/install/placeholders.ts +16 -35
  112. package/.bkit/core/engine/install/write.ts +59 -12
  113. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  114. package/.bkit/core/engine/render/hosts.ts +47 -67
  115. package/.bkit/core/engine/render/models.ts +29 -11
  116. package/.bkit/core/engine/shared/branches.ts +13 -0
  117. package/.bkit/core/engine/shared/egress.ts +3 -3
  118. package/.bkit/core/engine/shared/json.ts +18 -1
  119. package/.bkit/core/engine/shared/package-json.ts +63 -0
  120. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  121. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  122. package/.bkit/core/engine/shared/settings.ts +44 -0
  123. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  124. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  125. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  126. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  127. package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
  128. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  130. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  132. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  133. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  134. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  135. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  136. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  137. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  138. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  139. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  140. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  141. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  142. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  143. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  144. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  145. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  146. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  148. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  149. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  150. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  151. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  152. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  153. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  154. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  155. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  156. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  157. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  158. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  159. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  160. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  161. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  162. package/.bkit/core/workflows/bkit-auto.md +2 -2
  163. package/.bkit/core/workflows/bkit-build.md +10 -10
  164. package/.bkit/core/workflows/bkit-debug.md +80 -44
  165. package/.bkit/core/workflows/bkit-design.md +22 -13
  166. package/.bkit/core/workflows/bkit-plan.md +33 -16
  167. package/.bkit/core/workflows/bkit-ship.md +87 -98
  168. package/.bkit/shared/.claude/bkit-cloud.md +58 -25
  169. package/.bkit/shared/.claude/settings.json +19 -0
  170. package/.bkit/shared/.cursor/mcp.json +2 -1
  171. package/.bkit/shared/.opencode/opencode.json +19 -1
  172. package/.bkit/shared/docs/deployments.md +49 -29
  173. package/.bkit/shared/docs/security.md +8 -6
  174. package/.bkit/shared/docs/testing.md +9 -5
  175. package/.bkit/shared/gitignore +1 -2
  176. package/.bkit/templates/.cursor/Dockerfile +30 -16
  177. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  178. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  179. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  180. package/.bkit/templates/.github/renovate.json5 +91 -12
  181. package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
  182. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  183. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  184. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  185. package/.bkit/templates/.husky/pre-commit +6 -0
  186. package/.bkit/templates/.husky/pre-push +15 -3
  187. package/.bkit/templates/.lintstagedrc.json +5 -1
  188. package/.bkit/templates/.oxlintrc.json +21 -0
  189. package/.bkit/templates/docs/capabilities.md +1 -1
  190. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  191. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  192. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  193. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  194. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  195. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  196. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  197. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  198. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  199. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  200. package/CHANGELOG.md +98 -3
  201. package/README.md +252 -122
  202. package/dist/checks/after/auth.js +10 -11
  203. package/dist/checks/after/ci-yml.js +11 -14
  204. package/dist/checks/after/github.js +32 -125
  205. package/dist/checks/after/index.js +3 -2
  206. package/dist/checks/after/managed.js +8 -24
  207. package/dist/checks/after/tools.js +3 -16
  208. package/dist/checks/before/context-fetch.js +1 -21
  209. package/dist/checks/before/index.js +6 -42
  210. package/dist/checks/before/mcp.js +14 -9
  211. package/dist/checks/before/repo.js +8 -11
  212. package/dist/checks/status-holes.js +5 -7
  213. package/dist/checks/tips/catalogue.js +65 -18
  214. package/dist/checks/tips/detect.js +41 -2
  215. package/dist/checks/tips/index.js +61 -25
  216. package/dist/cli.js +52 -26
  217. package/dist/commands/analysis.js +21 -5
  218. package/dist/commands/comply.js +40 -31
  219. package/dist/commands/harvest.js +12 -13
  220. package/dist/commands/install/doctor.js +55 -23
  221. package/dist/commands/install/install.js +72 -122
  222. package/dist/commands/install/uninstall.js +165 -31
  223. package/dist/commands/install/upgrade.js +46 -39
  224. package/dist/commands/land.js +129 -0
  225. package/dist/commands/lib.js +41 -16
  226. package/dist/commands/registry.js +2 -0
  227. package/dist/commands/tips.js +10 -3
  228. package/dist/commands/workflow/branches.js +303 -248
  229. package/dist/commands/workflow/counters.js +17 -7
  230. package/dist/commands/workflow/disk.js +452 -0
  231. package/dist/commands/workflow/fids.js +39 -0
  232. package/dist/commands/workflow/issues.js +63 -27
  233. package/dist/commands/workflow/ledgers.js +3 -1
  234. package/dist/commands/workflow/locks.js +35 -130
  235. package/dist/commands/workflow/prs.js +8 -5
  236. package/dist/commands/workflow/repo.js +2 -2
  237. package/dist/commands/workflow/roadmap.js +50 -57
  238. package/dist/commands/workflow/runs.js +5 -5
  239. package/dist/commands/workflow/runtime.js +3 -2
  240. package/dist/commands/workflow/status.js +32 -12
  241. package/dist/commands/workflow/steps.js +19 -11
  242. package/dist/commands/workflow/tests.js +16 -3
  243. package/dist/commands/workflow/workflows.js +390 -249
  244. package/dist/commands/workflow/workstreams.js +4 -2
  245. package/dist/commands/workflow/worktrees.js +15 -6
  246. package/dist/install/cloud-env.js +10 -23
  247. package/dist/install/manifest.js +14 -7
  248. package/dist/install/modules/antigravity.js +15 -26
  249. package/dist/install/modules/claude.js +17 -21
  250. package/dist/install/modules/cloud.js +6 -2
  251. package/dist/install/modules/codex.js +15 -29
  252. package/dist/install/modules/core.js +95 -63
  253. package/dist/install/modules/cursor.js +6 -9
  254. package/dist/install/modules/index.js +6 -1
  255. package/dist/install/modules/opencode.js +41 -72
  256. package/dist/install/network-allowlist.js +62 -0
  257. package/dist/install/placeholders.js +16 -35
  258. package/dist/install/write.js +55 -15
  259. package/dist/ledgers/telemetry.js +5 -4
  260. package/dist/render/hosts.js +30 -55
  261. package/dist/render/models.js +20 -9
  262. package/dist/shared/branches.js +11 -0
  263. package/dist/shared/egress.js +0 -2
  264. package/dist/shared/json.js +14 -0
  265. package/dist/shared/package-json.js +61 -0
  266. package/dist/shared/package-roots.js +0 -8
  267. package/dist/shared/protected-paths.js +5 -122
  268. package/dist/shared/settings.js +23 -1
  269. package/dist/shared/timeouts.js +8 -7
  270. package/package.json +21 -17
  271. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -0,0 +1,21 @@
1
+ {
2
+ "$schema": "./node_modules/oxlint/configuration_schema.json",
3
+ "plugins": [],
4
+ "categories": {
5
+ "correctness": "off"
6
+ },
7
+ "ignorePatterns": [".bkit/templates/**", "scripts/ci/**/*.test.mjs"],
8
+ "overrides": [
9
+ {
10
+ "files": ["**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
11
+ "plugins": ["vitest", "typescript"],
12
+ "rules": {
13
+ "vitest/expect-expect": "error",
14
+ "vitest/no-conditional-in-test": "error",
15
+ "vitest/no-conditional-expect": "error",
16
+ "vitest/valid-expect": ["error", { "maxArgs": 2 }],
17
+ "typescript/no-floating-promises": "error"
18
+ }
19
+ }
20
+ ]
21
+ }
@@ -9,7 +9,7 @@
9
9
  >
10
10
  > **Rules:**
11
11
  >
12
- > - GENERATED. `pnpm graph:update && pnpm graph:rollup` rewrites this file.
12
+ > - GENERATED. `pnpm graph:refresh` rewrites this file.
13
13
  > - Source of truth: `scripts/graphify/bkit-graph-drift-rules.json`. Status is derived from the tree, never typed.
14
14
  > - Markers literal, never regex. Regex metacharacter in a marker matches nothing → reads as clean result.
15
15
  > - Optional `scope`: path prefixes. Optional `surface`: `product` (default), `tests`, or `all`.
@@ -0,0 +1,176 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * check-capstone.mjs — the decision behind the `bkit-tests-check` capstone.
6
+ *
7
+ * Reads the capstone's `needs` context from the environment and reds when green would prove
8
+ * nothing. It fails when:
9
+ * - a lane's result is not `success` (failed, skipped or cancelled),
10
+ * - a lane ran although the plan said skip (`run_level` is `none`),
11
+ * - a lane succeeded having executed 0 tests, or reports a count that is not a number,
12
+ * - the plan does not parse (not JSON, not an object, or no `run_level`),
13
+ * - the planner job (`SCOPE_RESULT`) did not succeed,
14
+ * - no lane is named, or a lane's result was never wired in.
15
+ * It asserts nothing for a lane that `<LANE>_CACHE_SKIP=true` marks as proven on a cached
16
+ * SHA, and nothing about a skipped lane when `run_level` is `none`.
17
+ *
18
+ * Environment:
19
+ * LANES comma-separated lane names, e.g. `static,unit`. The job named
20
+ * `bkit-tests-<lane>` is read from `<LANE>_RESULT` (name upper-cased,
21
+ * `-` becomes `_`: `e2e-web` reads `E2E_WEB_RESULT`).
22
+ * <LANE>_RESULT `needs.<job>.result`.
23
+ * <LANE>_RAN `needs.<job>.outputs.tests_ran`. Setting the variable (even empty)
24
+ * makes the lane counted: it must report a number above 0. A lane
25
+ * with no such variable is not count-checked.
26
+ * <LANE>_CACHE_SKIP `needs.<job>.outputs.cache_skip`; `true` skips the count check.
27
+ * PLAN optional planner JSON (`needs.bkit-tests-scope.outputs.plan`). Unset
28
+ * means every listed lane is expected to run. Set, it must parse and
29
+ * carry a `run_level`; `none` expects every lane to be skipped.
30
+ * SCOPE_RESULT optional `needs.bkit-tests-scope.result`; must be `success`.
31
+ * EMPTY_COUNT `warn` turns a lane that reports no count yet into a warning. Any
32
+ * other value fails it. A count of 0 or a non-number always fails.
33
+ *
34
+ * Usage: node scripts/ci/check-capstone.mjs
35
+ * Exit: 0 = every expectation met, 1 = at least one failure.
36
+ */
37
+
38
+ import path from "node:path";
39
+ import { fileURLToPath } from "node:url";
40
+
41
+ const LANE_NAME = /^[a-z][a-z0-9-]*$/i;
42
+ const PREFIX = (lane) => lane.toUpperCase().replace(/-/g, "_");
43
+
44
+ /** The planner's `run_level` from `raw`, or why `raw` is not a usable plan. */
45
+ function readPlan(raw) {
46
+ let plan;
47
+ try {
48
+ plan = JSON.parse(raw);
49
+ } catch (err) {
50
+ return { runLevel: null, problem: err.message };
51
+ }
52
+ if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
53
+ return { runLevel: null, problem: "not a JSON object" };
54
+ }
55
+ if (typeof plan.run_level !== "string" || plan.run_level === "") {
56
+ return { runLevel: null, problem: "no run_level" };
57
+ }
58
+ return { runLevel: plan.run_level, problem: null };
59
+ }
60
+
61
+ /**
62
+ * Judge the capstone from its environment.
63
+ * @param {Record<string, string | undefined>} env
64
+ * @returns {{ errors: string[], warnings: string[], summary: string }}
65
+ */
66
+ export function checkCapstone(env) {
67
+ const errors = [];
68
+ const warnings = [];
69
+
70
+ const lanes = (env.LANES ?? "")
71
+ .split(",")
72
+ .map((l) => l.trim())
73
+ .filter(Boolean);
74
+ if (lanes.length === 0) {
75
+ errors.push("LANES names no lane — a capstone that watches nothing proves nothing.");
76
+ }
77
+
78
+ if (env.SCOPE_RESULT !== undefined && env.SCOPE_RESULT !== "success") {
79
+ errors.push(`bkit-tests-scope did not succeed (result=${env.SCOPE_RESULT})`);
80
+ }
81
+
82
+ let runLevel = null;
83
+ if (env.PLAN !== undefined) {
84
+ const plan = readPlan(env.PLAN);
85
+ runLevel = plan.runLevel;
86
+ if (plan.problem !== null) {
87
+ errors.push(
88
+ `the plan does not parse (${plan.problem}) — expected a JSON object with a run_level, got ${JSON.stringify(env.PLAN.slice(0, 80))}`,
89
+ );
90
+ }
91
+ }
92
+ const expectSkip = runLevel === "none";
93
+ const why = runLevel === null ? "" : `plan.run_level=${runLevel} but `;
94
+
95
+ const parts = [];
96
+ for (const lane of lanes) {
97
+ const job = `bkit-tests-${lane}`;
98
+ if (!LANE_NAME.test(lane)) {
99
+ errors.push(`LANES entry '${lane}' is not a lane name (letters, digits and '-').`);
100
+ continue;
101
+ }
102
+ const prefix = PREFIX(lane);
103
+ const result = env[`${prefix}_RESULT`];
104
+ if (result === undefined) {
105
+ errors.push(`${prefix}_RESULT is not set — the capstone cannot read ${job}'s result.`);
106
+ continue;
107
+ }
108
+
109
+ if (expectSkip) {
110
+ if (result !== "skipped") {
111
+ errors.push(
112
+ `plan.run_level=none says skip but ${job} ran (result=${result}) — plan and lane disagree.`,
113
+ );
114
+ }
115
+ parts.push(`${lane}=${result}`);
116
+ continue;
117
+ }
118
+
119
+ if (result !== "success") {
120
+ errors.push(
121
+ runLevel === null
122
+ ? `${job} result=${result} (expected success)`
123
+ : `${why}${job} result=${result}`,
124
+ );
125
+ parts.push(`${lane}=${result}`);
126
+ continue;
127
+ }
128
+
129
+ const ranKey = `${prefix}_RAN`;
130
+ const counted = Object.hasOwn(env, ranKey);
131
+ if (!counted || env[`${prefix}_CACHE_SKIP`] === "true") {
132
+ parts.push(`${lane}=${result}`);
133
+ continue;
134
+ }
135
+
136
+ const ran = env[ranKey] ?? "";
137
+ if (ran === "" && env.EMPTY_COUNT === "warn") {
138
+ warnings.push(
139
+ `${job} writes no executed-test count — green does not prove tests ran (see its test step).`,
140
+ );
141
+ parts.push(`${lane}=${result} (count unreported)`);
142
+ } else if (!/^[0-9]+$/.test(ran)) {
143
+ errors.push(
144
+ `${job} succeeded but its executed-test count is non-numeric ('${ran}') — cannot confirm tests ran.`,
145
+ );
146
+ parts.push(`${lane}=${result}`);
147
+ } else if (Number(ran) === 0) {
148
+ errors.push(`${job} succeeded but executed 0 tests — vacuous green (expected >0).`);
149
+ parts.push(`${lane}=${result} (0 tests)`);
150
+ } else {
151
+ parts.push(`${lane}=${result} (${Number(ran)} tests)`);
152
+ }
153
+ }
154
+
155
+ const level = runLevel === null ? "" : `, run_level=${runLevel}`;
156
+ return {
157
+ errors,
158
+ warnings,
159
+ summary: `bkit-tests-check passed — ${parts.join(", ")}${level}.`,
160
+ };
161
+ }
162
+
163
+ function main() {
164
+ const { errors, warnings, summary } = checkCapstone(process.env);
165
+ for (const w of warnings) console.log(`::warning::${w}`);
166
+ for (const e of errors) console.log(`::error::${e}`);
167
+ if (errors.length > 0) {
168
+ console.log("::error::bkit-tests-check FAILED — see above.");
169
+ process.exit(1);
170
+ }
171
+ console.log(`✅ ${summary}`);
172
+ }
173
+
174
+ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
175
+ main();
176
+ }
@@ -0,0 +1,311 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * check-capstone.test.mjs — unit tests for the capstone gate.
6
+ *
7
+ * Pure Node, no runner: `node scripts/ci/check-capstone.test.mjs`.
8
+ * Exit: 0 = all tests passed, 1 = at least one test failed.
9
+ */
10
+
11
+ import { spawnSync } from "node:child_process";
12
+ import path from "node:path";
13
+ import { fileURLToPath } from "node:url";
14
+ import { checkCapstone } from "./check-capstone.mjs";
15
+
16
+ const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "check-capstone.mjs");
17
+
18
+ let passed = 0;
19
+ let failed = 0;
20
+
21
+ function test(name, fn) {
22
+ try {
23
+ fn();
24
+ passed++;
25
+ console.log(` ok ${name}`);
26
+ } catch (err) {
27
+ failed++;
28
+ console.log(` FAIL ${name} — ${err.message}`);
29
+ }
30
+ }
31
+
32
+ function assert(cond, message) {
33
+ if (!cond) throw new Error(message);
34
+ }
35
+
36
+ /** The environment of a capstone that watches a static lane and a counted unit lane. */
37
+ const base = (extra = {}) => ({
38
+ LANES: "static,unit",
39
+ STATIC_RESULT: "success",
40
+ UNIT_RESULT: "success",
41
+ UNIT_RAN: "12",
42
+ UNIT_CACHE_SKIP: "",
43
+ ...extra,
44
+ });
45
+
46
+ /** The planner shape: scope + a run level, with a counted integration lane too. */
47
+ const planned = (extra = {}) => ({
48
+ LANES: "static,unit,integration",
49
+ PLAN: JSON.stringify({ run_level: "full" }),
50
+ SCOPE_RESULT: "success",
51
+ STATIC_RESULT: "success",
52
+ UNIT_RESULT: "success",
53
+ UNIT_RAN: "12",
54
+ UNIT_CACHE_SKIP: "false",
55
+ INTEGRATION_RESULT: "success",
56
+ INTEGRATION_RAN: "4",
57
+ INTEGRATION_CACHE_SKIP: "false",
58
+ ...extra,
59
+ });
60
+
61
+ const skipPlan = (extra = {}) =>
62
+ planned({
63
+ PLAN: JSON.stringify({ run_level: "none" }),
64
+ STATIC_RESULT: "skipped",
65
+ UNIT_RESULT: "skipped",
66
+ UNIT_RAN: "",
67
+ UNIT_CACHE_SKIP: "",
68
+ INTEGRATION_RESULT: "skipped",
69
+ INTEGRATION_RAN: "",
70
+ INTEGRATION_CACHE_SKIP: "",
71
+ ...extra,
72
+ });
73
+
74
+ const reds = (env, needle) => {
75
+ const r = checkCapstone(env);
76
+ assert(r.errors.length > 0, `expected a failure, got ${JSON.stringify(r)}`);
77
+ if (needle) {
78
+ assert(
79
+ r.errors.some((e) => e.includes(needle)),
80
+ `no error mentions ${JSON.stringify(needle)}: ${JSON.stringify(r.errors)}`,
81
+ );
82
+ }
83
+ return r;
84
+ };
85
+
86
+ const greens = (env) => {
87
+ const r = checkCapstone(env);
88
+ assert(r.errors.length === 0, `expected a pass, got ${JSON.stringify(r.errors)}`);
89
+ return r;
90
+ };
91
+
92
+ // ── the clean pass ───────────────────────────────────────────────────────────
93
+
94
+ test("every lane succeeded and the counted lane ran tests: passes", () => {
95
+ const r = greens(base());
96
+ assert(r.warnings.length === 0, `warnings ${JSON.stringify(r.warnings)}`);
97
+ });
98
+
99
+ test("with a plan: scope, every lane and every count good passes", () => {
100
+ greens(planned());
101
+ });
102
+
103
+ // ── case 1: a lane whose result is not success ──────────────────────────────
104
+
105
+ test("a failed lane fails, naming the lane and its result", () => {
106
+ reds(base({ STATIC_RESULT: "failure" }), "bkit-tests-static");
107
+ const r = reds(base({ UNIT_RESULT: "failure" }), "result=failure");
108
+ assert(
109
+ r.errors.some((e) => e.includes("bkit-tests-unit")),
110
+ "lane not named",
111
+ );
112
+ });
113
+
114
+ test("a skipped or cancelled lane fails when the lane was expected to run", () => {
115
+ reds(base({ STATIC_RESULT: "skipped" }), "result=skipped");
116
+ reds(base({ UNIT_RESULT: "cancelled" }), "result=cancelled");
117
+ });
118
+
119
+ test("with a plan, a failed lane fails naming the run level", () => {
120
+ reds(planned({ INTEGRATION_RESULT: "failure" }), "run_level=full");
121
+ });
122
+
123
+ test("a lane whose result was never wired in fails", () => {
124
+ const env = base();
125
+ delete env.STATIC_RESULT;
126
+ reds(env, "STATIC_RESULT");
127
+ });
128
+
129
+ test("a failed scope job fails even when every lane succeeded", () => {
130
+ reds(planned({ SCOPE_RESULT: "failure" }), "bkit-tests-scope");
131
+ });
132
+
133
+ // ── case 2: a gated lane ran although the plan said skip ────────────────────
134
+
135
+ test("run_level=none with every lane skipped passes", () => {
136
+ greens(skipPlan());
137
+ });
138
+
139
+ test("run_level=none but a lane ran (success) fails", () => {
140
+ reds(skipPlan({ UNIT_RESULT: "success", UNIT_RAN: "5" }), "bkit-tests-unit");
141
+ });
142
+
143
+ test("run_level=none but a lane ran (failure) fails", () => {
144
+ reds(skipPlan({ STATIC_RESULT: "failure" }), "bkit-tests-static");
145
+ });
146
+
147
+ test("run_level=none ignores counts on skipped lanes", () => {
148
+ greens(skipPlan({ UNIT_RAN: "0", INTEGRATION_RAN: "not-a-number" }));
149
+ });
150
+
151
+ // ── case 3: success with 0 tests, or a count that is not a number ───────────
152
+
153
+ test("a lane that succeeded having run 0 tests fails", () => {
154
+ reds(base({ UNIT_RAN: "0" }), "0 tests");
155
+ });
156
+
157
+ test("a zero written with leading zeros is still zero", () => {
158
+ reds(base({ UNIT_RAN: "00" }), "0 tests");
159
+ });
160
+
161
+ test("a non-numeric count fails", () => {
162
+ reds(base({ UNIT_RAN: "abc" }), "non-numeric");
163
+ reds(base({ UNIT_RAN: "-3" }), "non-numeric");
164
+ reds(base({ UNIT_RAN: "1.5" }), "non-numeric");
165
+ reds(base({ UNIT_RAN: " 4" }), "non-numeric");
166
+ });
167
+
168
+ test("an empty count fails by default", () => {
169
+ reds(base({ UNIT_RAN: "" }), "non-numeric");
170
+ });
171
+
172
+ test("a positive count passes", () => {
173
+ greens(base({ UNIT_RAN: "1" }));
174
+ greens(base({ UNIT_RAN: "0042" }));
175
+ });
176
+
177
+ test("each counted lane is checked on its own", () => {
178
+ reds(planned({ UNIT_RAN: "9", INTEGRATION_RAN: "0" }), "bkit-tests-integration");
179
+ reds(planned({ UNIT_RAN: "0", INTEGRATION_RAN: "9" }), "bkit-tests-unit");
180
+ });
181
+
182
+ test("a lane with no <LANE>_RAN variable is not count-checked", () => {
183
+ const env = base();
184
+ assert(!("STATIC_RAN" in env), "fixture sets STATIC_RAN");
185
+ greens(env);
186
+ });
187
+
188
+ test("a count on a lane that did not succeed is not double-reported", () => {
189
+ const r = reds(base({ UNIT_RESULT: "failure", UNIT_RAN: "0" }), "result=failure");
190
+ assert(r.errors.length === 1, `errors ${JSON.stringify(r.errors)}`);
191
+ });
192
+
193
+ // ── case 4: a plan that will not parse ──────────────────────────────────────
194
+
195
+ test("a plan that is not JSON fails", () => {
196
+ reds(planned({ PLAN: "{not json" }), "plan");
197
+ });
198
+
199
+ test("an empty plan fails (a planner that emitted nothing)", () => {
200
+ reds(planned({ PLAN: "" }), "plan");
201
+ });
202
+
203
+ test("a plan that is not an object, or has no run_level, fails", () => {
204
+ reds(planned({ PLAN: "[]" }), "plan");
205
+ reds(planned({ PLAN: "null" }), "plan");
206
+ reds(planned({ PLAN: '"full"' }), "plan");
207
+ reds(planned({ PLAN: "{}" }), "plan");
208
+ reds(planned({ PLAN: '{"run_level":""}' }), "plan");
209
+ reds(planned({ PLAN: '{"run_level":3}' }), "plan");
210
+ });
211
+
212
+ test("an unparseable plan never lets a skipped lane pass as 'nothing planned'", () => {
213
+ reds(skipPlan({ PLAN: "{not json" }), "plan");
214
+ });
215
+
216
+ // ── the exemptions ──────────────────────────────────────────────────────────
217
+
218
+ test("cache_skip=true asserts no count", () => {
219
+ greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "" }));
220
+ greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "0" }));
221
+ greens(planned({ INTEGRATION_CACHE_SKIP: "true", INTEGRATION_RAN: "0" }));
222
+ });
223
+
224
+ test("cache_skip=true does not excuse a failed lane", () => {
225
+ reds(base({ UNIT_RESULT: "failure", UNIT_CACHE_SKIP: "true" }), "result=failure");
226
+ });
227
+
228
+ test("only the exact string 'true' is a cache skip", () => {
229
+ reds(base({ UNIT_CACHE_SKIP: "yes", UNIT_RAN: "0" }), "0 tests");
230
+ reds(base({ UNIT_CACHE_SKIP: "TRUE", UNIT_RAN: "0" }), "0 tests");
231
+ });
232
+
233
+ test("EMPTY_COUNT=warn turns an unreported count into a warning, not a failure", () => {
234
+ const r = greens(base({ EMPTY_COUNT: "warn", UNIT_RAN: "" }));
235
+ assert(r.warnings.length === 1, `warnings ${JSON.stringify(r.warnings)}`);
236
+ assert(r.warnings[0].includes("bkit-tests-unit"), "lane not named in the warning");
237
+ });
238
+
239
+ test("EMPTY_COUNT=warn still fails a zero or non-numeric count", () => {
240
+ reds(base({ EMPTY_COUNT: "warn", UNIT_RAN: "0" }), "0 tests");
241
+ reds(base({ EMPTY_COUNT: "warn", UNIT_RAN: "abc" }), "non-numeric");
242
+ });
243
+
244
+ test("an EMPTY_COUNT value other than warn is the strict default", () => {
245
+ reds(base({ EMPTY_COUNT: "ignore", UNIT_RAN: "" }), "non-numeric");
246
+ });
247
+
248
+ // ── the wiring ──────────────────────────────────────────────────────────────
249
+
250
+ test("no LANES fails: a gate that watches nothing proves nothing", () => {
251
+ reds({}, "LANES");
252
+ reds({ LANES: "" }, "LANES");
253
+ reds({ LANES: " , " }, "LANES");
254
+ });
255
+
256
+ test("a lane name that cannot be an env prefix fails", () => {
257
+ reds({ LANES: "unit;rm", UNIT_RESULT: "success" }, "unit;rm");
258
+ });
259
+
260
+ test("a hyphenated lane reads <LANE>_ variables with underscores", () => {
261
+ greens({
262
+ LANES: "e2e-web",
263
+ E2E_WEB_RESULT: "success",
264
+ E2E_WEB_RAN: "3",
265
+ E2E_WEB_CACHE_SKIP: "",
266
+ });
267
+ reds(
268
+ { LANES: "e2e-web", E2E_WEB_RESULT: "success", E2E_WEB_RAN: "0", E2E_WEB_CACHE_SKIP: "" },
269
+ "bkit-tests-e2e-web",
270
+ );
271
+ });
272
+
273
+ test("lane names tolerate spaces around the commas", () => {
274
+ greens(base({ LANES: " static , unit " }));
275
+ });
276
+
277
+ // ── the command line ────────────────────────────────────────────────────────
278
+
279
+ function run(env) {
280
+ const r = spawnSync(process.execPath, [SCRIPT], { env, encoding: "utf-8" });
281
+ return { status: r.status, out: `${r.stdout}${r.stderr}` };
282
+ }
283
+
284
+ test("exits 0 and prints a pass line when the lanes are good", () => {
285
+ const r = run(base());
286
+ assert(r.status === 0, `status ${r.status}: ${r.out}`);
287
+ assert(r.out.includes("bkit-tests-check passed"), `output ${r.out}`);
288
+ });
289
+
290
+ test("exits 1 and prints ::error:: lines when a lane failed", () => {
291
+ const r = run(base({ UNIT_RESULT: "failure" }));
292
+ assert(r.status === 1, `status ${r.status}`);
293
+ assert(r.out.includes("::error::bkit-tests-unit"), `output ${r.out}`);
294
+ assert(r.out.includes("bkit-tests-check FAILED"), `output ${r.out}`);
295
+ });
296
+
297
+ test("exits 1 on a zero count, and prints ::warning:: for an unreported one", () => {
298
+ assert(run(base({ UNIT_RAN: "0" })).status === 1, "zero count passed");
299
+ const r = run(base({ EMPTY_COUNT: "warn", UNIT_RAN: "" }));
300
+ assert(r.status === 0, `status ${r.status}: ${r.out}`);
301
+ assert(r.out.includes("::warning::bkit-tests-unit"), `output ${r.out}`);
302
+ });
303
+
304
+ test("exits 1 on a plan that will not parse", () => {
305
+ const r = run(planned({ PLAN: "{not json" }));
306
+ assert(r.status === 1, `status ${r.status}`);
307
+ assert(r.out.includes("::error::"), `output ${r.out}`);
308
+ });
309
+
310
+ console.log(`\n${passed} passed, ${failed} failed`);
311
+ process.exit(failed ? 1 : 0);