rungate 0.6.0 → 0.7.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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +81 -16
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-id-cross-tree.ts +19 -7
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +241 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,525 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a consumer actually installs, compared against this tree — by CONTENT,
|
|
3
|
+
* not by version string (#875).
|
|
4
|
+
*
|
|
5
|
+
* ## The defect this exists for
|
|
6
|
+
*
|
|
7
|
+
* `lib/distribution-standing.ts` compares three spellings of a NUMBER:
|
|
8
|
+
* `package.json`'s version, `SUCCESS.md`'s standing line, and the registry's
|
|
9
|
+
* `latest`. All three agreeing proves the repository and the registry agree
|
|
10
|
+
* about a NAME. It proves nothing about what is behind the name.
|
|
11
|
+
*
|
|
12
|
+
* Measured 2026-10-21, with all three agreeing on `0.6.0` and the check
|
|
13
|
+
* reporting standing fine:
|
|
14
|
+
*
|
|
15
|
+
* | Reading | Value |
|
|
16
|
+
* |---|---|
|
|
17
|
+
* | files `npm pack --dry-run` would publish | 235 |
|
|
18
|
+
* | files in the published `rungate@0.6.0` tarball | 192 |
|
|
19
|
+
* | published files whose bytes differ from the tree | 42 |
|
|
20
|
+
* | files the published artifact does not have at all | 43 |
|
|
21
|
+
*
|
|
22
|
+
* Same label, different software. That is the defect class
|
|
23
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` calls *a detector narrower
|
|
24
|
+
* than what it detects*: the version string is the cheapest proxy for "the
|
|
25
|
+
* registry and the tree agree", and a proxy is a thing that can be satisfied
|
|
26
|
+
* directly without fixing anything. Here it is satisfied permanently, because
|
|
27
|
+
* the numbers keep agreeing for as long as nobody bumps.
|
|
28
|
+
*
|
|
29
|
+
* ## Why a content mismatch is not automatically a failure
|
|
30
|
+
*
|
|
31
|
+
* A repository that is AHEAD of its last release is the normal state between
|
|
32
|
+
* releases, so a check that reddened on "the tree differs from npm" would be
|
|
33
|
+
* red every day and would teach everyone to stop reading it. The distinction
|
|
34
|
+
* this module is built around is which of two things the difference means:
|
|
35
|
+
*
|
|
36
|
+
* | Versions | Content | Reading | Violation |
|
|
37
|
+
* |---|---|---|---|
|
|
38
|
+
* | tree > published | — | `AHEAD` | no — unreleased work is what a repo is for |
|
|
39
|
+
* | tree < published | — | `BEHIND` | no — a stale checkout, not a distribution defect |
|
|
40
|
+
* | equal | identical | `MATCHED` | no |
|
|
41
|
+
* | **equal** | **differs** | **`DIVERGED`** | **yes — the label lies** |
|
|
42
|
+
* | could not be taken | — | `UNMEASURED` | yes |
|
|
43
|
+
*
|
|
44
|
+
* `DIVERGED` is the only content state that is a defect, and it is a defect
|
|
45
|
+
* because of what the version string claims, not because of the bytes. A
|
|
46
|
+
* consumer running `bun add -d rungate@0.6.0` and a maintainer reading `0.6.0`
|
|
47
|
+
* in `package.json` are talking about different trees and nothing says so.
|
|
48
|
+
*
|
|
49
|
+
* ## UNMEASURED is a violation, deliberately
|
|
50
|
+
*
|
|
51
|
+
* `0`, `{}`, `null` and `SKIP` are indistinguishable from success
|
|
52
|
+
* (`.claude/rules/config-access.md`). A guard with no failing input in the
|
|
53
|
+
* configuration it actually runs in is worse than no guard, because the green
|
|
54
|
+
* is read as evidence — so an unreachable registry, an absent `npm`, a tarball
|
|
55
|
+
* this module cannot parse and a pack that named no files all produce
|
|
56
|
+
* `UNMEASURED`, and `artifactViolations` refuses it with the same force it
|
|
57
|
+
* refuses `DIVERGED`.
|
|
58
|
+
*
|
|
59
|
+
* ## One binding per question
|
|
60
|
+
*
|
|
61
|
+
* `artifactStanding` is the only thing that decides a reading and
|
|
62
|
+
* `artifactViolations` is a projection of it, so they cannot disagree — two
|
|
63
|
+
* deciders that agree are behaviourally one guard and no behavioural test can
|
|
64
|
+
* tell them apart.
|
|
65
|
+
*
|
|
66
|
+
* ## The question this does NOT answer
|
|
67
|
+
*
|
|
68
|
+
* `artifactViolations` refuses a lying LABEL, so the cheapest way to clear it
|
|
69
|
+
* is to bump `package.json` — `DIVERGED` becomes `AHEAD`, the refusal goes
|
|
70
|
+
* away, and the published tree is exactly as stale as it was.
|
|
71
|
+
* `lib/distribution-currency.ts` asks the consumer's question instead — is the
|
|
72
|
+
* published artifact the content this tree would publish — which takes no
|
|
73
|
+
* version string as an input and so does not move under that bump. Run it with
|
|
74
|
+
* `bun scripts/check-distribution-currency.ts`; it exits non-zero when a
|
|
75
|
+
* consumer cannot obtain this tree.
|
|
76
|
+
*/
|
|
77
|
+
import { createHash } from "crypto";
|
|
78
|
+
import { readFileSync } from "fs";
|
|
79
|
+
import { join } from "path";
|
|
80
|
+
import { gunzipSync } from "zlib";
|
|
81
|
+
import { NPM_REGISTRY } from "./release-preflight";
|
|
82
|
+
|
|
83
|
+
/** One file in a publishable artifact, hashed by content. */
|
|
84
|
+
export interface ArtifactFile {
|
|
85
|
+
/** Path relative to the package root — `lib/conformity.ts`, never `package/lib/…`. */
|
|
86
|
+
path: string;
|
|
87
|
+
/** sha256 of the file's bytes, hex. */
|
|
88
|
+
sha256: string;
|
|
89
|
+
/** Bytes, so a reader can see the size of a difference without re-reading. */
|
|
90
|
+
size: number;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** Every npm tarball entry is prefixed with this directory. */
|
|
94
|
+
export const TARBALL_ROOT = "package/";
|
|
95
|
+
|
|
96
|
+
/** Raised by anything in this module that could not take its reading. */
|
|
97
|
+
export class ArtifactUnmeasured extends Error {}
|
|
98
|
+
|
|
99
|
+
function sha256(bytes: Uint8Array): string {
|
|
100
|
+
return createHash("sha256").update(bytes).digest("hex");
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Parse an uncompressed npm tarball into per-entry content hashes.
|
|
105
|
+
*
|
|
106
|
+
* Hand-rolled rather than extracted to disk: nothing from the registry is ever
|
|
107
|
+
* written to the filesystem, so there is no untrusted archive to unpack and no
|
|
108
|
+
* `tar` binary whose flags differ between macOS and CI.
|
|
109
|
+
*
|
|
110
|
+
* **Every way of failing to read throws.** A typeflag this does not understand
|
|
111
|
+
* — a pax extended header, a GNU long name, a symlink — is an entry whose name
|
|
112
|
+
* or content comes from somewhere this parser is not looking, and skipping it
|
|
113
|
+
* would silently shrink the published set, which makes the comparison agree for
|
|
114
|
+
* a reason that has nothing to do with the bytes. The header checksum is
|
|
115
|
+
* verified for the same reason: a misaligned read produces plausible garbage,
|
|
116
|
+
* and plausible garbage compares unequal, which reads as a finding.
|
|
117
|
+
*/
|
|
118
|
+
export function parseNpmTarball(tar: Uint8Array): ArtifactFile[] {
|
|
119
|
+
const b = Buffer.from(tar.buffer, tar.byteOffset, tar.byteLength);
|
|
120
|
+
const out: ArtifactFile[] = [];
|
|
121
|
+
let off = 0;
|
|
122
|
+
|
|
123
|
+
/** A list with nothing in it compares equal to anything. Refuse instead. */
|
|
124
|
+
const done = (): ArtifactFile[] => {
|
|
125
|
+
if (out.length === 0) throw new ArtifactUnmeasured("the tarball holds no files at all");
|
|
126
|
+
return out.sort((x, y) => (x.path < y.path ? -1 : 1));
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
while (off + 512 <= b.length) {
|
|
130
|
+
const header = b.subarray(off, off + 512);
|
|
131
|
+
if (header.every(x => x === 0)) return done();
|
|
132
|
+
|
|
133
|
+
// The checksum is the sum of every header byte with the checksum field
|
|
134
|
+
// itself read as spaces. If this does not agree we are not on a header.
|
|
135
|
+
const declared = parseInt(header.subarray(148, 156).toString("utf8").replace(/\0.*$/, "").trim(), 8);
|
|
136
|
+
let sum = 0;
|
|
137
|
+
for (let i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 0x20 : header[i];
|
|
138
|
+
if (!Number.isFinite(declared) || declared !== sum) {
|
|
139
|
+
throw new ArtifactUnmeasured(
|
|
140
|
+
`tarball header at byte ${off} has checksum ${declared} but its bytes sum to ${sum} — ` +
|
|
141
|
+
`the parser is not aligned on a header and anything it reported would be noise`,
|
|
142
|
+
);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
|
|
146
|
+
const prefix = header.subarray(345, 500).toString("utf8").replace(/\0.*$/, "");
|
|
147
|
+
const type = String.fromCharCode(header[156]);
|
|
148
|
+
const sizeField = header.subarray(124, 136).toString("utf8").replace(/\0.*$/, "").trim();
|
|
149
|
+
const size = parseInt(sizeField, 8);
|
|
150
|
+
if (!Number.isFinite(size) || size < 0) {
|
|
151
|
+
throw new ArtifactUnmeasured(`tarball entry ${name} declares an unreadable size ${JSON.stringify(sizeField)}`);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const dataStart = off + 512;
|
|
155
|
+
const dataEnd = dataStart + size;
|
|
156
|
+
if (dataEnd > b.length) {
|
|
157
|
+
throw new ArtifactUnmeasured(
|
|
158
|
+
`tarball entry ${name} declares ${size} bytes but the archive ends ${dataEnd - b.length} bytes short — truncated`,
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
if (type !== "0" && type !== "\0" && type !== "5") {
|
|
163
|
+
throw new ArtifactUnmeasured(
|
|
164
|
+
`tarball entry ${name} has typeflag ${JSON.stringify(type)}, which this parser does not read. ` +
|
|
165
|
+
`Skipping it would shrink the published file set and the comparison would agree for the wrong reason`,
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
if (type !== "5") {
|
|
170
|
+
const full = prefix ? `${prefix}/${name}` : name;
|
|
171
|
+
if (!full.startsWith(TARBALL_ROOT)) {
|
|
172
|
+
throw new ArtifactUnmeasured(`tarball entry ${full} is not under ${TARBALL_ROOT}`);
|
|
173
|
+
}
|
|
174
|
+
out.push({
|
|
175
|
+
path: full.slice(TARBALL_ROOT.length),
|
|
176
|
+
sha256: sha256(b.subarray(dataStart, dataEnd)),
|
|
177
|
+
size,
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
off = dataStart + Math.ceil(size / 512) * 512;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
// Falling out of the loop means the terminating zero blocks were never
|
|
185
|
+
// reached. Every tar npm writes ends with two of them, so their absence is a
|
|
186
|
+
// truncated download — and a truncated download yields a SHORT FILE LIST,
|
|
187
|
+
// which reads as "the published artifact has fewer files than the tree",
|
|
188
|
+
// i.e. as a finding rather than as the absence of a reading.
|
|
189
|
+
throw new ArtifactUnmeasured(
|
|
190
|
+
`the tarball ended after ${out.length} entries without its terminating zero blocks, ` +
|
|
191
|
+
`${b.length - off} bytes short of a header — the download is truncated`,
|
|
192
|
+
);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Download and hash what the registry actually serves for `pkg@version`.
|
|
197
|
+
*
|
|
198
|
+
* Reads only. Nothing here publishes, tags, or writes to the registry.
|
|
199
|
+
*/
|
|
200
|
+
export async function publishedArtifact(
|
|
201
|
+
pkg: string,
|
|
202
|
+
version: string,
|
|
203
|
+
opts: { fetchImpl?: typeof fetch; base?: string } = {},
|
|
204
|
+
): Promise<ArtifactFile[]> {
|
|
205
|
+
const base = opts.base ?? NPM_REGISTRY;
|
|
206
|
+
const f = opts.fetchImpl ?? fetch;
|
|
207
|
+
const bare = pkg.replace(/^@[^/]+\//, "");
|
|
208
|
+
const url = `${base}/${pkg}/-/${bare}-${version}.tgz`;
|
|
209
|
+
let res: Response;
|
|
210
|
+
try {
|
|
211
|
+
res = await f(url);
|
|
212
|
+
} catch (e) {
|
|
213
|
+
throw new ArtifactUnmeasured(`could not reach ${url}: ${(e as Error).message}`);
|
|
214
|
+
}
|
|
215
|
+
if (!res.ok) throw new ArtifactUnmeasured(`registry returned ${res.status} for ${url}`);
|
|
216
|
+
const gz = new Uint8Array(await res.arrayBuffer());
|
|
217
|
+
if (gz.length === 0) throw new ArtifactUnmeasured(`registry returned an empty body for ${url}`);
|
|
218
|
+
let plain: Buffer;
|
|
219
|
+
try {
|
|
220
|
+
plain = gunzipSync(gz);
|
|
221
|
+
} catch (e) {
|
|
222
|
+
throw new ArtifactUnmeasured(`${url} is not gzip: ${(e as Error).message}`);
|
|
223
|
+
}
|
|
224
|
+
return parseNpmTarball(plain);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** The shape `npm pack --dry-run --json` reports, narrowed to what is read here. */
|
|
228
|
+
export interface PackReading {
|
|
229
|
+
name: string;
|
|
230
|
+
version: string;
|
|
231
|
+
files: ArtifactFile[];
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** How a command is run, so a test can drive the reading without a real npm. */
|
|
235
|
+
export type RunCommand = (
|
|
236
|
+
cmd: string[],
|
|
237
|
+
cwd: string,
|
|
238
|
+
) => { status: number | null; stdout: string; stderr: string };
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* What `npm pack` would publish from `root`, hashed from disk.
|
|
242
|
+
*
|
|
243
|
+
* **The file list comes from npm, not from `package.json`'s `files[]`.**
|
|
244
|
+
* `files[]` is the declaration being checked — #484 is this repository's own
|
|
245
|
+
* instance of a published module reading a path `files[]` omitted — so a
|
|
246
|
+
* comparison built from it would be a comparison of the list with itself.
|
|
247
|
+
* `npm pack --dry-run` is the emitting side: it applies `files[]`, `.npmignore`,
|
|
248
|
+
* npm's always-included and always-excluded sets, and reports the result.
|
|
249
|
+
*/
|
|
250
|
+
export function localArtifact(root: string, run: RunCommand): PackReading {
|
|
251
|
+
const r = run(["npm", "pack", "--dry-run", "--json"], root);
|
|
252
|
+
if (r.status !== 0) {
|
|
253
|
+
throw new ArtifactUnmeasured(
|
|
254
|
+
`\`npm pack --dry-run --json\` exited ${r.status} in ${root}: ${r.stderr.trim() || "(no stderr)"}`,
|
|
255
|
+
);
|
|
256
|
+
}
|
|
257
|
+
let parsed: unknown;
|
|
258
|
+
try {
|
|
259
|
+
parsed = JSON.parse(r.stdout);
|
|
260
|
+
} catch {
|
|
261
|
+
throw new ArtifactUnmeasured(`\`npm pack --dry-run --json\` did not print JSON: ${r.stdout.slice(0, 200)}`);
|
|
262
|
+
}
|
|
263
|
+
const first = Array.isArray(parsed) ? (parsed[0] as Record<string, unknown> | undefined) : undefined;
|
|
264
|
+
if (!first || typeof first.name !== "string" || typeof first.version !== "string") {
|
|
265
|
+
throw new ArtifactUnmeasured("`npm pack --dry-run --json` reported no package name and version");
|
|
266
|
+
}
|
|
267
|
+
const entries = Array.isArray(first.files) ? (first.files as { path?: unknown }[]) : [];
|
|
268
|
+
if (entries.length === 0) {
|
|
269
|
+
// Zero files is not agreement with an empty artifact. It is a pack that
|
|
270
|
+
// read nothing, and an empty set compares equal to anything.
|
|
271
|
+
throw new ArtifactUnmeasured(`\`npm pack --dry-run\` named no files in ${root}`);
|
|
272
|
+
}
|
|
273
|
+
const files: ArtifactFile[] = entries.map(e => {
|
|
274
|
+
if (typeof e.path !== "string") throw new ArtifactUnmeasured("`npm pack` reported a file with no path");
|
|
275
|
+
const bytes = readFileSync(join(root, e.path));
|
|
276
|
+
return { path: e.path, sha256: sha256(bytes), size: bytes.length };
|
|
277
|
+
});
|
|
278
|
+
return { name: first.name, version: first.version, files: files.sort((a, b) => (a.path < b.path ? -1 : 1)) };
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/** Which paths are on one side only, and which are on both and differ. */
|
|
282
|
+
export interface ContentDifference {
|
|
283
|
+
onlyLocal: string[];
|
|
284
|
+
onlyPublished: string[];
|
|
285
|
+
differing: string[];
|
|
286
|
+
localCount: number;
|
|
287
|
+
publishedCount: number;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/** `true` when nothing is on one side only and nothing shared differs. */
|
|
291
|
+
export function contentAgrees(d: ContentDifference): boolean {
|
|
292
|
+
return d.onlyLocal.length === 0 && d.onlyPublished.length === 0 && d.differing.length === 0;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* The single place that compares two artifacts.
|
|
297
|
+
*
|
|
298
|
+
* A comparison over two empty sets agrees trivially, which is the vacuous
|
|
299
|
+
* shape this repository has shipped before, so an empty side REFUSES rather
|
|
300
|
+
* than returning a clean difference.
|
|
301
|
+
*/
|
|
302
|
+
export function contentDifference(local: ArtifactFile[], published: ArtifactFile[]): ContentDifference {
|
|
303
|
+
if (local.length === 0 || published.length === 0) {
|
|
304
|
+
throw new ArtifactUnmeasured(
|
|
305
|
+
`a content comparison needs both sides: local has ${local.length} files and published has ` +
|
|
306
|
+
`${published.length}. Two empty sets agree, and that agreement is not a reading`,
|
|
307
|
+
);
|
|
308
|
+
}
|
|
309
|
+
const l = new Map(local.map(f => [f.path, f.sha256]));
|
|
310
|
+
const p = new Map(published.map(f => [f.path, f.sha256]));
|
|
311
|
+
const onlyLocal: string[] = [];
|
|
312
|
+
const differing: string[] = [];
|
|
313
|
+
for (const [path, hash] of l) {
|
|
314
|
+
const other = p.get(path);
|
|
315
|
+
if (other === undefined) onlyLocal.push(path);
|
|
316
|
+
else if (other !== hash) differing.push(path);
|
|
317
|
+
}
|
|
318
|
+
const onlyPublished = [...p.keys()].filter(path => !l.has(path));
|
|
319
|
+
return {
|
|
320
|
+
onlyLocal: onlyLocal.sort(),
|
|
321
|
+
onlyPublished: onlyPublished.sort(),
|
|
322
|
+
differing: differing.sort(),
|
|
323
|
+
localCount: l.size,
|
|
324
|
+
publishedCount: p.size,
|
|
325
|
+
};
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
export type ArtifactReading = "MATCHED" | "DIVERGED" | "AHEAD" | "BEHIND" | "UNMEASURED";
|
|
329
|
+
|
|
330
|
+
export interface ArtifactStanding {
|
|
331
|
+
reading: ArtifactReading;
|
|
332
|
+
/** `package.json`'s version in the tree that was packed. */
|
|
333
|
+
treeVersion: string | null;
|
|
334
|
+
/** The registry's `latest`. */
|
|
335
|
+
publishedVersion: string | null;
|
|
336
|
+
/** `null` only when the comparison could not be performed. */
|
|
337
|
+
difference: ContentDifference | null;
|
|
338
|
+
/** Commits between the published tag and HEAD. `null` is a reading nobody took. */
|
|
339
|
+
commitsAhead: number | null;
|
|
340
|
+
/** Why `commitsAhead` is null, when it is. Reported; never gated on. */
|
|
341
|
+
distanceNote: string | null;
|
|
342
|
+
/** Non-empty exactly when `reading` is `UNMEASURED`. */
|
|
343
|
+
unmeasuredReasons: string[];
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** `0.6.0` → `[0,6,0]`; anything else → `null`. Prerelease suffixes are ignored. */
|
|
347
|
+
function parts(v: string): [number, number, number] | null {
|
|
348
|
+
const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
|
|
349
|
+
return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/** `-1`, `0`, `1`, or `null` when either side is not a version this can order. */
|
|
353
|
+
export function compareVersions(a: string, b: string): -1 | 0 | 1 | null {
|
|
354
|
+
const x = parts(a);
|
|
355
|
+
const y = parts(b);
|
|
356
|
+
if (!x || !y) return null;
|
|
357
|
+
for (let i = 0; i < 3; i++) {
|
|
358
|
+
if (x[i] !== y[i]) return x[i] > y[i] ? 1 : -1;
|
|
359
|
+
}
|
|
360
|
+
return 0;
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
/**
|
|
364
|
+
* The single place that turns the readings into a verdict.
|
|
365
|
+
*
|
|
366
|
+
* Pure: every input is passed in, so a case can construct any state including
|
|
367
|
+
* ones that cannot be produced on this machine today.
|
|
368
|
+
*/
|
|
369
|
+
export function artifactStanding(input: {
|
|
370
|
+
treeVersion: string | null;
|
|
371
|
+
publishedVersion: string | null;
|
|
372
|
+
difference: ContentDifference | null;
|
|
373
|
+
commitsAhead?: number | null;
|
|
374
|
+
distanceNote?: string | null;
|
|
375
|
+
unmeasuredReasons?: string[];
|
|
376
|
+
}): ArtifactStanding {
|
|
377
|
+
const base = {
|
|
378
|
+
treeVersion: input.treeVersion,
|
|
379
|
+
publishedVersion: input.publishedVersion,
|
|
380
|
+
difference: input.difference,
|
|
381
|
+
commitsAhead: input.commitsAhead ?? null,
|
|
382
|
+
distanceNote: input.distanceNote ?? null,
|
|
383
|
+
};
|
|
384
|
+
const reasons = [...(input.unmeasuredReasons ?? [])];
|
|
385
|
+
if (input.treeVersion === null) reasons.push("the tree's version could not be read");
|
|
386
|
+
if (input.publishedVersion === null) reasons.push("the registry's published version could not be read");
|
|
387
|
+
if (input.difference === null) reasons.push("the content comparison was not performed");
|
|
388
|
+
if (reasons.length > 0) {
|
|
389
|
+
return { ...base, reading: "UNMEASURED", unmeasuredReasons: reasons };
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
const order = compareVersions(input.treeVersion!, input.publishedVersion!);
|
|
393
|
+
if (order === null) {
|
|
394
|
+
return {
|
|
395
|
+
...base,
|
|
396
|
+
reading: "UNMEASURED",
|
|
397
|
+
unmeasuredReasons: [
|
|
398
|
+
`cannot order ${JSON.stringify(input.treeVersion)} against ${JSON.stringify(input.publishedVersion)}`,
|
|
399
|
+
],
|
|
400
|
+
};
|
|
401
|
+
}
|
|
402
|
+
if (order > 0) return { ...base, reading: "AHEAD", unmeasuredReasons: [] };
|
|
403
|
+
if (order < 0) return { ...base, reading: "BEHIND", unmeasuredReasons: [] };
|
|
404
|
+
return {
|
|
405
|
+
...base,
|
|
406
|
+
reading: contentAgrees(input.difference!) ? "MATCHED" : "DIVERGED",
|
|
407
|
+
unmeasuredReasons: [],
|
|
408
|
+
};
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
/**
|
|
412
|
+
* The single refusal. One binding, so there is one thing to mutate.
|
|
413
|
+
*
|
|
414
|
+
* A projection of `reading` and nothing else — a second predicate over the
|
|
415
|
+
* same facts would always agree with this one and would survive any mutation
|
|
416
|
+
* of it.
|
|
417
|
+
*/
|
|
418
|
+
export function artifactViolations(s: ArtifactStanding): string[] {
|
|
419
|
+
if (s.reading === "UNMEASURED") {
|
|
420
|
+
return [
|
|
421
|
+
`UNMEASURED: the published artifact was not compared against this tree — ` +
|
|
422
|
+
s.unmeasuredReasons.join("; ") +
|
|
423
|
+
`. A comparison that could not be taken is not one that passed.`,
|
|
424
|
+
];
|
|
425
|
+
}
|
|
426
|
+
if (s.reading === "DIVERGED") {
|
|
427
|
+
const d = s.difference!;
|
|
428
|
+
return [
|
|
429
|
+
`rungate@${s.publishedVersion} on the registry and the ${s.treeVersion} tree are ` +
|
|
430
|
+
`DIFFERENT SOFTWARE under the SAME version string: ${d.differing.length} of the published ` +
|
|
431
|
+
`artifact's ${d.publishedCount} files differ in content, ${d.onlyLocal.length} files the ` +
|
|
432
|
+
`tree would publish are absent from it, and ${d.onlyPublished.length} of its files are gone ` +
|
|
433
|
+
`from the tree` +
|
|
434
|
+
(s.commitsAhead === null ? "" : ` (${s.commitsAhead} commits since the published tag)`) +
|
|
435
|
+
`. Bump package.json so the two names stop claiming to be one thing, or cut the release.`,
|
|
436
|
+
];
|
|
437
|
+
}
|
|
438
|
+
return [];
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
/**
|
|
442
|
+
* Commits between `v<version>` and `HEAD`. `null` is a reading nobody took.
|
|
443
|
+
*
|
|
444
|
+
* Never gated on: a shallow CI checkout has no tags, so a refusal here would
|
|
445
|
+
* fire on the ordinary case. It is reported so staleness is a number someone
|
|
446
|
+
* can read, which is the half of #875 that is informational rather than a gate.
|
|
447
|
+
*/
|
|
448
|
+
export function publishedTagDistance(
|
|
449
|
+
root: string,
|
|
450
|
+
version: string,
|
|
451
|
+
run: RunCommand,
|
|
452
|
+
): { commits: number | null; note: string | null } {
|
|
453
|
+
const tag = `v${version}`;
|
|
454
|
+
const probe = run(["git", "rev-parse", "--verify", `${tag}^{commit}`], root);
|
|
455
|
+
if (probe.status !== 0) {
|
|
456
|
+
return { commits: null, note: `tag ${tag} is not in this checkout (a shallow clone has none)` };
|
|
457
|
+
}
|
|
458
|
+
const r = run(["git", "rev-list", "--count", `${tag}..HEAD`], root);
|
|
459
|
+
if (r.status !== 0) return { commits: null, note: `git rev-list failed: ${r.stderr.trim()}` };
|
|
460
|
+
const n = Number(r.stdout.trim());
|
|
461
|
+
return Number.isInteger(n) ? { commits: n, note: null } : { commits: null, note: `unreadable count ${r.stdout.trim()}` };
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/**
|
|
465
|
+
* Take every reading and produce one standing. Any throw becomes `UNMEASURED`.
|
|
466
|
+
*
|
|
467
|
+
* The catch is what makes an unreachable registry reportable instead of a
|
|
468
|
+
* crash — and `artifactViolations` refuses `UNMEASURED`, so it is not a
|
|
469
|
+
* fail-open. The distinction matters: this converts an exception into a
|
|
470
|
+
* REFUSAL, not into a pass.
|
|
471
|
+
*/
|
|
472
|
+
export async function measureArtifactStanding(opts: {
|
|
473
|
+
pkg: string;
|
|
474
|
+
root: string;
|
|
475
|
+
run: RunCommand;
|
|
476
|
+
latestVersion: (pkg: string) => Promise<string>;
|
|
477
|
+
fetchImpl?: typeof fetch;
|
|
478
|
+
base?: string;
|
|
479
|
+
}): Promise<ArtifactStanding> {
|
|
480
|
+
let treeVersion: string | null = null;
|
|
481
|
+
let publishedVersion: string | null = null;
|
|
482
|
+
let difference: ContentDifference | null = null;
|
|
483
|
+
const reasons: string[] = [];
|
|
484
|
+
|
|
485
|
+
let local: ArtifactFile[] = [];
|
|
486
|
+
try {
|
|
487
|
+
const pack = localArtifact(opts.root, opts.run);
|
|
488
|
+
treeVersion = pack.version;
|
|
489
|
+
local = pack.files;
|
|
490
|
+
} catch (e) {
|
|
491
|
+
reasons.push((e as Error).message);
|
|
492
|
+
}
|
|
493
|
+
|
|
494
|
+
try {
|
|
495
|
+
publishedVersion = await opts.latestVersion(opts.pkg);
|
|
496
|
+
} catch (e) {
|
|
497
|
+
reasons.push(`registry: ${(e as Error).message}`);
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
if (publishedVersion !== null && local.length > 0) {
|
|
501
|
+
try {
|
|
502
|
+
const remote = await publishedArtifact(opts.pkg, publishedVersion, {
|
|
503
|
+
fetchImpl: opts.fetchImpl,
|
|
504
|
+
base: opts.base,
|
|
505
|
+
});
|
|
506
|
+
difference = contentDifference(local, remote);
|
|
507
|
+
} catch (e) {
|
|
508
|
+
reasons.push((e as Error).message);
|
|
509
|
+
}
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
const distance =
|
|
513
|
+
publishedVersion === null
|
|
514
|
+
? { commits: null, note: "no published version to measure from" }
|
|
515
|
+
: publishedTagDistance(opts.root, publishedVersion, opts.run);
|
|
516
|
+
|
|
517
|
+
return artifactStanding({
|
|
518
|
+
treeVersion,
|
|
519
|
+
publishedVersion,
|
|
520
|
+
difference,
|
|
521
|
+
commitsAhead: distance.commits,
|
|
522
|
+
distanceNote: distance.note,
|
|
523
|
+
unmeasuredReasons: reasons,
|
|
524
|
+
});
|
|
525
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `readdirSync`, sorted (#827).
|
|
3
|
+
*
|
|
4
|
+
* A LEAF module, in the shape `lib/local-calendar-day.ts` established: one
|
|
5
|
+
* exported binding, no relative imports, so there is exactly one thing to
|
|
6
|
+
* mutate and every call site names the same rule.
|
|
7
|
+
*
|
|
8
|
+
* ## Why this exists
|
|
9
|
+
*
|
|
10
|
+
* Directory enumeration order is the filesystem's, and it is not an order:
|
|
11
|
+
* APFS hands entries back in a different sequence from ext4. The scan
|
|
12
|
+
* renders tables straight from these reads, so three generated files —
|
|
13
|
+
* `.claude/rules/specs-routing.md` and the prompt-routing tables in
|
|
14
|
+
* `.claude/agents/discovery.md` and `marcus.md` — came out as a different
|
|
15
|
+
* PERMUTATION on Linux and on macOS, with byte-identical rows.
|
|
16
|
+
*
|
|
17
|
+
* The consequence is sharper than a cosmetic diff: the repository could be a
|
|
18
|
+
* fixed point of its own generator on the machine its files were last
|
|
19
|
+
* written on and on no other. #827 was measured on a Mac and reported five
|
|
20
|
+
* drifting files; CI found three more that no amount of looking on the
|
|
21
|
+
* author's machine would have shown.
|
|
22
|
+
*
|
|
23
|
+
* ## Why one module rather than a `.sort()` per call site
|
|
24
|
+
*
|
|
25
|
+
* The scan exists TWICE — `lib/scanner.ts` and `lib/scaffold/steps.ts` carry
|
|
26
|
+
* parallel copies, which is the duplication #829 removed for the spec scan
|
|
27
|
+
* and which is still there for the rest. Twenty-four `.sort()` calls are
|
|
28
|
+
* twenty-four things to forget; one binding is one.
|
|
29
|
+
* `test/harness-fixed-point.test.ts` asserts that neither file calls
|
|
30
|
+
* `readdirSync` at all, so a new call site cannot reintroduce the class by
|
|
31
|
+
* reaching for the raw import.
|
|
32
|
+
*
|
|
33
|
+
* Plain `.sort()`: the default lexicographic order over UTF-16 code units is
|
|
34
|
+
* locale-independent, unlike `localeCompare`, and a generator whose output
|
|
35
|
+
* depends on the runner's locale is the same defect in a different coat.
|
|
36
|
+
*/
|
|
37
|
+
import { readdirSync } from "fs";
|
|
38
|
+
|
|
39
|
+
export interface ReaddirSortedOptions {
|
|
40
|
+
recursive?: boolean;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function readdirSorted(dir: string, opts?: ReaddirSortedOptions): string[] {
|
|
44
|
+
return (opts ? readdirSync(dir, opts) : readdirSync(dir)).map(String).sort();
|
|
45
|
+
}
|