rungate 0.3.0 → 0.4.1
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/ac-quality.ts +119 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/ci-checkout.ts +27 -1
- package/lib/compliance-backfill.ts +16 -4
- package/lib/compliance-report.ts +109 -8
- package/lib/config-loader.ts +129 -5
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +520 -27
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +55 -33
- package/lib/decomposition-waves.ts +197 -0
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/generators/agents-md.ts +10 -5
- package/lib/issue-extraction.ts +368 -0
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +111 -0
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/prior-branch.ts +24 -1
- package/lib/project-aliases.ts +100 -0
- package/lib/prove-label-gate.ts +93 -0
- package/lib/release-preflight.ts +225 -15
- package/lib/rungate-schema.ts +36 -2
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/rehearsal.ts +330 -0
- package/lib/scaffold/steps.ts +175 -122
- package/lib/scaffold/write-steps.ts +167 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/task-completion-checks.ts +50 -3
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +23 -34
- package/lib/verified-push.ts +179 -2
- package/lib/workflow-security.ts +51 -7
- package/lib/worktree-cleanup.ts +318 -20
- package/lib/worktree-repo.ts +465 -0
- package/package.json +8 -2
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +26 -136
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
package/lib/release-preflight.ts
CHANGED
|
@@ -151,7 +151,11 @@ export function preflightRefusal(
|
|
|
151
151
|
`${treeVersion}, so the tag would describe a release that is not the one cut`
|
|
152
152
|
);
|
|
153
153
|
}
|
|
154
|
-
|
|
154
|
+
// `registryServes`, not a second `versions.includes` here (#445). Two
|
|
155
|
+
// deciders answering the same question about the same input are
|
|
156
|
+
// behaviourally one guard, and no behavioural test can tell them apart —
|
|
157
|
+
// the fourth shape in .claude/rules/checks-must-be-able-to-fail.md.
|
|
158
|
+
if (registryServes(state, treeVersion)) {
|
|
155
159
|
return (
|
|
156
160
|
`rungate@${treeVersion} is already on the registry — publishing it again is ` +
|
|
157
161
|
`rejected by npm, and a job that treats that rejection as success reports a ` +
|
|
@@ -162,25 +166,231 @@ export function preflightRefusal(
|
|
|
162
166
|
}
|
|
163
167
|
|
|
164
168
|
/**
|
|
165
|
-
* The
|
|
166
|
-
*
|
|
169
|
+
* The ONE question the postflight answers: is the version on the registry?
|
|
170
|
+
*
|
|
171
|
+
* The `versions` list, not `dist-tags.latest` (#445). They are different
|
|
172
|
+
* facts and #364 conflated them. A version that appears in `versions` has
|
|
173
|
+
* been published — `npm install rungate@0.4.0` resolves — whatever `latest`
|
|
174
|
+
* currently points at, because a dist-tag is a pointer that moves on its own
|
|
175
|
+
* schedule and can be aimed anywhere. Reading `latest` to answer "did the
|
|
176
|
+
* publish take effect" is reading a pointer to answer a question about the
|
|
177
|
+
* thing pointed at.
|
|
178
|
+
*
|
|
179
|
+
* Exported as its own binding so there is exactly one place to mutate.
|
|
180
|
+
* `preflightRefusal` asks the same predicate in the opposite direction — the
|
|
181
|
+
* version must NOT be here before, and MUST be here after — which is the
|
|
182
|
+
* whole of the two-readings design in one field.
|
|
183
|
+
*/
|
|
184
|
+
export function registryServes(state: RegistryState, version: string): boolean {
|
|
185
|
+
return state.versions.includes(version);
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* What the postflight established, and what it could not (#445).
|
|
190
|
+
*
|
|
191
|
+
* Three states, not two, because `v0.3.0` and `v0.4.0` both published
|
|
192
|
+
* successfully and both were recorded as failures. The old shape had only
|
|
193
|
+
* `refusal | null`, so a stale read had nowhere to go but into a refusal, and
|
|
194
|
+
* the refusal it got said *the publish step did not take effect* — a cause
|
|
195
|
+
* the guard had not established and could not establish from where it stood.
|
|
196
|
+
*/
|
|
197
|
+
export interface PostflightVerdict {
|
|
198
|
+
/** `true` only when the registry serves the version being cut. */
|
|
199
|
+
published: boolean;
|
|
200
|
+
/**
|
|
201
|
+
* Set when the release is published but `latest` still points elsewhere.
|
|
202
|
+
* Reported, never decided on: a lagging dist-tag is propagation, and the
|
|
203
|
+
* guard calling it a failed publish is the whole of #445.
|
|
204
|
+
*/
|
|
205
|
+
note: string | null;
|
|
206
|
+
/**
|
|
207
|
+
* Set when the version is absent from the packument. Deliberately NOT a
|
|
208
|
+
* finding — both explanations are named and neither is chosen. See
|
|
209
|
+
* `.claude/rules/config-access.md`: a reading that could not be obtained is
|
|
210
|
+
* UNMEASURED, and `0`, `{}`, `null` and `SKIP` are indistinguishable from
|
|
211
|
+
* success while UNMEASURED is not.
|
|
212
|
+
*/
|
|
213
|
+
unmeasured: string | null;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** The command a human runs to settle what this guard cannot. */
|
|
217
|
+
export function confirmCommand(pkg: string, version: string): string {
|
|
218
|
+
return `npm view ${pkg}@${version} version`;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* The single place that decides whether a release actually happened.
|
|
167
223
|
*
|
|
168
224
|
* Run AFTER the publish step, against a freshly read registry. This is the
|
|
169
225
|
* half that cannot be satisfied by doing nothing: a skipped, swallowed or
|
|
170
|
-
* silently-failed publish leaves
|
|
226
|
+
* silently-failed publish leaves the registry without the version.
|
|
227
|
+
*
|
|
228
|
+
* What it will not do is say WHY the version is missing. From one stale read
|
|
229
|
+
* "the publish did not take effect" and "the packument has not propagated"
|
|
230
|
+
* are the same observation, and #407 answered that by waiting longer, which
|
|
231
|
+
* is a bigger guess rather than a different mechanism. This answers it by
|
|
232
|
+
* declining to guess and naming the command that settles it.
|
|
171
233
|
*/
|
|
172
|
-
export function
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
234
|
+
export function postflightVerdict(
|
|
235
|
+
pkg: string,
|
|
236
|
+
treeVersion: string,
|
|
237
|
+
state: RegistryState,
|
|
238
|
+
read: { attempts: number; waitedMs: number },
|
|
239
|
+
): PostflightVerdict {
|
|
240
|
+
const seconds = Math.round(read.waitedMs / 1000);
|
|
241
|
+
const reads = `${read.attempts} read${read.attempts === 1 ? "" : "s"} over ${seconds}s`;
|
|
242
|
+
|
|
243
|
+
if (registryServes(state, treeVersion)) {
|
|
244
|
+
return {
|
|
245
|
+
published: true,
|
|
246
|
+
note:
|
|
247
|
+
state.latest === treeVersion
|
|
248
|
+
? null
|
|
249
|
+
: `the registry serves ${pkg}@${treeVersion} while dist-tags.latest is ` +
|
|
250
|
+
`${state.latest ?? "unset"} — the publish landed and the tag has not ` +
|
|
251
|
+
`caught up. That is propagation and it is not a failed publish`,
|
|
252
|
+
unmeasured: null,
|
|
253
|
+
};
|
|
178
254
|
}
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
255
|
+
|
|
256
|
+
return {
|
|
257
|
+
published: false,
|
|
258
|
+
note: null,
|
|
259
|
+
unmeasured:
|
|
260
|
+
`UNMEASURED: ${pkg}@${treeVersion} is absent from the registry's packument ` +
|
|
261
|
+
`after ${reads} (dist-tags.latest is ${state.latest ?? "unset"}). Two ` +
|
|
262
|
+
`explanations fit this reading and nothing available here tells them apart: ` +
|
|
263
|
+
`the publish did not take effect, or the packument has not propagated. ` +
|
|
264
|
+
`The publish may well have succeeded. Settle it with ` +
|
|
265
|
+
`\`${confirmCommand(pkg, treeVersion)}\` — if that prints ${treeVersion} the ` +
|
|
266
|
+
`release landed and only this job's result is wrong; if it fails, the publish ` +
|
|
267
|
+
`did not happen and the release must be cut again.`,
|
|
268
|
+
};
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/** What a postflight poll saw, and how hard it had to look (#407, #445). */
|
|
272
|
+
export interface PostflightReading {
|
|
273
|
+
/** The `latest` dist-tag on the final read. */
|
|
274
|
+
latest: string | null;
|
|
275
|
+
/** Reads performed. 1 means the registry had it immediately. */
|
|
276
|
+
attempts: number;
|
|
277
|
+
/** Time spent sleeping between reads, in ms. */
|
|
278
|
+
waitedMs: number;
|
|
279
|
+
/** What the final read established. */
|
|
280
|
+
verdict: PostflightVerdict;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* The whole poll window, as ONE exported constant (#445 SC-4).
|
|
285
|
+
*
|
|
286
|
+
* #407 shipped the window as two numbers — ten attempts, three seconds apart
|
|
287
|
+
* — so widening it meant reasoning about their product, and the next person
|
|
288
|
+
* to widen it would raise whichever one they noticed. One constant, one edit,
|
|
289
|
+
* and `POSTFLIGHT_DELAY_MS` below cannot change the window no matter what it
|
|
290
|
+
* is set to. The positive control in `test/release-guard.test.ts` proves the
|
|
291
|
+
* guard still refuses an absent version, so widening this cannot quietly turn
|
|
292
|
+
* the check off.
|
|
293
|
+
*/
|
|
294
|
+
export const POSTFLIGHT_BUDGET_MS = 120_000;
|
|
295
|
+
|
|
296
|
+
/** How often to re-read inside the budget. A cadence, not a budget knob. */
|
|
297
|
+
export const POSTFLIGHT_DELAY_MS = 5_000;
|
|
298
|
+
|
|
299
|
+
/** Reads the budget buys at a given cadence. The first read costs no wait. */
|
|
300
|
+
export function postflightAttempts(budgetMs: number, delayMs: number): number {
|
|
301
|
+
return Math.floor(budgetMs / delayMs) + 1;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Poll the registry until it serves `treeVersion`, or give up and refuse (#407).
|
|
306
|
+
*
|
|
307
|
+
* `v0.3.0` published cleanly and the release job still went red: the
|
|
308
|
+
* postflight read `registry.npmjs.org/rungate` about a second after `npm
|
|
309
|
+
* publish` returned, and that document is CDN-fronted and eventually
|
|
310
|
+
* consistent, so it was still serving `0.2.1`. The publish was fine. The check
|
|
311
|
+
* was wrong.
|
|
312
|
+
*
|
|
313
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about checks that cannot
|
|
314
|
+
* fail. This is the inverse and it costs the same thing, because the message
|
|
315
|
+
* is wrong either way — and a red job over a green release is how a gate
|
|
316
|
+
* teaches people to stop reading it.
|
|
317
|
+
*
|
|
318
|
+
* ## The bound is the point
|
|
319
|
+
*
|
|
320
|
+
* Retrying until it goes green would turn this into the defect in the other
|
|
321
|
+
* direction. The loop is bounded, a version that never appears is never
|
|
322
|
+
* reported as published, and the reading says how many times it looked and
|
|
323
|
+
* for how long — so a reader can tell a bounded search from an impatient one
|
|
324
|
+
* without the guard having to interpret the number for them.
|
|
325
|
+
*
|
|
326
|
+
* ## What it stopped claiming (#445)
|
|
327
|
+
*
|
|
328
|
+
* Exhausting the budget used to produce a refusal naming a cause. It now
|
|
329
|
+
* produces `verdict.unmeasured`, which names both causes and neither. See
|
|
330
|
+
* `postflightVerdict`.
|
|
331
|
+
*
|
|
332
|
+
* ## Why an intermediate throw retries and the last one does not
|
|
333
|
+
*
|
|
334
|
+
* A transient network error is exactly what polling is for, so a read that
|
|
335
|
+
* throws with attempts remaining is retried. The FINAL one rethrows, because
|
|
336
|
+
* `registryState` throws rather than returning an empty state precisely so
|
|
337
|
+
* that "could not measure" cannot read as "nothing wrong" — and swallowing
|
|
338
|
+
* the last throw here would put that fail-open back.
|
|
339
|
+
*
|
|
340
|
+
* `sleep` is injectable so the exhaustion case can be driven in a test without
|
|
341
|
+
* spending 30 seconds of wall clock on it.
|
|
342
|
+
*/
|
|
343
|
+
export async function awaitRegistryServes(
|
|
344
|
+
pkg: string,
|
|
345
|
+
treeVersion: string,
|
|
346
|
+
opts: {
|
|
347
|
+
fetchImpl?: typeof fetch;
|
|
348
|
+
base?: string;
|
|
349
|
+
budgetMs?: number;
|
|
350
|
+
delayMs?: number;
|
|
351
|
+
sleep?: (ms: number) => Promise<void>;
|
|
352
|
+
} = {},
|
|
353
|
+
): Promise<PostflightReading> {
|
|
354
|
+
const budgetMs = opts.budgetMs ?? POSTFLIGHT_BUDGET_MS;
|
|
355
|
+
const delayMs = opts.delayMs ?? POSTFLIGHT_DELAY_MS;
|
|
356
|
+
// An unbounded budget is the defect in the other direction — a poll that
|
|
357
|
+
// retries until it goes green cannot fail — and a zero delay divides the
|
|
358
|
+
// budget by nothing and never terminates.
|
|
359
|
+
if (!Number.isFinite(budgetMs) || budgetMs < 0 || !Number.isFinite(delayMs) || delayMs <= 0) {
|
|
360
|
+
throw new Error(
|
|
361
|
+
`postflight needs a finite non-negative budget and a positive delay, got ` +
|
|
362
|
+
`${opts.budgetMs} / ${opts.delayMs}`,
|
|
183
363
|
);
|
|
184
364
|
}
|
|
185
|
-
|
|
365
|
+
const attempts = postflightAttempts(budgetMs, delayMs);
|
|
366
|
+
const sleep = opts.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
|
|
367
|
+
|
|
368
|
+
let waitedMs = 0;
|
|
369
|
+
|
|
370
|
+
for (let attempt = 1; attempt <= attempts; attempt++) {
|
|
371
|
+
const last = attempt === attempts;
|
|
372
|
+
let state: RegistryState;
|
|
373
|
+
try {
|
|
374
|
+
state = await registryState(pkg, opts.fetchImpl ?? fetch, opts.base);
|
|
375
|
+
} catch (e) {
|
|
376
|
+
// A transient error is exactly what polling is for. The FINAL one
|
|
377
|
+
// rethrows, because `registryState` throws rather than returning an
|
|
378
|
+
// empty state precisely so that "could not measure" cannot read as
|
|
379
|
+
// "nothing wrong", and swallowing it here would put that back.
|
|
380
|
+
if (last) throw e;
|
|
381
|
+
await sleep(delayMs);
|
|
382
|
+
waitedMs += delayMs;
|
|
383
|
+
continue;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
const verdict = postflightVerdict(pkg, treeVersion, state, { attempts: attempt, waitedMs });
|
|
387
|
+
if (verdict.published || last) {
|
|
388
|
+
return { latest: state.latest, attempts: attempt, waitedMs, verdict };
|
|
389
|
+
}
|
|
390
|
+
await sleep(delayMs);
|
|
391
|
+
waitedMs += delayMs;
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/* c8 ignore next */
|
|
395
|
+
throw new Error("unreachable: the loop returns on its last attempt");
|
|
186
396
|
}
|
package/lib/rungate-schema.ts
CHANGED
|
@@ -6,7 +6,19 @@ export const DevSchema = z.object({
|
|
|
6
6
|
uiBase: z.string().url(),
|
|
7
7
|
preStart: z.string().optional(),
|
|
8
8
|
testCmd: z.string().optional(),
|
|
9
|
-
|
|
9
|
+
/**
|
|
10
|
+
* The project's type check, or `null` when it has nothing to type-check.
|
|
11
|
+
*
|
|
12
|
+
* **Nullable as well as optional (#87)**, for `healthPath`'s reason below.
|
|
13
|
+
* The scaffold used to write `bunx tsc --noEmit` here unconditionally, and
|
|
14
|
+
* `gates/gate-executor.ts` RUNS what it finds; without a tsconfig that
|
|
15
|
+
* command prints its help text and exits 1, so the verify gate reported
|
|
16
|
+
* `Type check FAIL` at every consumer the rest of the scaffold had already
|
|
17
|
+
* decided was not a TypeScript project. Absent and null are different facts
|
|
18
|
+
* — "nobody configured this" versus "the scaffold looked and there is
|
|
19
|
+
* nothing to run" — and the gate skips on either.
|
|
20
|
+
*/
|
|
21
|
+
typeCheck: z.string().nullable().optional(),
|
|
10
22
|
note: z.string().optional(),
|
|
11
23
|
/**
|
|
12
24
|
* The path the dev-server liveness probe requests, relative to `apiBase`.
|
|
@@ -150,7 +162,29 @@ export const ProjectHarnessSchema = z.object({
|
|
|
150
162
|
forbiddenCommands: z.array(z.string()).optional(),
|
|
151
163
|
consumers: z.array(z.string()).optional(),
|
|
152
164
|
promptKeywords: z.record(z.array(z.string())).optional(),
|
|
153
|
-
|
|
165
|
+
/**
|
|
166
|
+
* Both authored shapes, because both have always been consumed (#439).
|
|
167
|
+
*
|
|
168
|
+
* This was `z.record(...)` — object only — while `gates/brief-assembler.ts`
|
|
169
|
+
* read `Array.isArray(docs) ? docs : Object.values(docs)` and
|
|
170
|
+
* `gates/brief-assembler.test.ts` tested the array form explicitly. The
|
|
171
|
+
* contradiction was invisible because the assembler parsed the file itself
|
|
172
|
+
* with `JSON.parse` and never reached the validator. Routing it through
|
|
173
|
+
* the loader is what made the schema and the consumer meet.
|
|
174
|
+
*
|
|
175
|
+
* The ENTRIES are `unknown` on purpose, which is the only place in this
|
|
176
|
+
* schema that is true. `lib/context-docs.ts` is the single decider for what
|
|
177
|
+
* a declared doc becomes, and it reports per entry — "docs/x.md: not a
|
|
178
|
+
* string" names the offender, where a schema throw would refuse the whole
|
|
179
|
+
* brief and name the key. Validating the entries here as well would be a
|
|
180
|
+
* second decider agreeing with the first, and the first would then be
|
|
181
|
+
* unreachable in production: its "not a string" arm could never fire, and
|
|
182
|
+
* no test could tell. See `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
183
|
+
*/
|
|
184
|
+
contextDocs: z.union([
|
|
185
|
+
z.record(z.unknown()),
|
|
186
|
+
z.array(z.unknown()),
|
|
187
|
+
]).optional(),
|
|
154
188
|
mcp: z.array(McpServerSchema).optional(),
|
|
155
189
|
research: z.array(ResearchToolSchema).optional(),
|
|
156
190
|
roles: z.record(RoleSchema).optional(),
|
package/lib/sc-cover.ts
CHANGED
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
import { readdirSync, readFileSync } from "fs";
|
|
45
45
|
import { join } from "path";
|
|
46
46
|
|
|
47
|
-
import { isBehavioralSC, matchPattern } from "./conformity";
|
|
47
|
+
import { collectTestableSpecs, isBehavioralSC, matchPattern, planSCTests } from "./conformity";
|
|
48
48
|
import { buildScRegistry, isTemplateSpec, parseScDeclarations, type ScDeclaration } from "./sc-ids";
|
|
49
49
|
|
|
50
50
|
export interface UncoveredSc {
|
|
@@ -148,3 +148,94 @@ export function ratchetViolations(
|
|
|
148
148
|
}
|
|
149
149
|
return out.sort();
|
|
150
150
|
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* The two halves of "checked, and the engine can build no assertion" (#441).
|
|
154
|
+
*
|
|
155
|
+
* `UNMATCHED_CHECKED_RATCHET` was one number counting both, and its docblock
|
|
156
|
+
* read it as debt: SCs marked done that carry no assertion and are therefore
|
|
157
|
+
* wishes. That reading was right at 54. It stopped being right once the repo
|
|
158
|
+
* started writing criteria about REFUSALS, because the registry's whole
|
|
159
|
+
* vocabulary — file-exists, content-contains, count-threshold — is claims
|
|
160
|
+
* about the state of the tree, and there is no state of a tree that expresses
|
|
161
|
+
* "X refuses, and says which of two things happened".
|
|
162
|
+
*
|
|
163
|
+
* So the number rose on #397, #398 and #399 for criteria that are all covered
|
|
164
|
+
* by executed tests, and the only way to lower it would have been to rewrite
|
|
165
|
+
* them as weaker claims about file contents. A ratchet that rises whenever an
|
|
166
|
+
* issue writes a good behavioural criterion is measuring the matcher's
|
|
167
|
+
* vocabulary, not the project's honesty.
|
|
168
|
+
*
|
|
169
|
+
* - `unclaimed` — no test file declares it. The wish the old docblock meant.
|
|
170
|
+
* - `claimed` — a test file declares it per
|
|
171
|
+
* `.claude/rules/claiming-sc-coverage.md`, and the engine still cannot
|
|
172
|
+
* build the assertion. A measure of the vocabulary.
|
|
173
|
+
*
|
|
174
|
+
* `SUPERSEDED` ticks are excluded from BOTH, matching `uncoveredTickedScs`.
|
|
175
|
+
* A tick that points at its replacement is not a criterion anybody owes a
|
|
176
|
+
* test for, and leaving it in would have put one criterion in `unclaimed`
|
|
177
|
+
* that the census next door deliberately drops — a disagreement between two
|
|
178
|
+
* numbers about the same tree, arrived at by accident.
|
|
179
|
+
*/
|
|
180
|
+
export interface UnmatchedSplit {
|
|
181
|
+
unclaimed: UncoveredSc[];
|
|
182
|
+
claimed: UncoveredSc[];
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export function splitUnmatchedChecked(opts: {
|
|
186
|
+
projectRoot: string;
|
|
187
|
+
claimed: Set<string>;
|
|
188
|
+
scopedKey: (specFile: string, id: string) => string;
|
|
189
|
+
}): UnmatchedSplit {
|
|
190
|
+
const { projectRoot, claimed, scopedKey } = opts;
|
|
191
|
+
const out: UnmatchedSplit = { unclaimed: [], claimed: [] };
|
|
192
|
+
|
|
193
|
+
for (const [specFile, meta] of collectTestableSpecs(projectRoot)) {
|
|
194
|
+
for (const entry of planSCTests(meta.scs)) {
|
|
195
|
+
if (entry.kind !== "unmatched") continue;
|
|
196
|
+
if (isSuperseded(entry.sc.statement)) continue;
|
|
197
|
+
const row = { id: entry.sc.id, specFile, statement: entry.sc.statement };
|
|
198
|
+
if (claimed.has(scopedKey(specFile, entry.sc.id))) out.claimed.push(row);
|
|
199
|
+
else out.unclaimed.push(row);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
return out;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* Where the unclaimed half disagrees with the uncovered census next door.
|
|
207
|
+
*
|
|
208
|
+
* Measured before this existed: of 155 unclaimed criteria, **154** were
|
|
209
|
+
* already in `uncoveredTickedScs`'s census, which
|
|
210
|
+
* `test/ticked-sc-cover.test.ts` ratchets per spec, both directions, naming
|
|
211
|
+
* the ids. Banking the unclaimed count as a SECOND global number would have
|
|
212
|
+
* been two deciders answering one question — the fourth shape in
|
|
213
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
|
|
214
|
+
* would have left the other holding every case up.
|
|
215
|
+
*
|
|
216
|
+
* So this returns the DIFFERENCE rather than a count, and the test asserts
|
|
217
|
+
* the difference is exactly what is explained below. The per-spec ratchet
|
|
218
|
+
* stays the one place a new untested criterion is refused; this is the
|
|
219
|
+
* relationship between the two populations, checked rather than assumed.
|
|
220
|
+
*
|
|
221
|
+
* The two known residues, both of them the other function behaving correctly
|
|
222
|
+
* and this one being narrower:
|
|
223
|
+
*
|
|
224
|
+
* - `collectTestableSpecs` skips a spec whose frontmatter says
|
|
225
|
+
* `testable: no`, and `readSpecs` does not. `DA-COMPLIANCE-SPEC.md` is one.
|
|
226
|
+
* - `uncoveredTickedScs` also counts a criterion whose matcher MATCHES and
|
|
227
|
+
* then FAILS, which is not `unmatched` and so is invisible here.
|
|
228
|
+
*/
|
|
229
|
+
export function unclaimedCensusResidue(opts: {
|
|
230
|
+
unclaimed: UncoveredSc[];
|
|
231
|
+
census: UncoveredSc[];
|
|
232
|
+
scopedKey: (specFile: string, id: string) => string;
|
|
233
|
+
}): { onlyUnclaimed: string[]; onlyCensus: string[] } {
|
|
234
|
+
const { scopedKey } = opts;
|
|
235
|
+
const a = new Set(opts.unclaimed.map(u => scopedKey(u.specFile, u.id)));
|
|
236
|
+
const b = new Set(opts.census.map(u => scopedKey(u.specFile, u.id)));
|
|
237
|
+
return {
|
|
238
|
+
onlyUnclaimed: [...a].filter(k => !b.has(k)).sort(),
|
|
239
|
+
onlyCensus: [...b].filter(k => !a.has(k)).sort(),
|
|
240
|
+
};
|
|
241
|
+
}
|
package/lib/sc-ids.ts
CHANGED
|
@@ -140,6 +140,46 @@ export function isIssueShaped(id: string): boolean {
|
|
|
140
140
|
return /^SC-\d$/.test(id);
|
|
141
141
|
}
|
|
142
142
|
|
|
143
|
+
/**
|
|
144
|
+
* Ids at or above this number are reserved for test fixtures and will never
|
|
145
|
+
* be allocated to a real criterion (#399).
|
|
146
|
+
*
|
|
147
|
+
* **The namespace has two halves and only one of them was ever guarded.**
|
|
148
|
+
* `nextSCNumber`, `crossSpecCollisions`, `crossFormCollisions` and
|
|
149
|
+
* `requiresQualification` all reason over `specs/` — correctly, and blind to
|
|
150
|
+
* the other half. A test file that writes `- [ ] SC-9441: AGENTS.md exists`
|
|
151
|
+
* inside a string literal has put a checkbox declaration into the live
|
|
152
|
+
* namespace where no guard can see it, so the allocator proposes 900 as free,
|
|
153
|
+
* every collision detector agrees it is free, and the number collides with a
|
|
154
|
+
* literal the suite depends on. That is
|
|
155
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`'s second shape: a detector
|
|
156
|
+
* narrower than what it detects.
|
|
157
|
+
*
|
|
158
|
+
* **It is not hypothetical.** `test/stale-issue-scanner.test.ts` plants
|
|
159
|
+
* `SC-379` and `SC-380` as fixtures, and
|
|
160
|
+
* `specs/CONFIG-DRIVEN-TESTING-SPEC.md:77-78` declares both as real tracked
|
|
161
|
+
* criteria. The collision #399 was filed to prevent had already landed.
|
|
162
|
+
*
|
|
163
|
+
* 9000 rather than 9900, which is what the issue proposed: the convention the
|
|
164
|
+
* tree already follows is 9000+, measured — 209 fixture mentions sit at
|
|
165
|
+
* 9001..9902 across eight files, against 24 strays below. Picking the floor
|
|
166
|
+
* the repo converged on costs no migrations that were not already needed, and
|
|
167
|
+
* `test/sc-claim-forms.test.ts` argued for the convention first.
|
|
168
|
+
*/
|
|
169
|
+
export const FIXTURE_SC_FLOOR = 9000;
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* Is this id reserved for fixtures?
|
|
173
|
+
*
|
|
174
|
+
* ONE exported predicate, consulted by the allocator and by the stray guard,
|
|
175
|
+
* so there is a single binding to mutate rather than a convention each caller
|
|
176
|
+
* reimplements — which is what the four spec-only guards above already are.
|
|
177
|
+
*/
|
|
178
|
+
export function isFixtureScId(id: string): boolean {
|
|
179
|
+
const n = Number(id.replace(/^SC-/, ""));
|
|
180
|
+
return Number.isInteger(n) && n >= FIXTURE_SC_FLOOR;
|
|
181
|
+
}
|
|
182
|
+
|
|
143
183
|
/**
|
|
144
184
|
* The registry: which spec files declare each id.
|
|
145
185
|
*
|
|
@@ -342,3 +382,114 @@ export function isQualifiedBy(source: string, at: number, specFile: string): boo
|
|
|
342
382
|
.toLowerCase();
|
|
343
383
|
return qualifierTokens(specFile).some(t => window.includes(t.toLowerCase()));
|
|
344
384
|
}
|
|
385
|
+
|
|
386
|
+
// ── The other half of the namespace: ids spelled in source ──
|
|
387
|
+
|
|
388
|
+
/** Directories whose sources can spell an SC id. */
|
|
389
|
+
export const SC_SOURCE_DIRS: readonly string[] = ["test", "lib", "scripts", "gates"];
|
|
390
|
+
|
|
391
|
+
/** One mention of an SC id in a source file. */
|
|
392
|
+
export interface ScMentionInSource {
|
|
393
|
+
id: string;
|
|
394
|
+
file: string;
|
|
395
|
+
/** True when the mention sits in a comment rather than in code. */
|
|
396
|
+
inComment: boolean;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/**
|
|
400
|
+
* Every numeric SC id spelled anywhere under `SC_SOURCE_DIRS`.
|
|
401
|
+
*
|
|
402
|
+
* Deliberately NOT restricted to declaring forms. The allocator's question is
|
|
403
|
+
* "could handing out this number break something", and a fixture spelled in
|
|
404
|
+
* any position — a string literal, an array of ids, a `-t` filter — breaks
|
|
405
|
+
* the same way once a spec claims the number. `commentClaimForm` draws the
|
|
406
|
+
* narrower line for CREDIT, and that line is settled and must not move
|
|
407
|
+
* (`.claude/rules/claiming-sc-coverage.md`); this is a different question
|
|
408
|
+
* asked for a different purpose, and widening it here cannot credit anything.
|
|
409
|
+
*/
|
|
410
|
+
export function scMentionsInSource(root: string): ScMentionInSource[] {
|
|
411
|
+
const { readdirSync, readFileSync } = require("fs") as typeof import("fs");
|
|
412
|
+
const { join } = require("path") as typeof import("path");
|
|
413
|
+
const { commentMask } = require("./strip-js-comments") as typeof import("./strip-js-comments");
|
|
414
|
+
const out: ScMentionInSource[] = [];
|
|
415
|
+
|
|
416
|
+
const walk = (dir: string): void => {
|
|
417
|
+
let entries;
|
|
418
|
+
try {
|
|
419
|
+
entries = readdirSync(dir, { withFileTypes: true });
|
|
420
|
+
} catch {
|
|
421
|
+
return; // a source dir this consumer does not have
|
|
422
|
+
}
|
|
423
|
+
for (const e of entries) {
|
|
424
|
+
if (e.name === "node_modules" || e.name === ".git") continue;
|
|
425
|
+
const p = join(dir, e.name);
|
|
426
|
+
if (e.isDirectory()) { walk(p); continue; }
|
|
427
|
+
if (!e.name.endsWith(".ts") && !e.name.endsWith(".js")) continue;
|
|
428
|
+
const src = readFileSync(p, "utf-8");
|
|
429
|
+
if (!src.includes("SC-")) continue;
|
|
430
|
+
const mask = commentMask(src);
|
|
431
|
+
for (const m of src.matchAll(/SC-(\d+)(?!\d)/g)) {
|
|
432
|
+
out.push({ id: m[0], file: p.slice(root.length + 1), inComment: mask[m.index!] === true });
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
};
|
|
436
|
+
for (const d of SC_SOURCE_DIRS) walk(join(root, d));
|
|
437
|
+
return out;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/** Ids spelled in source, with the files that spell them. */
|
|
441
|
+
export function scIdsSpelledInSource(root: string): Map<string, string[]> {
|
|
442
|
+
const found = new Map<string, string[]>();
|
|
443
|
+
for (const m of scMentionsInSource(root)) {
|
|
444
|
+
const files = found.get(m.id) ?? [];
|
|
445
|
+
if (!files.includes(m.file)) files.push(m.file);
|
|
446
|
+
found.set(m.id, files);
|
|
447
|
+
}
|
|
448
|
+
return found;
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/**
|
|
452
|
+
* Fixture ids living in the live namespace: spelled in source, declared by
|
|
453
|
+
* no spec, and below `FIXTURE_SC_FLOOR`.
|
|
454
|
+
*
|
|
455
|
+
* "Declared by no spec" is what makes it a fixture rather than a coverage
|
|
456
|
+
* claim. `// covers SC-640` names a real criterion and must not be moved;
|
|
457
|
+
* `{ id: "SC-9441", done: true }` names nothing and is a number the
|
|
458
|
+
* allocator is free to hand out tomorrow. The difference is in the registry,
|
|
459
|
+
* not in the spelling, which is why this takes one.
|
|
460
|
+
*
|
|
461
|
+
* ## What this deliberately does NOT catch, and why
|
|
462
|
+
*
|
|
463
|
+
* A fixture reusing an id a spec ALREADY declares is invisible here, and
|
|
464
|
+
* that case is real — two instances, both found by hand rather than by any
|
|
465
|
+
* guard:
|
|
466
|
+
*
|
|
467
|
+
* - `test/stale-issue-scanner.test.ts` plants `SC-379`/`SC-380`, both
|
|
468
|
+
* declared in `specs/CONFIG-DRIVEN-TESTING-SPEC.md:77-78`.
|
|
469
|
+
* - `test/sync-sc-status-matching.test.ts` planted `SC-91`/`SC-92`/`SC-93`,
|
|
470
|
+
* all declared in `specs/bootstrap-data-flow/success-criteria.md`, under a
|
|
471
|
+
* comment reading "with IDs this repo does not use so the file does not
|
|
472
|
+
* claim them" — true when written, false by the time it mattered, and
|
|
473
|
+
* nothing could notice.
|
|
474
|
+
*
|
|
475
|
+
* **Catching those by POSITION was tried and is wrong.** "In a comment it is
|
|
476
|
+
* a citation, in code it is a fixture" reports 338 violations on this tree,
|
|
477
|
+
* because `test("SC-1504: …")` is a test TITLE — a claim form
|
|
478
|
+
* `.claude/rules/claiming-sc-coverage.md` lists as valid and settled. And a
|
|
479
|
+
* planted fixture string containing `test("SC-91: …")` is textually
|
|
480
|
+
* identical to a real title, so no position rule separates them. Widening
|
|
481
|
+
* here would have swapped a guard that misses two cases for one that
|
|
482
|
+
* misreports three hundred, which is the worse trade in the direction this
|
|
483
|
+
* repo has already chosen: toward NOT reporting.
|
|
484
|
+
*
|
|
485
|
+
* The residue is filed rather than hidden. See #399's PR.
|
|
486
|
+
*/
|
|
487
|
+
export function strayFixtureIds(root: string, reg: ScRegistry): Map<string, string[]> {
|
|
488
|
+
const stray = new Map<string, string[]>();
|
|
489
|
+
for (const [id, files] of scIdsSpelledInSource(root)) {
|
|
490
|
+
if (reg.declaredById.has(id)) continue;
|
|
491
|
+
if (isFixtureScId(id)) continue;
|
|
492
|
+
stray.set(id, files);
|
|
493
|
+
}
|
|
494
|
+
return stray;
|
|
495
|
+
}
|