@intentius/chant 0.124.84 → 0.124.86

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 (254) hide show
  1. package/dist/bundle-check.d.ts +102 -0
  2. package/dist/bundle-check.d.ts.map +1 -0
  3. package/dist/bundle-check.js +310 -0
  4. package/dist/chant-install.d.ts +100 -0
  5. package/dist/chant-install.d.ts.map +1 -0
  6. package/dist/chant-install.js +158 -0
  7. package/dist/ci-commit.d.ts +19 -6
  8. package/dist/ci-commit.d.ts.map +1 -1
  9. package/dist/ci-commit.js +23 -4
  10. package/dist/ci-evidence-jobs.d.ts +54 -0
  11. package/dist/ci-evidence-jobs.d.ts.map +1 -0
  12. package/dist/ci-evidence-jobs.js +55 -0
  13. package/dist/ci-image.d.ts +274 -0
  14. package/dist/ci-image.d.ts.map +1 -0
  15. package/dist/ci-image.js +635 -0
  16. package/dist/ci-login.d.ts +150 -0
  17. package/dist/ci-login.d.ts.map +1 -0
  18. package/dist/ci-login.js +240 -0
  19. package/dist/ci-product.d.ts +16 -0
  20. package/dist/ci-product.d.ts.map +1 -1
  21. package/dist/ci-product.js +17 -0
  22. package/dist/cli/commands/import-index.js +2 -2
  23. package/dist/cli/handlers/build.d.ts +8 -0
  24. package/dist/cli/handlers/build.d.ts.map +1 -1
  25. package/dist/cli/handlers/build.js +22 -4
  26. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  27. package/dist/cli/handlers/ci-check.js +57 -2
  28. package/dist/cli/handlers/ci-evidence.d.ts +3 -0
  29. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -0
  30. package/dist/cli/handlers/ci-evidence.js +171 -0
  31. package/dist/cli/handlers/components.js +3 -3
  32. package/dist/cli/handlers/dead-guards.d.ts +3 -0
  33. package/dist/cli/handlers/dead-guards.d.ts.map +1 -0
  34. package/dist/cli/handlers/dead-guards.js +35 -0
  35. package/dist/cli/handlers/graph.js +4 -4
  36. package/dist/cli/handlers/lifecycle.d.ts +2 -1
  37. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  38. package/dist/cli/handlers/lifecycle.js +5 -4
  39. package/dist/cli/handlers/local-chant.d.ts +16 -0
  40. package/dist/cli/handlers/local-chant.d.ts.map +1 -0
  41. package/dist/cli/handlers/local-chant.js +109 -0
  42. package/dist/cli/handlers/operator.js +2 -2
  43. package/dist/cli/handlers/search.js +5 -5
  44. package/dist/cli/main.d.ts.map +1 -1
  45. package/dist/cli/main.js +38 -0
  46. package/dist/cli/parse-args.d.ts.map +1 -1
  47. package/dist/cli/parse-args.js +28 -0
  48. package/dist/cli/registry.d.ts +16 -0
  49. package/dist/cli/registry.d.ts.map +1 -1
  50. package/dist/components/check-hooks.d.ts +49 -0
  51. package/dist/components/check-hooks.d.ts.map +1 -1
  52. package/dist/components/check-hooks.js +64 -4
  53. package/dist/components/check-steps.d.ts +17 -0
  54. package/dist/components/check-steps.d.ts.map +1 -1
  55. package/dist/components/check-steps.js +37 -5
  56. package/dist/components/product-pipeline.d.ts +23 -0
  57. package/dist/components/product-pipeline.d.ts.map +1 -1
  58. package/dist/components/product-pipeline.js +6 -2
  59. package/dist/components/product-plan.d.ts +137 -0
  60. package/dist/components/product-plan.d.ts.map +1 -0
  61. package/dist/components/product-plan.js +143 -0
  62. package/dist/components/release-compile.d.ts.map +1 -1
  63. package/dist/components/release-compile.js +2 -2
  64. package/dist/config.d.ts +39 -1
  65. package/dist/config.d.ts.map +1 -1
  66. package/dist/config.js +35 -3
  67. package/dist/dead-guards.d.ts +82 -0
  68. package/dist/dead-guards.d.ts.map +1 -0
  69. package/dist/dead-guards.js +436 -0
  70. package/dist/discovery/files.d.ts +3 -1
  71. package/dist/discovery/files.d.ts.map +1 -1
  72. package/dist/discovery/files.js +5 -3
  73. package/dist/drift-issue.d.ts +152 -0
  74. package/dist/drift-issue.d.ts.map +1 -0
  75. package/dist/drift-issue.js +167 -0
  76. package/dist/floor-table.d.ts +30 -0
  77. package/dist/floor-table.d.ts.map +1 -0
  78. package/dist/floor-table.data.d.ts +3 -0
  79. package/dist/floor-table.data.d.ts.map +1 -0
  80. package/dist/floor-table.data.js +178 -0
  81. package/dist/floor-table.js +56 -0
  82. package/dist/forge-flags.d.ts +90 -0
  83. package/dist/forge-flags.d.ts.map +1 -0
  84. package/dist/forge-flags.js +184 -0
  85. package/dist/lexicon.d.ts +69 -0
  86. package/dist/lexicon.d.ts.map +1 -1
  87. package/dist/lifecycle/gated-op.d.ts +7 -1
  88. package/dist/lifecycle/gated-op.d.ts.map +1 -1
  89. package/dist/lifecycle/gated-op.js +7 -4
  90. package/dist/local-chant.d.ts +98 -0
  91. package/dist/local-chant.d.ts.map +1 -0
  92. package/dist/local-chant.js +307 -0
  93. package/dist/op/activities/predict-behaviour.js +2 -2
  94. package/dist/op/op-waves-evidence-spec.d.ts +13 -0
  95. package/dist/op/op-waves-evidence-spec.d.ts.map +1 -0
  96. package/dist/op/op-waves-evidence-spec.js +21 -0
  97. package/dist/op/op-waves-evidence.d.ts +38 -0
  98. package/dist/op/op-waves-evidence.d.ts.map +1 -0
  99. package/dist/op/op-waves-evidence.js +57 -0
  100. package/dist/op/op-waves-run.d.ts +4 -0
  101. package/dist/op/op-waves-run.d.ts.map +1 -1
  102. package/dist/op/op-waves-run.js +24 -1
  103. package/dist/op/op-waves.d.ts +17 -1
  104. package/dist/op/op-waves.d.ts.map +1 -1
  105. package/dist/op/op-waves.js +23 -0
  106. package/dist/op/schedule-overdue.d.ts +41 -9
  107. package/dist/op/schedule-overdue.d.ts.map +1 -1
  108. package/dist/op/schedule-overdue.js +154 -25
  109. package/dist/plan-summary.d.ts +25 -0
  110. package/dist/plan-summary.d.ts.map +1 -1
  111. package/dist/plan-summary.js +31 -0
  112. package/dist/pr-plan-note.d.ts +35 -0
  113. package/dist/pr-plan-note.d.ts.map +1 -1
  114. package/dist/pr-plan-note.js +10 -0
  115. package/dist/pr-post.d.ts +23 -0
  116. package/dist/pr-post.d.ts.map +1 -1
  117. package/dist/pr-post.js +125 -3
  118. package/dist/release-floors.d.ts +31 -1
  119. package/dist/release-floors.d.ts.map +1 -1
  120. package/dist/release-floors.js +31 -1
  121. package/dist/state-migration.d.ts +24 -0
  122. package/dist/state-migration.d.ts.map +1 -1
  123. package/dist/state-migration.js +100 -5
  124. package/dist/wave-runtime.mjs +305 -298
  125. package/dist/workspace/lexicon-outputs.d.ts.map +1 -1
  126. package/dist/workspace/lexicon-outputs.js +21 -7
  127. package/dist/workspace/reason-codes.d.ts +3 -0
  128. package/dist/workspace/reason-codes.d.ts.map +1 -1
  129. package/dist/workspace/reason-codes.js +4 -0
  130. package/dist/workspace/ref-gate.schema.json +85 -0
  131. package/dist/workspace/search-contract.d.ts +1 -1
  132. package/dist/workspace/search-contract.d.ts.map +1 -1
  133. package/dist/workspace/trust/check-evidence-report.d.ts +51 -0
  134. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -0
  135. package/dist/workspace/trust/check-evidence-report.js +102 -0
  136. package/dist/workspace/trust/check-evidence.d.ts +126 -0
  137. package/dist/workspace/trust/check-evidence.d.ts.map +1 -0
  138. package/dist/workspace/trust/check-evidence.js +237 -0
  139. package/dist/workspace/trust/local-evidence.d.ts +120 -0
  140. package/dist/workspace/trust/local-evidence.d.ts.map +1 -0
  141. package/dist/workspace/trust/local-evidence.js +259 -0
  142. package/dist/workspace/trust/policy.d.ts +84 -0
  143. package/dist/workspace/trust/policy.d.ts.map +1 -1
  144. package/dist/workspace/trust/policy.js +94 -1
  145. package/dist/workspace/trust/ref-gate-cli.d.ts +33 -0
  146. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -0
  147. package/dist/workspace/trust/ref-gate-cli.js +234 -0
  148. package/dist/workspace/trust/ref-gate-fixture.d.ts +38 -0
  149. package/dist/workspace/trust/ref-gate-fixture.d.ts.map +1 -0
  150. package/dist/workspace/trust/ref-gate-fixture.js +97 -0
  151. package/dist/workspace/trust/ref-gate.d.ts +187 -0
  152. package/dist/workspace/trust/ref-gate.d.ts.map +1 -0
  153. package/dist/workspace/trust/ref-gate.js +430 -0
  154. package/dist/workspace/trust/trust-files.d.ts.map +1 -1
  155. package/dist/workspace/trust/trust-files.js +18 -1
  156. package/package.json +1 -1
  157. package/src/bundle-check.test.ts +140 -0
  158. package/src/bundle-check.ts +352 -0
  159. package/src/chant-install.test.ts +112 -0
  160. package/src/chant-install.ts +179 -0
  161. package/src/ci-commit.test.ts +45 -0
  162. package/src/ci-commit.ts +38 -4
  163. package/src/ci-evidence-jobs.ts +67 -0
  164. package/src/ci-image.test.ts +506 -0
  165. package/src/ci-image.ts +822 -0
  166. package/src/ci-login.test.ts +235 -0
  167. package/src/ci-login.ts +307 -0
  168. package/src/ci-product.ts +18 -0
  169. package/src/cli/commands/__fixtures__/source-dir-include/chant.config.json +1 -0
  170. package/src/cli/commands/__fixtures__/source-dir-include/infra.ts +1 -0
  171. package/src/cli/commands/__fixtures__/source-dir-include/scripts/run-on-load.ts +3 -0
  172. package/src/cli/commands/__fixtures__/source-dir-root/chant.config.json +1 -0
  173. package/src/cli/commands/__fixtures__/source-dir-root/infra.test.ts +1 -0
  174. package/src/cli/commands/__fixtures__/source-dir-root/infra.ts +1 -0
  175. package/src/cli/commands/__fixtures__/source-dir-root/scripts/run-on-load.ts +3 -0
  176. package/src/cli/commands/__fixtures__/source-dir-scoped/app.ts +3 -0
  177. package/src/cli/commands/__fixtures__/source-dir-scoped/chant.config.json +1 -0
  178. package/src/cli/commands/__fixtures__/source-dir-scoped/infra/net.ts +1 -0
  179. package/src/cli/commands/__fixtures__/source-dir-scoped/scripts/run-on-load.ts +3 -0
  180. package/src/cli/commands/import-index.ts +2 -2
  181. package/src/cli/handlers/build-source-dir.test.ts +64 -0
  182. package/src/cli/handlers/build.ts +21 -4
  183. package/src/cli/handlers/ci-check.ts +56 -3
  184. package/src/cli/handlers/ci-evidence.ts +162 -0
  185. package/src/cli/handlers/components.ts +3 -3
  186. package/src/cli/handlers/dead-guards.ts +37 -0
  187. package/src/cli/handlers/graph.ts +4 -4
  188. package/src/cli/handlers/lifecycle.ts +5 -4
  189. package/src/cli/handlers/local-chant.ts +106 -0
  190. package/src/cli/handlers/operator.ts +2 -2
  191. package/src/cli/handlers/search.ts +5 -5
  192. package/src/cli/main.test.ts +7 -0
  193. package/src/cli/main.ts +38 -0
  194. package/src/cli/parse-args.ts +21 -0
  195. package/src/cli/registry.ts +16 -0
  196. package/src/components/check-evidence-stage.test.ts +80 -0
  197. package/src/components/check-hooks.ts +84 -4
  198. package/src/components/check-local-evidence-stage.test.ts +141 -0
  199. package/src/components/check-steps.ts +56 -6
  200. package/src/components/product-pipeline.ts +28 -3
  201. package/src/components/product-plan.test.ts +87 -0
  202. package/src/components/product-plan.ts +226 -0
  203. package/src/components/release-compile.ts +2 -2
  204. package/src/config.ts +44 -3
  205. package/src/dead-guards.test.ts +206 -0
  206. package/src/dead-guards.ts +446 -0
  207. package/src/discovery/files.ts +5 -3
  208. package/src/drift-issue-bundle.test.ts +31 -0
  209. package/src/drift-issue.test.ts +206 -0
  210. package/src/drift-issue.ts +274 -0
  211. package/src/fit-note.test.ts +44 -0
  212. package/src/floor-table.data.ts +180 -0
  213. package/src/floor-table.ts +77 -0
  214. package/src/forge-flags.test.ts +110 -0
  215. package/src/forge-flags.ts +208 -0
  216. package/src/gate-decision-bundle.test.ts +1 -0
  217. package/src/lexicon.ts +68 -0
  218. package/src/lifecycle/gated-op.ts +10 -5
  219. package/src/local-chant.e2e.test.ts +94 -0
  220. package/src/local-chant.test.ts +162 -0
  221. package/src/local-chant.ts +341 -0
  222. package/src/op/activities/predict-behaviour.ts +2 -2
  223. package/src/op/op-waves-evidence-spec.ts +24 -0
  224. package/src/op/op-waves-evidence.test.ts +130 -0
  225. package/src/op/op-waves-evidence.ts +57 -0
  226. package/src/op/op-waves-run.ts +25 -1
  227. package/src/op/op-waves.ts +31 -1
  228. package/src/op/schedule-overdue.test.ts +85 -0
  229. package/src/op/schedule-overdue.ts +162 -26
  230. package/src/plan-summary.ts +40 -0
  231. package/src/pr-plan-note.ts +34 -0
  232. package/src/pr-post-plan-note.test.ts +146 -0
  233. package/src/pr-post.ts +127 -3
  234. package/src/release-floors.ts +44 -1
  235. package/src/stage-hooks-bundle.test.ts +1 -0
  236. package/src/state-migration.test.ts +52 -1
  237. package/src/state-migration.ts +107 -5
  238. package/src/workspace/lexicon-outputs.ts +23 -6
  239. package/src/workspace/reason-codes.test.ts +3 -0
  240. package/src/workspace/reason-codes.ts +4 -0
  241. package/src/workspace/ref-gate.schema.json +85 -0
  242. package/src/workspace/trust/check-evidence-report.ts +106 -0
  243. package/src/workspace/trust/check-evidence.test.ts +133 -0
  244. package/src/workspace/trust/check-evidence.ts +257 -0
  245. package/src/workspace/trust/local-evidence.test.ts +127 -0
  246. package/src/workspace/trust/local-evidence.ts +266 -0
  247. package/src/workspace/trust/policy.ts +134 -1
  248. package/src/workspace/trust/ref-gate-cli.ts +244 -0
  249. package/src/workspace/trust/ref-gate-fixture.ts +125 -0
  250. package/src/workspace/trust/ref-gate.e2e.test.ts +76 -0
  251. package/src/workspace/trust/ref-gate.test.ts +247 -0
  252. package/src/workspace/trust/ref-gate.ts +538 -0
  253. package/src/workspace/trust/trust-files.test.ts +16 -0
  254. package/src/workspace/trust/trust-files.ts +41 -1
@@ -0,0 +1,97 @@
1
+ /**
2
+ * Test support for the ref gate (#4867): a checkout and a bare remote, a
3
+ * runner key, fake runner evidence signed with it, and override lines on
4
+ * `chant/lifecycle`. Isolated from the user's git config. The temporary
5
+ * directories are left in the system's temp directory.
6
+ */
7
+ import { execFileSync } from "node:child_process";
8
+ import { generateKeyPairSync } from "node:crypto";
9
+ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
10
+ import { tmpdir } from "node:os";
11
+ import { dirname, join } from "node:path";
12
+ import { loadRunnerKey } from "./dsse.js";
13
+ import { buildStatement, signEvidence } from "./evidence.js";
14
+ import { attachEvidence, EVIDENCE_NOTES_REF, refGateSubject } from "./ref-gate.js";
15
+ import { OVERRIDE_OP, overrideDigest } from "../../override-gate.js";
16
+ export function runnerKey() {
17
+ const { privateKey } = generateKeyPairSync("ed25519");
18
+ const pem = privateKey.export({ format: "pem", type: "pkcs8" }).toString();
19
+ return { pem, pub: loadRunnerKey(pem).publicKey };
20
+ }
21
+ export const RUNNER = "ci@example.test";
22
+ export class GateRepos {
23
+ constructor(label) {
24
+ this.root = mkdtempSync(join(tmpdir(), `chant-4867-${label}-`));
25
+ this.work = join(this.root, "work");
26
+ this.origin = join(this.root, "origin.git");
27
+ this.home = join(this.root, "home");
28
+ mkdirSync(this.home);
29
+ this.run(this.root, ["init", "-q", "--bare", "-b", "main", this.origin]);
30
+ this.run(this.root, ["init", "-q", "-b", "main", this.work]);
31
+ this.git(["remote", "add", "origin", this.origin]);
32
+ }
33
+ env() {
34
+ return {
35
+ PATH: process.env.PATH ?? "",
36
+ HOME: this.home,
37
+ GIT_CONFIG_GLOBAL: join(this.home, "gitconfig"),
38
+ GIT_CONFIG_NOSYSTEM: "1",
39
+ GIT_AUTHOR_NAME: "t",
40
+ GIT_AUTHOR_EMAIL: "t@example.test",
41
+ GIT_COMMITTER_NAME: "t",
42
+ GIT_COMMITTER_EMAIL: "t@example.test",
43
+ };
44
+ }
45
+ run(cwd, args, input) {
46
+ return execFileSync("git", args, { cwd, env: this.env(), input, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
47
+ }
48
+ git(args, input) {
49
+ return this.run(this.work, args, input);
50
+ }
51
+ write(path, text) {
52
+ mkdirSync(dirname(join(this.work, path)), { recursive: true });
53
+ writeFileSync(join(this.work, path), text);
54
+ }
55
+ commit(message) {
56
+ this.git(["add", "-A"]);
57
+ this.git(["commit", "-q", "--no-gpg-sign", "--allow-empty", "-m", message]);
58
+ return this.git(["rev-parse", "HEAD"]).trim();
59
+ }
60
+ /** Push `refspecs` to the bare remote with no hook in the way, and return git's output. */
61
+ push(...refspecs) {
62
+ return this.run(this.work, ["push", "-q", "origin", ...refspecs]);
63
+ }
64
+ /** Sign evidence for `check` at `at` over `paths`, with `key`, and attach it to `to` (default `at`). */
65
+ sign(key, check, at, paths, to = at) {
66
+ const statement = buildStatement({ repo: this.work, commit: at, paths, runner: RUNNER, check });
67
+ const { key: k, publicKey } = loadRunnerKey(key.pem);
68
+ const envelope = signEvidence(statement, k, publicKey);
69
+ attachEvidence(this.work, to, envelope);
70
+ return envelope;
71
+ }
72
+ notesTip() {
73
+ return this.git(["rev-parse", EVIDENCE_NOTES_REF]).trim();
74
+ }
75
+ /** Write `chant/lifecycle` holding a request for an override of `check` on `commit` and `by`'s override of it. */
76
+ override(commit, check, by, reason, at = "2026-11-09T10:00:00.000Z") {
77
+ const subject = refGateSubject(commit, check);
78
+ const digest = overrideDigest(subject, commit, [check]);
79
+ const pending = { version: 1, kind: "pending", op: OVERRIDE_OP, gate: subject, timestamp: "2026-11-09T09:00:00.000Z", expiresAt: "2026-11-12T09:00:00.000Z", planDigest: digest, plan: commit, rules: [check] };
80
+ const resolution = { version: 1, kind: "resolution", op: OVERRIDE_OP, gate: subject, resolvedBy: by, timestamp: at, note: reason, planDigest: digest };
81
+ const blob = this.git(["hash-object", "-w", "--stdin"], `${JSON.stringify(pending)}\n${JSON.stringify(resolution)}\n`).trim();
82
+ const gates = this.git(["mktree"], `100644 blob ${blob}\t${OVERRIDE_OP}.jsonl\n`).trim();
83
+ const tree = this.git(["mktree"], `040000 tree ${gates}\t_gates\n`).trim();
84
+ const c = this.git(["commit-tree", tree, "-m", "ledger"]).trim();
85
+ this.git(["update-ref", "refs/heads/chant/lifecycle", c]);
86
+ return c;
87
+ }
88
+ }
89
+ /** `.chant/trust.json` with one runner and a ref rule for `refs/heads/main` and `refs/heads/release/*`. */
90
+ export function trustJson(runner, checks, extra = {}) {
91
+ return JSON.stringify({
92
+ schema: 1,
93
+ runners: [{ principal: RUNNER, class: "runner", key: runner.pub }],
94
+ refs: [{ ref: "refs/heads/main", checks }, { ref: "refs/heads/release/*", checks }],
95
+ ...extra,
96
+ }, null, 2);
97
+ }
@@ -0,0 +1,187 @@
1
+ /**
2
+ * The ref gate (#4867): a ref update is refused when the commit lacks the
3
+ * runner evidence the policy at base requires for that ref.
4
+ *
5
+ * chant judges evidence at the green tick, a land, a gate and a release cut,
6
+ * all after the push. A change that was never going to pass still reached
7
+ * the remote and started CI. The gate judges it at the ref update instead,
8
+ * from three places that all call {@link decideRefUpdate}:
9
+ *
10
+ * - a plain git remote: the `pre-receive` hook `chant workspace ref-gate
11
+ * install` writes, which refuses the push;
12
+ * - a forge: `chant workspace ref-gate status`, a commit status the forge
13
+ * requires, so the merge is refused where the push can't be;
14
+ * - the developer's side: the `pre-push` hook, which refuses before the
15
+ * network and records the request for an override.
16
+ *
17
+ * The rules are `refs` in `.chant/trust.json`, read at base like every other
18
+ * part of the trust policy (./policy.ts): the old tip of the ref, so a change
19
+ * can neither drop a check nor add the runner key that signs its own
20
+ * evidence. Evidence is the runner evidence of ./evidence.ts, kept as git
21
+ * notes on the commit under {@link EVIDENCE_NOTES_REF}, one envelope per
22
+ * line, and verified offline against the runner keys at base. A check has
23
+ * current evidence when an envelope for it verifies and every record it
24
+ * names hashes the same at the pushed commit; an envelope that names no
25
+ * records counts only for a commit with the tree it was signed over.
26
+ *
27
+ * An override is the override gate's (../../override-gate.ts): a person
28
+ * the overriders file at base lists records a reasoned approval of one
29
+ * commit and one check, subject `ref-gate-<sha12>-<check>`, and it is spent
30
+ * by the first ref update it admits. Every decision is a line of the gate's
31
+ * ledger, a JSON-lines file in the git directory ({@link refGateLedgerPath}),
32
+ * since a pre-receive hook may not move a ref.
33
+ */
34
+ import type { RefRule, TrustPolicy } from "./policy.js";
35
+ import { type AppliedOverrideRecord } from "../../override-gate.js";
36
+ /** Where runner evidence for a commit is kept (#4867): a git note on the commit, one DSSE envelope per line. */
37
+ export declare const EVIDENCE_NOTES_REF = "refs/notes/chant/evidence";
38
+ /** The ledger branch whose override lines the gate reads. */
39
+ export declare const LIFECYCLE_REF = "refs/heads/chant/lifecycle";
40
+ /** The commit status a forge requires when the rule names none. */
41
+ export declare const REF_GATE_STATUS = "chant/ref-gate";
42
+ /** Why the gate cannot decide at all. Each is in `reason-codes.ts` and `ref-gate.schema.json`. */
43
+ export declare const REF_GATE_ERROR_CODES: readonly ["not-a-git-repository", "revision-unknown", "trust-policy-unreadable", "ref-update-invalid"];
44
+ export type RefGateErrorCode = (typeof REF_GATE_ERROR_CODES)[number];
45
+ /** Why a required check has no current evidence. The envelope codes are those of `evidence verify`. */
46
+ export declare const REF_GATE_CHECK_CODES: readonly ["ref-evidence-missing", "ref-evidence-stale", "envelope-invalid", "envelope-untrusted", "evidence-payload-type", "evidence-statement-invalid", "evidence-runner-mismatch"];
47
+ export type RefGateCheckCode = (typeof REF_GATE_CHECK_CODES)[number];
48
+ /** One ref update, as a hook reads it. `null` is git's zero id: a ref created (`old`) or deleted (`new`). */
49
+ export interface RefUpdate {
50
+ ref: string;
51
+ old: string | null;
52
+ new: string | null;
53
+ }
54
+ export interface OverrideUsed {
55
+ subject: string;
56
+ by: string;
57
+ at: string;
58
+ reason: string;
59
+ digest: string;
60
+ }
61
+ /** A required check, judged. */
62
+ export interface CheckVerdict {
63
+ check: string;
64
+ action: "block" | "warn";
65
+ /** The command that produces the evidence. */
66
+ command: string;
67
+ status: "current" | "stale" | "missing" | "overridden";
68
+ /** Why it has no current evidence. Absent when it has. */
69
+ code?: RefGateCheckCode;
70
+ reason: string;
71
+ /** The runner whose evidence counted. */
72
+ runner?: string;
73
+ /** The override it was let through under. */
74
+ override?: OverrideUsed;
75
+ /** The subject an override of this check names. */
76
+ subject: string;
77
+ }
78
+ export interface RefDecision {
79
+ ref: string;
80
+ old: string | null;
81
+ new: string | null;
82
+ /** The commit the policy was read at, or null when there is none. */
83
+ base: string | null;
84
+ decision: "admit" | "refuse";
85
+ /** The commit status a forge requires for this ref, when a rule matched. */
86
+ status: string | null;
87
+ checks: CheckVerdict[];
88
+ /** Set when the gate could not decide; the update is then refused. */
89
+ error?: {
90
+ code: RefGateErrorCode;
91
+ message: string;
92
+ };
93
+ }
94
+ /** The commit `rev` names, peeled, or undefined. */
95
+ export declare function commitOf(repo: string, rev: string): string | undefined;
96
+ /** A ref pattern as a RegExp: `**` matches across `/`, `*` within one segment. */
97
+ export declare function refPatternRegExp(pattern: string): RegExp;
98
+ /**
99
+ * The checks the policy requires for `ref`: every matching rule's, each check
100
+ * once. A check two rules name is `block` when either blocks it; the first
101
+ * rule that names a status or an override mode gives it.
102
+ */
103
+ export declare function rulesFor(policy: Pick<TrustPolicy, "refs">, ref: string): {
104
+ matched: boolean;
105
+ checks: RefRule["checks"];
106
+ status: string;
107
+ overrides?: "ledger" | "sealed";
108
+ };
109
+ /** The envelopes in a note's text: one per line, or the whole note as one envelope or an array of them. */
110
+ export declare function parseEvidenceNote(text: string): unknown[];
111
+ /** The envelopes attached to `commit`, read from the notes commit `notes` (default: {@link EVIDENCE_NOTES_REF}'s tip). */
112
+ export declare function evidenceFor(repo: string, commit: string, notes?: string | null): unknown[];
113
+ /**
114
+ * Attach `envelope` to `commit` as one line of its evidence note. Pushing `refs/notes/chant/evidence` is the caller's.
115
+ * `notesRef` is another notes ref, for local evidence (#4868), which the ref gate never reads.
116
+ */
117
+ export declare function attachEvidence(repo: string, commit: string, envelope: unknown, notesRef?: string): void;
118
+ /** The subject an override of `check` for `commit` names. */
119
+ export declare function refGateSubject(commit: string, check: string): string;
120
+ export interface RefGateInput {
121
+ /** The repository, bare or not. */
122
+ repo: string;
123
+ update: RefUpdate;
124
+ /** The commit the policy is read at: the ref's old tip, or the default branch for a new ref. Null: no policy, nothing required. */
125
+ base: string | null;
126
+ /** The notes commit evidence is read from. Default: {@link EVIDENCE_NOTES_REF}'s tip. */
127
+ notes?: string | null;
128
+ /** The `chant/lifecycle` commit override lines are read from. Default: {@link LIFECYCLE_REF}'s tip. */
129
+ lifecycle?: string | null;
130
+ /** Overrides already spent, from the gate's own ledger ({@link spentOverrides}). */
131
+ spent?: readonly AppliedOverrideRecord[];
132
+ /** ISO-8601 now. */
133
+ now?: string;
134
+ }
135
+ /** Decide one ref update against the policy at base. Never throws for a policy or an envelope it can't read: it refuses. */
136
+ export declare function decideRefUpdate(input: RefGateInput): RefDecision;
137
+ /** Where a decision is made: the remote's hook, the developer's hook, a forge status job or a plain check. */
138
+ export type RefGateSite = "pre-receive" | "pre-push" | "status" | "check";
139
+ /** A line of the gate's ledger. */
140
+ export interface RefGateLedgerLine extends RefDecision {
141
+ version: 1;
142
+ kind: "ref-update";
143
+ site: RefGateSite;
144
+ timestamp: string;
145
+ /** Set on every line of a push the remote refused as a whole: an override it would have spent stays unspent. */
146
+ push?: "refused";
147
+ }
148
+ /** The gate's ledger file in the git directory of `repo`, `<git dir>/chant/ref-gate.jsonl`. */
149
+ export declare function refGateLedgerPath(repo: string): string;
150
+ export declare function appendRefGateLedger(path: string, lines: readonly RefGateLedgerLine[]): void;
151
+ export declare function readRefGateLedger(path: string): RefGateLedgerLine[];
152
+ /** The overrides the ledger's admitted updates spent: an update the remote took, or a status that passed, under an override. A pre-push or a plain check spends nothing. */
153
+ export declare function spentOverrides(lines: readonly RefGateLedgerLine[]): AppliedOverrideRecord[];
154
+ /** pre-receive's stdin: `<old> <new> <ref>` per line. */
155
+ export declare function parsePreReceive(text: string): RefUpdate[];
156
+ /** pre-push's stdin: `<local ref> <local sha> <remote ref> <remote sha>` per line, as updates of the remote ref. */
157
+ export declare function parsePrePush(text: string): RefUpdate[];
158
+ export declare class RefUpdateInputError extends Error {
159
+ }
160
+ export interface SiteResult {
161
+ ok: boolean;
162
+ decisions: RefDecision[];
163
+ ledger: string;
164
+ }
165
+ /**
166
+ * The remote's pre-receive hook: decide every update of the push, with the
167
+ * notes and the `chant/lifecycle` tip the push itself brings when it brings
168
+ * them, and write one ledger line per update. git refuses the whole push when
169
+ * the hook fails, so overrides are spent only when every update is admitted.
170
+ */
171
+ export declare function runPreReceive(repo: string, stdin: string, opts?: {
172
+ ledger?: string;
173
+ now?: string;
174
+ }): SiteResult;
175
+ /**
176
+ * The developer's pre-push hook: the same decision against the local
177
+ * repository, before the network. The policy is read at the remote's tip
178
+ * when the repository holds it, else at the default base. It spends nothing.
179
+ */
180
+ export declare function runPrePush(repo: string, stdin: string, opts?: {
181
+ ledger?: string;
182
+ now?: string;
183
+ base?: (repo: string) => string | null;
184
+ }): SiteResult;
185
+ /** What the gate says about one decision: each missing check and its command, and how to override a blocked one. */
186
+ export declare function describeDecision(d: RefDecision): string[];
187
+ //# sourceMappingURL=ref-gate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ref-gate.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ref-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAQH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAQL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAK7B,gHAAgH;AAChH,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAC9D,6DAA6D;AAC7D,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAC1D,mEAAmE;AACnE,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAIhD,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,wGAAyI,CAAC;AAC3K,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,sLAQS,CAAC;AAC3C,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,6GAA6G;AAC7G,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,YAAY,CAAC;IACvD,0DAA0D;IAC1D,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,qEAAqE;IACrE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAWD,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEtE;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,CAiBzK;AAID,2GAA2G;AAC3G,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAezD;AAgBD,0HAA0H;AAC1H,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE,CAK1F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAE,MAA2B,GAAG,IAAI,CAE3H;AA0DD,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE;AAQD,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;IAClB,mIAAmI;IACnI,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oFAAoF;IACpF,KAAK,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzC,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4HAA4H;AAC5H,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAuDhE;AAID,8GAA8G;AAC9G,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1E,mCAAmC;AACnC,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gHAAgH;IAChH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI,CAI3F;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAYnE;AAED,4KAA4K;AAC5K,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAAG,qBAAqB,EAAE,CAU3F;AAOD,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAUzD;AAED,oHAAoH;AACpH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAUtD;AAED,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAIjD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAsBnH;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;CAAO,GAAG,UAAU,CAUxJ;AAMD,oHAAoH;AACpH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,EAAE,CAyBzD"}