rungate 0.7.0 → 0.8.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 (63) hide show
  1. package/hooks/ActionVerificationGate.hook.ts +96 -0
  2. package/hooks/AgentBriefGuard.hook.ts +38 -0
  3. package/hooks/AgentVerdictCapture.hook.ts +87 -0
  4. package/hooks/AutoVerifyGate.hook.ts +79 -0
  5. package/hooks/BashToolGuard.hook.ts +65 -0
  6. package/hooks/BashWriteGuard.hook.ts +60 -0
  7. package/hooks/CommitEnforcement.hook.ts +130 -0
  8. package/hooks/DocHygiene.hook.ts +148 -0
  9. package/hooks/GateEnforcement.hook.ts +58 -0
  10. package/hooks/GateResultProtection.hook.ts +69 -0
  11. package/hooks/HarnessAFKGate.hook.ts +85 -0
  12. package/hooks/HookCurrency.hook.ts +99 -0
  13. package/hooks/IssueCloseGuard.hook.ts +149 -0
  14. package/hooks/MergeGuard.hook.ts +58 -0
  15. package/hooks/PostCompact.hook.ts +60 -0
  16. package/hooks/ProjectStateSync.hook.ts +103 -0
  17. package/hooks/SkillGuard.hook.ts +69 -0
  18. package/hooks/SpecConformityTrigger.hook.ts +43 -0
  19. package/hooks/SpecSCGuard.hook.ts +123 -0
  20. package/hooks/StaleTTLCleanup.hook.ts +141 -0
  21. package/hooks/TaskCompleted.hook.ts +51 -0
  22. package/hooks/TeamInit.hook.ts +85 -0
  23. package/hooks/TestSuiteGuard.hook.ts +70 -0
  24. package/hooks/TestSuiteRelease.hook.ts +85 -0
  25. package/hooks/TopLevelCdGuard.hook.ts +108 -0
  26. package/hooks/VerifyPhaseLock.hook.ts +84 -0
  27. package/hooks/WorkflowStateGuard.hook.ts +40 -0
  28. package/hooks/lib/agent-config.json +9 -0
  29. package/hooks/lib/agentDetection.ts +201 -0
  30. package/hooks/lib/comment-template.ts +86 -0
  31. package/hooks/lib/findWorkflow.ts +101 -0
  32. package/hooks/lib/parseStdin.ts +37 -0
  33. package/hooks/lib/paths.ts +111 -0
  34. package/hooks/lib/utils.ts +338 -0
  35. package/lib/affected-tests.ts +29 -0
  36. package/lib/bash-write-guard.ts +373 -0
  37. package/lib/branch-cleanup.ts +279 -7
  38. package/lib/config-trackable.ts +9 -0
  39. package/lib/distribution-currency.ts +55 -5
  40. package/lib/failure-intake.ts +7 -1
  41. package/lib/gate-enforcement.ts +222 -28
  42. package/lib/gate-names.ts +72 -0
  43. package/lib/gate-result-protection.ts +427 -0
  44. package/lib/intake-sources.ts +380 -0
  45. package/lib/late-env-spawn.ts +331 -0
  46. package/lib/launch-base.ts +128 -5
  47. package/lib/paths.ts +96 -3
  48. package/lib/phase2-decomposition.ts +1 -1
  49. package/lib/published-artifact.ts +162 -18
  50. package/lib/sc-id-cross-tree.ts +84 -8
  51. package/lib/scaffold/ai-review-findings.ts +7 -1
  52. package/lib/scaffold/ai-review-step.ts +861 -116
  53. package/lib/scaffold/defaults.ts +82 -1
  54. package/lib/scaffold/steps.ts +436 -44
  55. package/lib/security-verdict.ts +1 -1
  56. package/lib/shell-path-interpolation.ts +594 -0
  57. package/lib/text-dependents.ts +875 -0
  58. package/lib/workflow-security.ts +29 -0
  59. package/lib/workflow-taint.ts +732 -0
  60. package/lib/worktree-cleanup.ts +65 -38
  61. package/lib/worktree-repo.ts +32 -2
  62. package/package.json +3 -1
  63. package/scripts/check-installed-hook-currency.ts +825 -0
@@ -10,8 +10,35 @@
10
10
  * - NEVER deletes protected branches (main, master)
11
11
  * - NEVER deletes branches with open PRs
12
12
  * - When PR check fails, refuses to delete (safety default)
13
+ * - When the repository slug cannot be resolved, refuses to delete (#1079)
13
14
  *
14
- * GitHub issue #516
15
+ * ## The slug is an authorization input, not a convenience (#1079)
16
+ *
17
+ * `hasOpenPR` decides whether a branch may be deleted, and it decides it by
18
+ * asking ONE repository. Until #1079 that repository defaulted to the literal
19
+ * `hornjason/pai-harness` whenever a caller passed no `repo` — and the only
20
+ * caller in the tree, `hooks/StaleTTLCleanup.hook.ts`, passes none. So on any
21
+ * project that is not this one the guard asked about the wrong repository,
22
+ * every branch came back "no open PR" because the branch is not in the
23
+ * repository being asked about, and the `git push origin --delete` below ran
24
+ * against the project's OWN origin.
25
+ *
26
+ * That is worse than a guard that fails. `0`, `{}`, `null` and silence are
27
+ * indistinguishable from success; a confident wrong answer does not even look
28
+ * like a missing reading. So the default is now a REFUSAL:
29
+ *
30
+ * - no `repo` → resolve it from the project's own `origin` remote, which is
31
+ * the same place the branch at risk lives;
32
+ * - `origin` unreadable, absent, or not a GitHub remote → `UNMEASURED`, and
33
+ * UNMEASURED blocks the deletion rather than permitting it.
34
+ *
35
+ * **Never reintroduce a literal here.** Making `repo` a required parameter
36
+ * would make this symptom go away and leave the next caller free to pass a
37
+ * slug derived from a config, an env var or a cache — the guard wrong again
38
+ * with no default to blame. What makes the fix durable is that an unresolvable
39
+ * slug refuses the delete, not that the parameter is mandatory.
40
+ *
41
+ * GitHub issues #516, #1079
15
42
  */
16
43
 
17
44
  import { spawnSync } from "child_process";
@@ -56,6 +83,23 @@ export interface CleanupStaleBranchesResult {
56
83
  readonly deleted: string[];
57
84
  readonly skipped: string[];
58
85
  readonly errors: string[];
86
+ /**
87
+ * `UNMEASURED` when the open-PR question could not be asked at all — today
88
+ * that means the repository slug could not be resolved. An empty `deleted`
89
+ * under `MEASURED` means nothing was eligible; under `UNMEASURED` it means
90
+ * nothing was CHECKED, and those are different facts.
91
+ */
92
+ readonly reading: CleanupReading;
93
+ }
94
+
95
+ export type CleanupReading = "MEASURED" | "UNMEASURED";
96
+
97
+ /** Where a resolved slug came from, or why there is none. */
98
+ export interface RepoSlugReading {
99
+ readonly slug: string | null;
100
+ readonly source: "caller" | "origin";
101
+ /** Present iff `slug` is null. */
102
+ readonly reason?: string;
59
103
  }
60
104
 
61
105
  // ── Constants ───────────────────────────────────────────────
@@ -63,6 +107,127 @@ export interface CleanupStaleBranchesResult {
63
107
  const PROTECTED_BRANCHES = new Set(["main", "master"]);
64
108
  const DEFAULT_MAX_AGE_DAYS = 7;
65
109
 
110
+ /**
111
+ * The branch-deletion arm is disarmed unless this is set (#1079).
112
+ *
113
+ * `hooks/StaleTTLCleanup.hook.ts` runs at EVERY SessionStart from the shared
114
+ * checkout, so a `git push origin --delete` reached from it is unattended and
115
+ * reaches every live session at once. `.claude/rungate/hooks.json` names this
116
+ * arming and the slug refusal above as the two things that must BOTH hold
117
+ * before the hook may be reconsidered for consumer deployment — "either alone
118
+ * is insufficient" — and `lib/orphan-reaper.ts` already arms its destructive
119
+ * arm the same way.
120
+ */
121
+ const ARM_ENV_VAR = "RUNGATE_BRANCH_CLEANUP";
122
+ const ARM_ENV_VALUE = "1";
123
+
124
+ /**
125
+ * Whether the caller's environment arms the branch-deletion arm.
126
+ *
127
+ * One exported binding so a case can drive it over the values that must NOT
128
+ * arm it. An inline `===` in a hook is a claim nothing executes — that is what
129
+ * #690 cost two days of, and `lib/orphan-reaper.ts` carries the same note.
130
+ */
131
+ export function branchCleanupArmedFromEnv(
132
+ env: Record<string, string | undefined> = process.env,
133
+ ): boolean {
134
+ return env[ARM_ENV_VAR] === ARM_ENV_VALUE;
135
+ }
136
+
137
+ // ── Repository slug resolution ──────────────────────────────
138
+
139
+ /**
140
+ * The `owner/repo` a GitHub remote URL names, or null if it names none.
141
+ *
142
+ * One binding, so there is one thing to mutate. A remote this cannot read —
143
+ * a local path, a non-GitHub host, a URL with no two path segments — is not a
144
+ * repository any PR question can be asked about, so it is null and not a
145
+ * guess.
146
+ */
147
+ export function githubSlugFromRemoteUrl(url: string): string | null {
148
+ const trimmed = url.trim();
149
+ if (!trimmed) return null;
150
+
151
+ // scp-style (git@github.com:owner/repo.git) and URL-style
152
+ // (https://github.com/owner/repo, ssh://git@github.com/owner/repo.git).
153
+ const m =
154
+ /^(?:[^@/]+@)?github\.com[:/]+(.+)$/i.exec(trimmed) ??
155
+ /^[a-z+]+:\/\/(?:[^@/]+@)?github\.com\/+(.+)$/i.exec(trimmed);
156
+ if (!m) return null;
157
+
158
+ const path = m[1].replace(/\.git$/i, "").replace(/\/+$/, "");
159
+ const parts = path.split("/").filter(Boolean);
160
+ if (parts.length !== 2) return null;
161
+
162
+ const [owner, repo] = parts;
163
+ if (!/^[A-Za-z0-9._-]+$/.test(owner) || !/^[A-Za-z0-9._-]+$/.test(repo)) {
164
+ return null;
165
+ }
166
+ if (owner === "." || owner === ".." || repo === "." || repo === "..") {
167
+ return null;
168
+ }
169
+ return `${owner}/${repo}`;
170
+ }
171
+
172
+ /**
173
+ * Resolve the repository the open-PR question must be asked about.
174
+ *
175
+ * A caller-supplied `repo` wins. Otherwise the slug comes from the project's
176
+ * own `origin` — the same place the branch at risk lives. There is no third
177
+ * option and deliberately no fallback literal: an unresolvable remote is
178
+ * `{ slug: null }`, and every caller treats that as a refusal.
179
+ */
180
+ export function resolveRepoSlug(opts: {
181
+ readonly projectRoot: string;
182
+ readonly repo?: string;
183
+ readonly executor?: CommandExecutor;
184
+ }): RepoSlugReading {
185
+ const { projectRoot, repo, executor = defaultExecutor } = opts;
186
+
187
+ if (repo && repo.trim()) {
188
+ return { slug: repo.trim(), source: "caller" };
189
+ }
190
+
191
+ const result = executor("git", [
192
+ "-C",
193
+ projectRoot,
194
+ "remote",
195
+ "get-url",
196
+ "origin",
197
+ ]);
198
+
199
+ if (result.status !== 0) {
200
+ return {
201
+ slug: null,
202
+ source: "origin",
203
+ reason:
204
+ `cannot read the 'origin' remote of ${projectRoot}: ` +
205
+ `${(result.stderr || "git exited non-zero").trim().slice(0, 200)}`,
206
+ };
207
+ }
208
+
209
+ const slug = githubSlugFromRemoteUrl(result.stdout);
210
+ if (!slug) {
211
+ return {
212
+ slug: null,
213
+ source: "origin",
214
+ reason:
215
+ `the 'origin' remote of ${projectRoot} is not a GitHub repository ` +
216
+ `this can ask about: ${result.stdout.trim().slice(0, 200) || "(empty)"}`,
217
+ };
218
+ }
219
+
220
+ return { slug, source: "origin" };
221
+ }
222
+
223
+ /** The sentence every refusal uses, so there is one string to mutate. */
224
+ function unresolvedSlugRefusal(reason: string): string {
225
+ return (
226
+ "Cannot resolve the repository to check for open PRs — refusing to " +
227
+ `delete (#1079): ${reason}`
228
+ );
229
+ }
230
+
66
231
  // ── Default executor ────────────────────────────────────────
67
232
 
68
233
  function defaultExecutor(cmd: string, args: readonly string[]): CommandResult {
@@ -79,14 +244,18 @@ function defaultExecutor(cmd: string, args: readonly string[]): CommandResult {
79
244
 
80
245
  // ── Core: check for open PRs via Octokit ────────────────────
81
246
 
247
+ /**
248
+ * `repoSlug` is REQUIRED and has no default. A caller that cannot supply one
249
+ * has not asked the question and must not reach this function — see the
250
+ * refusals in both entry points.
251
+ */
82
252
  async function hasOpenPR(
83
253
  branch: string,
84
- client?: GitHubClient,
85
- repo?: string,
254
+ client: GitHubClient | undefined,
255
+ repoSlug: string,
86
256
  ): Promise<{ hasPR: boolean; error?: string }> {
87
257
  try {
88
258
  const github = client || createGitHubClient();
89
- const repoSlug = repo || "hornjason/pai-harness";
90
259
  const prs = await listPRs(github, repoSlug, { state: "open", head: branch, per_page: 1 });
91
260
  return { hasPR: Array.isArray(prs) && prs.length > 0 };
92
261
  } catch (e: any) {
@@ -109,8 +278,19 @@ export async function cleanupBranch(opts: CleanupBranchOptions): Promise<Cleanup
109
278
  return { deleted: false, reason: `${branch} is a protected branch` };
110
279
  }
111
280
 
281
+ // Guard: the open-PR question must be asked about the repository the branch
282
+ // is actually in. No slug means the question cannot be asked (#1079).
283
+ const slugReading = resolveRepoSlug({ projectRoot, repo, executor });
284
+ if (!slugReading.slug) {
285
+ return {
286
+ deleted: false,
287
+ reason: "Cannot resolve the repository — refusing to delete",
288
+ error: unresolvedSlugRefusal(slugReading.reason!),
289
+ };
290
+ }
291
+
112
292
  // Check for open PRs via Octokit
113
- const prCheck = await hasOpenPR(branch, githubClient, repo);
293
+ const prCheck = await hasOpenPR(branch, githubClient, slugReading.slug);
114
294
  if (prCheck.error) {
115
295
  return {
116
296
  deleted: false,
@@ -132,6 +312,84 @@ export async function cleanupBranch(opts: CleanupBranchOptions): Promise<Cleanup
132
312
  return { deleted: true };
133
313
  }
134
314
 
315
+ // ── The SessionStart arm ────────────────────────────────────
316
+
317
+ export interface BranchCleanupArmReport {
318
+ readonly armed: boolean;
319
+ readonly reading: CleanupReading;
320
+ readonly deleted: number;
321
+ readonly lines: string[];
322
+ }
323
+
324
+ /**
325
+ * The whole branch-deletion arm of `hooks/StaleTTLCleanup.hook.ts`, decided
326
+ * here rather than in the hook.
327
+ *
328
+ * `specs/HOOK-ARCHITECTURE-SPEC.md` makes hooks thin triggers that delegate
329
+ * to `lib/`, and this arm is the one with an arming decision, an UNMEASURED
330
+ * reading and three log shapes in it — all of which are behaviour a case can
331
+ * drive here and cannot drive inside a hook. `reapOrphans`/`reapReportLines`
332
+ * in `lib/orphan-reaper.ts` is the same split for the same reason.
333
+ *
334
+ * Silence is reserved for "armed, measured, nothing stale". A disarmed arm
335
+ * and an UNMEASURED one both say so by name, because zero deletions has three
336
+ * causes here and only one of them is a clean sweep.
337
+ */
338
+ export async function runBranchCleanupArm(opts: {
339
+ readonly projectRoot: string;
340
+ readonly maxAgeDays?: number;
341
+ readonly env?: Record<string, string | undefined>;
342
+ readonly executor?: CommandExecutor;
343
+ readonly githubClient?: GitHubClient;
344
+ readonly repo?: string;
345
+ }): Promise<BranchCleanupArmReport> {
346
+ const { projectRoot, maxAgeDays = DEFAULT_MAX_AGE_DAYS, env } = opts;
347
+
348
+ if (!branchCleanupArmedFromEnv(env ?? process.env)) {
349
+ return {
350
+ armed: false,
351
+ reading: "UNMEASURED",
352
+ deleted: 0,
353
+ lines: [
354
+ `BRANCH cleanup [${projectRoot}]: disarmed — set ` +
355
+ `${ARM_ENV_VAR}=${ARM_ENV_VALUE} to delete stale remote branches`,
356
+ ],
357
+ };
358
+ }
359
+
360
+ const br = await cleanupStaleBranches({
361
+ projectRoot,
362
+ maxAgeDays,
363
+ executor: opts.executor,
364
+ githubClient: opts.githubClient,
365
+ repo: opts.repo,
366
+ });
367
+
368
+ if (br.reading === "UNMEASURED") {
369
+ return {
370
+ armed: true,
371
+ reading: "UNMEASURED",
372
+ deleted: 0,
373
+ lines: [
374
+ `BRANCH cleanup [${projectRoot}]: UNMEASURED — no branch was ` +
375
+ `checked: ${br.errors.join("; ")}`,
376
+ ],
377
+ };
378
+ }
379
+
380
+ return {
381
+ armed: true,
382
+ reading: "MEASURED",
383
+ deleted: br.deleted.length,
384
+ lines: br.deleted.length
385
+ ? [
386
+ `BRANCH cleanup [${projectRoot}]: armed, deleted ` +
387
+ `${br.deleted.length} stale remote branches`,
388
+ ]
389
+ : [],
390
+ };
391
+ }
392
+
135
393
  // ── cleanupStaleBranches ────────────────────────────────────
136
394
 
137
395
  /**
@@ -154,8 +412,20 @@ export async function cleanupStaleBranches(
154
412
  deleted: [],
155
413
  skipped: [],
156
414
  errors: [],
415
+ reading: "MEASURED",
157
416
  };
158
417
 
418
+ // Resolve the subject of the open-PR question BEFORE listing anything.
419
+ // Resolved once, outside the loop: it is a property of the project, not of
420
+ // a branch, and asking per-branch would be N chances to answer differently
421
+ // about one repository (#1079).
422
+ const slugReading = resolveRepoSlug({ projectRoot, repo, executor });
423
+ if (!slugReading.slug) {
424
+ (result.errors as string[]).push(unresolvedSlugRefusal(slugReading.reason!));
425
+ return { ...result, reading: "UNMEASURED" };
426
+ }
427
+ const repoSlug = slugReading.slug;
428
+
159
429
  // List remote branches with their committer dates
160
430
  const refList = executor("git", [
161
431
  "-C",
@@ -169,7 +439,9 @@ export async function cleanupStaleBranches(
169
439
  (result.errors as string[]).push(
170
440
  `Failed to list remote branches: ${refList.stderr}`
171
441
  );
172
- return result;
442
+ // Nothing was checked, so an empty `deleted` here must not read as
443
+ // "nothing was eligible" either — same distinction as the slug refusal.
444
+ return { ...result, reading: "UNMEASURED" };
173
445
  }
174
446
 
175
447
  const lines = refList.stdout.trim().split("\n").filter(Boolean);
@@ -196,7 +468,7 @@ export async function cleanupStaleBranches(
196
468
  if (ageSeconds < maxAgeSeconds) continue;
197
469
 
198
470
  // Check for open PRs via Octokit
199
- const prCheck = await hasOpenPR(branchName, githubClient, repo);
471
+ const prCheck = await hasOpenPR(branchName, githubClient, repoSlug);
200
472
  if (prCheck.error) {
201
473
  (result.errors as string[]).push(
202
474
  `Cannot check PRs for ${branchName}: ${prCheck.error}`
@@ -147,6 +147,15 @@ function git(root: string, args: string[], input?: string) {
147
147
  encoding: "utf-8",
148
148
  timeout: 120_000,
149
149
  maxBuffer: 16 * 1024 * 1024,
150
+ // The child gets the environment this process HAS, not the one it
151
+ // started with. Under Bun those differ: a `process.env` write made
152
+ // after start does not reach a child given no `env` option, and under
153
+ // Node it does (#1096, measured with a Node control). Nothing in
154
+ // production writes these late, so this changes no shipped behaviour —
155
+ // what it changes is that `test/config-trackable.test.ts`'s hermetic
156
+ // HOME now reaches the git THIS function spawns, which is the half its
157
+ // fixture was written for and the half that was inert.
158
+ env: { ...process.env },
150
159
  });
151
160
  if (r.error) return { status: -1, stdout: "", stderr: r.error.message };
152
161
  return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
@@ -66,8 +66,11 @@
66
66
  */
67
67
  import {
68
68
  contentAgrees,
69
+ STANDING_CAUSE_HEADLINE,
69
70
  type ArtifactStanding,
70
71
  type ContentDifference,
72
+ type StandingCause,
73
+ type UnmeasuredReason,
71
74
  } from "./published-artifact";
72
75
 
73
76
  /**
@@ -103,6 +106,37 @@ export interface DistributionCurrency {
103
106
  publishedVersion: string | null;
104
107
  /** Non-empty exactly when `reading` is `UNMEASURED`. */
105
108
  unmeasuredReasons: string[];
109
+ /**
110
+ * WHICH condition produced the refusal (#1117). Empty when `CURRENT`.
111
+ * Never an input to `currencyRefusal` — a cause makes a red legible, it
112
+ * does not decide whether there is one.
113
+ */
114
+ causes: StandingCause[];
115
+ }
116
+
117
+ /**
118
+ * The conditions behind THIS reading, which is not the standing's question.
119
+ *
120
+ * `standingCauses` answers it for `artifactStanding`'s label. This answers it
121
+ * for the consumer's question, and the two genuinely disagree on an input
122
+ * this module already names: a tree at `0.7.0` against a published `0.6.0`
123
+ * whose content differs is `AHEAD` with no cause at all, and `STALE` with
124
+ * `CONTENT` — because a consumer still cannot obtain this tree. Reusing
125
+ * `standingCauses` here would make the version ordering an input to this
126
+ * module after all, which is exactly what the header says it is not.
127
+ *
128
+ * The SENTENCES are not restated: both selectors render through
129
+ * `STANDING_CAUSE_HEADLINE`, so there is one declaring position for the text
130
+ * and two readings that select from it.
131
+ */
132
+ function currencyCauses(reading: CurrencyReading, unmeasured: UnmeasuredReason[]): StandingCause[] {
133
+ if (reading === "UNMEASURED") {
134
+ const seen: StandingCause[] = [];
135
+ for (const r of unmeasured) if (!seen.includes(r.cause)) seen.push(r.cause);
136
+ return seen.length > 0 ? seen : ["UNCLASSIFIED"];
137
+ }
138
+ if (reading === "STALE") return ["CONTENT"];
139
+ return [];
106
140
  }
107
141
 
108
142
  /**
@@ -126,19 +160,23 @@ export function distributionCurrency(s: ArtifactStanding): DistributionCurrency
126
160
  publishedVersion: s.publishedVersion,
127
161
  };
128
162
  if (s.reading === "UNMEASURED" || d === null) {
163
+ const unmeasured: UnmeasuredReason[] =
164
+ s.unmeasured.length > 0
165
+ ? s.unmeasured
166
+ : [{ cause: "UNCLASSIFIED", text: "the content comparison was not performed" }];
129
167
  return {
130
168
  ...base,
131
169
  reading: "UNMEASURED",
132
- unmeasuredReasons:
133
- s.unmeasuredReasons.length > 0
134
- ? s.unmeasuredReasons
135
- : ["the content comparison was not performed"],
170
+ unmeasuredReasons: unmeasured.map(r => r.text),
171
+ causes: currencyCauses("UNMEASURED", unmeasured),
136
172
  };
137
173
  }
174
+ const reading: CurrencyReading = contentAgrees(d) ? "CURRENT" : "STALE";
138
175
  return {
139
176
  ...base,
140
- reading: contentAgrees(d) ? "CURRENT" : "STALE",
177
+ reading,
141
178
  unmeasuredReasons: [],
179
+ causes: currencyCauses(reading, []),
142
180
  };
143
181
  }
144
182
 
@@ -148,10 +186,15 @@ export function distributionCurrency(s: ArtifactStanding): DistributionCurrency
148
186
  * One exported binding, so there is one thing to mutate. A second predicate
149
187
  * over the same fields would always agree with this one and would survive any
150
188
  * mutation of it.
189
+ *
190
+ * `c.causes` leads each message (#1117) and is read by neither branch: the
191
+ * set of states this refuses is exactly what it was before the cause existed.
151
192
  */
152
193
  export function currencyRefusal(c: DistributionCurrency): string | null {
194
+ const why = currencyHeadline(c);
153
195
  if (c.reading === "UNMEASURED") {
154
196
  return (
197
+ `${why} ` +
155
198
  `UNMEASURED: nothing was compared — ${c.unmeasuredReasons.join("; ")}. ` +
156
199
  `A reading that could not be taken is not one that passed, so this exits ` +
157
200
  `non-zero rather than reporting that the distribution is fine.`
@@ -160,6 +203,7 @@ export function currencyRefusal(c: DistributionCurrency): string | null {
160
203
  if (c.reading === "STALE") {
161
204
  const n = c.staleFiles.length + c.missingFiles.length + c.removedFiles.length;
162
205
  return (
206
+ `${why} ` +
163
207
  `STALE: a consumer running \`bunx rungate\` today does NOT get this tree. ` +
164
208
  `rungate@${c.publishedVersion} on the registry differs from what this tree ` +
165
209
  `would publish in ${n} files — ${c.staleFiles.length} whose bytes differ, ` +
@@ -173,10 +217,16 @@ export function currencyRefusal(c: DistributionCurrency): string | null {
173
217
  return null;
174
218
  }
175
219
 
220
+ /** Every condition behind this refusal, as sentences. `""` when nothing refuses. */
221
+ export function currencyHeadline(c: DistributionCurrency): string {
222
+ return c.causes.map(x => STANDING_CAUSE_HEADLINE[x]).join(" ");
223
+ }
224
+
176
225
  /** Every number this reading produced, whether or not it refuses. */
177
226
  export function currencyReportLines(c: DistributionCurrency): string[] {
178
227
  return [
179
228
  `distribution currency: ${c.reading}`,
229
+ ` condition ${c.causes.length > 0 ? c.causes.join(", ") : "none"}`,
180
230
  ` published version ${c.publishedVersion ?? "UNREAD"}`,
181
231
  ` commits since its tag ${c.commitsAhead ?? "UNREAD"}`,
182
232
  ` files differing in bytes ${c.staleFiles.length}`,
@@ -79,7 +79,13 @@ import { join } from "path";
79
79
  import { contentHash } from "./content-hash";
80
80
 
81
81
  /** Where a candidate's evidence came from. */
82
- export type EvidenceKind = "fix-commit" | "revert-commit";
82
+ /**
83
+ * `gate-refusal` is produced by `lib/intake-sources.ts`, not by this module
84
+ * (#545). It lives here because `CandidateEvidence` is the one declaration
85
+ * every producer writes against — a second kind union would be two tables
86
+ * agreeing until they did not.
87
+ */
88
+ export type EvidenceKind = "fix-commit" | "revert-commit" | "gate-refusal";
83
89
 
84
90
  export interface CandidateEvidence {
85
91
  kind: EvidenceKind;