rungate 0.8.1 → 0.8.2

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.
@@ -28,7 +28,41 @@
28
28
  * one is only catchable if the file records BOTH versions. Checking the
29
29
  * recorded published version against the registry alone stays green through
30
30
  * a version bump, because the bump does not move either of those two values.
31
+ *
32
+ * ## Why the published half stopped being an equality (#1237)
33
+ *
34
+ * It was `standing.published === registryLatest`, and that equality cannot be
35
+ * true across a release. `package.json` is moved by the bump commit, the
36
+ * registry is moved by `npm publish`, and the standing line is moved by
37
+ * somebody remembering — three legs, two with a mechanism. So **every publish
38
+ * reddened `main`**, and the repair was always a human retyping a markdown
39
+ * file: `b7281397` and `803e1e66`, both on 2026-10-22, both one line.
40
+ *
41
+ * `SUCCESS.md` is DA-owned (#296), so the agents who hit the failure were
42
+ * precisely the agents forbidden to clear it. That is what made it structural
43
+ * rather than a slip, and it is why the fix is in the check and not in the
44
+ * file.
45
+ *
46
+ * The replacement is a BOUND, not a removal: the line may name `latest` or
47
+ * the release immediately before it, and nothing else. One release of lag is
48
+ * the most a publish can open up, and the next bump commit closes it — so a
49
+ * line two releases behind is still stale, a line naming a version the
50
+ * registry never served is still refused, and an absent line is still a
51
+ * violation.
52
+ *
53
+ * The tree half keeps its equality, deliberately. It is the one leg that IS
54
+ * maintainable atomically: whoever bumps `package.json` can edit this line in
55
+ * the same diff, and that pull request's own CI tells them before it merges.
56
+ *
57
+ * ## And the state none of this could see
58
+ *
59
+ * A bump commit that updates both halves of the standing line satisfies every
60
+ * equality the old check made — including when the release never happens. So
61
+ * *bumped and never published* was invisible here, and `main` could claim a
62
+ * version no consumer could install indefinitely. `lib/publish-window.ts`
63
+ * classifies that case and this module refuses it.
31
64
  */
65
+ import type { PublishState } from "./publish-window";
32
66
  export interface DistributionStanding {
33
67
  /** The version the standing measurements were taken against. */
34
68
  tree: string;
@@ -88,7 +122,7 @@ export async function publishedVersion(
88
122
  export function distributionViolations(
89
123
  standing: DistributionStanding | null,
90
124
  treeVersion: string,
91
- publishedNow: string,
125
+ registry: RegistryReading,
92
126
  ): string[] {
93
127
  if (standing === null) {
94
128
  return [
@@ -96,6 +130,13 @@ export function distributionViolations(
96
130
  "a tree, and nothing says which tree a consumer can install",
97
131
  ];
98
132
  }
133
+ if (registry.state === "UNMEASURED") {
134
+ return [
135
+ "the registry was not read, so nothing here was compared — UNMEASURED. A " +
136
+ "reading nobody took is not a reading that passed, and reporting the " +
137
+ "distribution as fine on it is the fail-open this check exists to avoid",
138
+ ];
139
+ }
99
140
  const out: string[] = [];
100
141
  if (standing.tree !== treeVersion) {
101
142
  out.push(
@@ -103,11 +144,41 @@ export function distributionViolations(
103
144
  `package.json says the tree is ${treeVersion} — the standing describes code that moved`,
104
145
  );
105
146
  }
106
- if (standing.published !== publishedNow) {
147
+ if (registry.state === "NEVER_PUBLISHED") {
107
148
  out.push(
108
- `SUCCESS.md says rungate@${standing.published} is published, the registry says ` +
109
- `${publishedNow} — the file's account of what a consumer can install is stale`,
149
+ `package.json declares ${treeVersion} and the registry does not serve it, with no ` +
150
+ `release tag for it inside the publish window — no consumer can install what main ` +
151
+ `says this tree is. Cut the release, or revert the bump`,
152
+ );
153
+ }
154
+ // The bound, and the whole of #1237: `latest` moves on `npm publish` and
155
+ // this line moves when a human edits a file, so one release of lag is the
156
+ // honest tolerance. Two is staleness, and a version in neither slot was
157
+ // never a reading of anything.
158
+ const allowed = [registry.latest, registry.previous].filter((v): v is string => v !== null);
159
+ if (!allowed.includes(standing.published)) {
160
+ out.push(
161
+ `SUCCESS.md says rungate@${standing.published} is published; the registry serves ` +
162
+ `${registry.latest ?? "nothing readable"} and served ${registry.previous ?? "nothing"} ` +
163
+ `before it — the file's account of what a consumer can install is stale. The line may ` +
164
+ `lag by one release, which is what a publish opens up; this is further behind than that`,
110
165
  );
111
166
  }
112
167
  return out;
113
168
  }
169
+
170
+ /**
171
+ * The registry side of the comparison, taken once by the caller.
172
+ *
173
+ * `state` comes from `publishState` in `lib/publish-window.ts` and is the
174
+ * same classification `.github/workflows/ai-review.yml`'s pin reads, so the
175
+ * two checks cannot disagree about which state a release is in — only about
176
+ * what to do with it. Before #1226 they disagreed about both.
177
+ */
178
+ export interface RegistryReading {
179
+ state: PublishState;
180
+ /** The `latest` dist-tag. */
181
+ latest: string | null;
182
+ /** The release immediately before it, by publish time. */
183
+ previous: string | null;
184
+ }
@@ -80,12 +80,20 @@ import { contentHash } from "./content-hash";
80
80
 
81
81
  /** Where a candidate's evidence came from. */
82
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
83
+ * `gate-refusal` is produced by `lib/intake-sources.ts`, and `finding` by
84
+ * `lib/finding-arbiter.ts` (#1187) — neither by this module (#545). They
85
+ * live here because `CandidateEvidence` is the one declaration every
86
+ * producer writes against — a second kind union would be two tables
86
87
  * agreeing until they did not.
88
+ *
89
+ * `finding` was added rather than reusing one of the others because a
90
+ * finding that survived the filing arbiter is a different kind of
91
+ * observation from a commit subject or a gate refusal: it carries a symptom
92
+ * key, and the thing being budgeted is an ISSUE rather than a rule. The
93
+ * ranking and the cap are `lib/rule-promotion.ts`'s either way, which is the
94
+ * point of adding a member here instead of writing a second promoter.
87
95
  */
88
- export type EvidenceKind = "fix-commit" | "revert-commit" | "gate-refusal";
96
+ export type EvidenceKind = "fix-commit" | "revert-commit" | "gate-refusal" | "finding";
89
97
 
90
98
  export interface CandidateEvidence {
91
99
  kind: EvidenceKind;
@@ -0,0 +1,81 @@
1
+ /**
2
+ * The file extensions under a directory (#1200).
3
+ *
4
+ * A LEAF module, in the shape `lib/local-calendar-day.ts` and
5
+ * `lib/readdir-sorted.ts` established: one exported binding, no relative
6
+ * imports, so there is exactly one thing to mutate and every call site names
7
+ * the same rule.
8
+ *
9
+ * ## Why this exists
10
+ *
11
+ * This was four lines, copied into all three of the scanners that build
12
+ * CODE-MAP.md's `## Directory Structure` table —
13
+ * `scripts/generate-code-map.ts`, `lib/scanner.ts` and
14
+ * `generateCodeMapInline` in `lib/scaffold/steps.ts`:
15
+ *
16
+ * const files = readdirSync(full, { recursive: true }).map(String);
17
+ * const exts = new Set(files.map(f => f.split(".").pop()).filter(Boolean));
18
+ * dirs.push({ name: entry, types: [...exts].slice(0, 5) });
19
+ *
20
+ * Every clause of that is wrong, and the shipped `CODE-MAP.md` said so:
21
+ *
22
+ * | test/ | ts, unit, types, json, fixtures |
23
+ * | evals/ | marcus-tdd-order, marcus-tdd-vs-speed, marcus-surgical, … |
24
+ * | scripts/| ts, sh, git-hooks, lib, git-hooks/pre-push |
25
+ *
26
+ * - `readdirSync(…, { recursive: true })` returns **directories as well as
27
+ * files**, and `"unit".split(".").pop()` is `"unit"`. So every
28
+ * extensionless entry — every directory, every `LICENSE`, every
29
+ * `Makefile` — contributed its own name as a "type", and not one entry in
30
+ * the `evals/` row was a file type.
31
+ * - Without `withFileTypes` the strings are **relative paths**, so the split
32
+ * ran on `git-hooks/pre-push` rather than on a basename.
33
+ * - A leading dot does not open an extension. `.gitignore` yielded
34
+ * `gitignore`.
35
+ * - `.slice(0, 5)` over a `Set` fed by a raw `readdirSync` is
36
+ * **filesystem-ordered**: five of N chosen by APFS or ext4, which is the
37
+ * defect `lib/readdir-sorted.ts` exists for, one indirection further in.
38
+ * Sorting here rather than at the three call sites is the same argument
39
+ * that file makes — one binding is one thing to forget.
40
+ *
41
+ * Measured on this repository, 10 of the 14 rows changed; `evals/` went from
42
+ * five directory names to `json, md, sh, ts, yaml`.
43
+ *
44
+ * ## Why the cap stays
45
+ *
46
+ * `MAX_TYPES` bounds a table cell, and #1200 asked only that the five be
47
+ * chosen deterministically rather than that they be all of them. Ascending
48
+ * order is also the drift-resistant key: a file added to a directory cannot
49
+ * move it, and only a brand-new extension can — unlike a frequency ranking,
50
+ * which is the per-directory census #1163 removed wearing an indirection.
51
+ *
52
+ * Errors are NOT caught here. An unreadable tree is the caller's to decide
53
+ * about, and all three callers already wrap this in the `try` that used to
54
+ * hold the four lines; swallowing it would turn "could not read" into "has
55
+ * no files", which is `.claude/rules/checks-must-be-able-to-fail.md`'s
56
+ * fail-open shape.
57
+ */
58
+ import { readdirSync } from "fs";
59
+
60
+ /** How many extensions a `Types` cell carries, at most. */
61
+ export const MAX_TYPES = 5;
62
+
63
+ export function fileExtensions(dir: string, limit: number = MAX_TYPES): string[] {
64
+ const exts = new Set<string>();
65
+ for (const entry of readdirSync(dir, { recursive: true, withFileTypes: true })) {
66
+ if (!entry.isFile()) continue;
67
+ // `entry.name` is a basename even under `recursive` — the directory part
68
+ // is on `parentPath` — so this cannot pick up a path separator.
69
+ const dot = entry.name.lastIndexOf(".");
70
+ // `<= 0` covers both "no dot at all" and a dotfile like `.gitignore`,
71
+ // whose leading dot does not open an extension.
72
+ if (dot <= 0) continue;
73
+ const ext = entry.name.slice(dot + 1);
74
+ if (ext) exts.add(ext);
75
+ }
76
+ // Plain `.sort()`: lexicographic over UTF-16 code units is
77
+ // locale-independent, unlike `localeCompare`. A generated file whose
78
+ // contents depend on the runner's locale is the same defect in a different
79
+ // coat (`lib/readdir-sorted.ts`).
80
+ return [...exts].sort().slice(0, limit);
81
+ }