rungate 0.4.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/config-loader.ts +129 -5
- package/lib/conformity.ts +157 -1
- package/lib/context-docs.ts +182 -0
- package/lib/create-brief.ts +22 -17
- package/lib/create-sc.ts +35 -8
- package/lib/doc-scan-targets.ts +435 -0
- package/lib/gate-check-audit.ts +9 -9
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +111 -0
- package/lib/project-aliases.ts +100 -0
- package/lib/release-preflight.ts +156 -48
- package/lib/rungate-schema.ts +23 -1
- package/lib/sc-cover.ts +92 -1
- package/lib/sc-ids.ts +151 -0
- package/lib/scaffold/rehearsal.ts +330 -0
- package/lib/scaffold/steps.ts +133 -21
- package/lib/scaffold/write-steps.ts +167 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/validators/spec-validators.ts +23 -34
- package/lib/workflow-security.ts +51 -7
- package/lib/worktree-cleanup.ts +123 -7
- package/lib/worktree-repo.ts +165 -0
- package/package.json +5 -1
- 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/worktree-cleanup.ts
CHANGED
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* GitHub issue #564
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
-
import { readdirSync, realpathSync, statSync, existsSync } from "fs";
|
|
13
|
-
import { join } from "path";
|
|
12
|
+
import { readdirSync, realpathSync, statSync, existsSync, readFileSync, rmSync } from "fs";
|
|
13
|
+
import { join, isAbsolute } from "path";
|
|
14
14
|
import { spawnSync } from "child_process";
|
|
15
15
|
|
|
16
16
|
export interface CleanupResult {
|
|
@@ -25,12 +25,43 @@ export interface CleanupResult {
|
|
|
25
25
|
* the gap between two other numbers is a bucket nobody reconciles.
|
|
26
26
|
*/
|
|
27
27
|
skipped: string[];
|
|
28
|
+
/**
|
|
29
|
+
* Checkouts git has no registration for (#436).
|
|
30
|
+
*
|
|
31
|
+
* A directory whose `.git` file names an admin directory that does not
|
|
32
|
+
* exist. `git worktree remove` cannot touch it — git does not know it is a
|
|
33
|
+
* worktree — so every pass pushed it to `errors` and moved on. That was the
|
|
34
|
+
* conservative behaviour and it was also permanent: an error that recurs on
|
|
35
|
+
* every SessionStart and can never be resolved is indistinguishable from a
|
|
36
|
+
* log line, which is how a 6.2 MB leftover sat in the report for weeks.
|
|
37
|
+
*
|
|
38
|
+
* Its own bucket, so "git could not answer" stays distinct from "there is
|
|
39
|
+
* nothing to ask git about".
|
|
40
|
+
*/
|
|
41
|
+
orphaned: string[];
|
|
28
42
|
errors: string[];
|
|
29
43
|
}
|
|
30
44
|
|
|
31
45
|
export interface CleanupOptions {
|
|
32
46
|
projectRoot: string;
|
|
33
47
|
maxAgeMs?: number;
|
|
48
|
+
/**
|
|
49
|
+
* Delete orphaned checkouts rather than only reporting them (#436 SC-5).
|
|
50
|
+
*
|
|
51
|
+
* **Default off, and that is the decision rather than an oversight.** This
|
|
52
|
+
* function's governing asymmetry, already written into the merge check two
|
|
53
|
+
* hundred lines below, is that treating "not merged" as unsafe costs disk
|
|
54
|
+
* and treating "merged" as safe can delete work. An orphan is the case
|
|
55
|
+
* where the question cannot be asked at all: the admin directory is gone,
|
|
56
|
+
* so `git status` cannot run, and nothing can establish whether the
|
|
57
|
+
* checkout holds work that exists nowhere else.
|
|
58
|
+
*
|
|
59
|
+
* Removing it would therefore be a recursive delete of content this
|
|
60
|
+
* function has explicitly failed to classify, run unprompted at
|
|
61
|
+
* SessionStart. So the automatic pass reports; an operator who has looked
|
|
62
|
+
* passes `removeOrphans: true`. `hooks/StaleTTLCleanup.hook.ts` does not.
|
|
63
|
+
*/
|
|
64
|
+
removeOrphans?: boolean;
|
|
34
65
|
}
|
|
35
66
|
|
|
36
67
|
/**
|
|
@@ -226,6 +257,59 @@ function realPath(p: string): string {
|
|
|
226
257
|
}
|
|
227
258
|
}
|
|
228
259
|
|
|
260
|
+
/**
|
|
261
|
+
* The admin directory a checkout's `.git` file names, when that directory is
|
|
262
|
+
* gone — otherwise `null` (#436).
|
|
263
|
+
*
|
|
264
|
+
* A linked worktree's `.git` is a FILE reading `gitdir: <path>`. When
|
|
265
|
+
* `git worktree prune` removes the registration but leaves the checkout, that
|
|
266
|
+
* path stops existing and every git command run inside the directory fails
|
|
267
|
+
* with "not a git repository". Nothing else produces that state, which is why
|
|
268
|
+
* the test is the gitdir rather than the status failure: a status that fails
|
|
269
|
+
* for any OTHER reason is still an error, because something unexplained
|
|
270
|
+
* happened and this function has no business deleting anything over it.
|
|
271
|
+
*
|
|
272
|
+
* Three things are deliberately NOT orphans:
|
|
273
|
+
*
|
|
274
|
+
* - no `.git` at all — it was never a worktree, and whatever it is, it is
|
|
275
|
+
* not this function's to delete;
|
|
276
|
+
* - a `.git` DIRECTORY — that is a whole repository someone put here, not a
|
|
277
|
+
* linked checkout;
|
|
278
|
+
* - a gitdir that exists — the registration is intact and the ordinary
|
|
279
|
+
* path applies.
|
|
280
|
+
*
|
|
281
|
+
* One exported binding, so there is one thing to mutate.
|
|
282
|
+
*/
|
|
283
|
+
export function orphanedGitdir(worktreePath: string): string | null {
|
|
284
|
+
const dotGit = join(worktreePath, ".git");
|
|
285
|
+
|
|
286
|
+
// ONE decider for "is there a readable `.git` FILE here", and it is this
|
|
287
|
+
// read. The first draft asked the same question twice more — a `statSync`
|
|
288
|
+
// whose catch meant "no .git", and an `isFile()` meaning "a real
|
|
289
|
+
// repository" — and the mutation battery is what showed they were the same
|
|
290
|
+
// question: dropping `isFile()` measured 0 of 47 red, because a directory
|
|
291
|
+
// makes this read throw EISDIR and a missing path makes it throw ENOENT,
|
|
292
|
+
// so the read already returned null for both. Two of the three could be
|
|
293
|
+
// deleted and no test could tell. See
|
|
294
|
+
// `.claude/rules/checks-must-be-able-to-fail.md`, fourth shape.
|
|
295
|
+
//
|
|
296
|
+
// The direction the catch fails in is the safe one: null means "not an
|
|
297
|
+
// orphan", and the only thing downstream does with an orphan is offer to
|
|
298
|
+
// delete it.
|
|
299
|
+
let contents: string;
|
|
300
|
+
try {
|
|
301
|
+
contents = readFileSync(dotGit, "utf-8");
|
|
302
|
+
} catch {
|
|
303
|
+
return null; // absent, a directory, or unreadable — none of them is an orphan
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const m = /^gitdir:\s*(.+?)\s*$/m.exec(contents);
|
|
307
|
+
if (!m) return null; // not the shape git writes; do not guess
|
|
308
|
+
const gitdir = m[1]!;
|
|
309
|
+
const resolved = isAbsolute(gitdir) ? gitdir : join(worktreePath, gitdir);
|
|
310
|
+
return existsSync(resolved) ? null : resolved;
|
|
311
|
+
}
|
|
312
|
+
|
|
229
313
|
/**
|
|
230
314
|
* Clean up stale git worktrees from .claude/worktrees/.
|
|
231
315
|
*
|
|
@@ -238,6 +322,7 @@ export async function cleanupWorktrees(opts: CleanupOptions): Promise<CleanupRes
|
|
|
238
322
|
removed: [],
|
|
239
323
|
kept: [],
|
|
240
324
|
skipped: [],
|
|
325
|
+
orphaned: [],
|
|
241
326
|
errors: [],
|
|
242
327
|
};
|
|
243
328
|
|
|
@@ -306,6 +391,34 @@ export async function cleanupWorktrees(opts: CleanupOptions): Promise<CleanupRes
|
|
|
306
391
|
continue;
|
|
307
392
|
}
|
|
308
393
|
|
|
394
|
+
// #436: git has no registration for this checkout, so every command run
|
|
395
|
+
// inside it fails and `git worktree remove` cannot touch it. Asked BEFORE
|
|
396
|
+
// the status call, because the status call is the thing that fails — and
|
|
397
|
+
// classifying on the failure rather than on the cause would also swallow
|
|
398
|
+
// every other reason git might refuse.
|
|
399
|
+
//
|
|
400
|
+
// The path deleted is the one THIS function built, two lines up, from
|
|
401
|
+
// `join(worktreesDir, entry)`. Not the gitdir read out of the `.git`
|
|
402
|
+
// file, which is attacker-controlled in the sense that matters: it is
|
|
403
|
+
// content, and content must never steer a recursive delete.
|
|
404
|
+
const missingGitdir = orphanedGitdir(worktreePath);
|
|
405
|
+
if (missingGitdir !== null) {
|
|
406
|
+
if (!opts.removeOrphans) {
|
|
407
|
+
result.orphaned.push(
|
|
408
|
+
`${entry} (git has no registration — ${missingGitdir} is gone; ` +
|
|
409
|
+
`nothing can read whether this checkout holds unique work, so it is reported rather than deleted)`,
|
|
410
|
+
);
|
|
411
|
+
continue;
|
|
412
|
+
}
|
|
413
|
+
try {
|
|
414
|
+
rmSync(worktreePath, { recursive: true, force: true });
|
|
415
|
+
result.orphaned.push(`${entry} (removed — git had no registration)`);
|
|
416
|
+
} catch (err) {
|
|
417
|
+
result.errors.push(`Failed to remove orphaned ${entry}: ${err}`);
|
|
418
|
+
}
|
|
419
|
+
continue;
|
|
420
|
+
}
|
|
421
|
+
|
|
309
422
|
// Check for uncommitted changes
|
|
310
423
|
const statusCheck = spawnSync("git", ["status", "--porcelain"], {
|
|
311
424
|
cwd: worktreePath,
|
|
@@ -419,13 +532,16 @@ export async function cleanupWorktrees(opts: CleanupOptions): Promise<CleanupRes
|
|
|
419
532
|
}
|
|
420
533
|
|
|
421
534
|
// Log summary
|
|
422
|
-
// All
|
|
423
|
-
// entries examined, which is the property
|
|
424
|
-
// asserts — a summary that cannot be
|
|
425
|
-
// how 149 worktrees hid behind
|
|
535
|
+
// All FIVE buckets. `removed + kept + skipped + orphaned + errors` is the
|
|
536
|
+
// number of entries examined, which is the property
|
|
537
|
+
// test/worktree-cleanup-orphans asserts — a summary that cannot be
|
|
538
|
+
// reconciled against the directory is how 149 worktrees hid behind
|
|
539
|
+
// "144 kept" (#431). #436 added `orphaned` and this line in the same
|
|
540
|
+
// change, because a bucket missing from the total is that defect again.
|
|
426
541
|
console.log(
|
|
427
542
|
`Worktree cleanup: ${result.removed.length} removed, ${result.kept.length} kept, ` +
|
|
428
|
-
`${result.skipped.length} skipped, ${result.
|
|
543
|
+
`${result.skipped.length} skipped, ${result.orphaned.length} orphaned, ` +
|
|
544
|
+
`${result.errors.length} error(s)`,
|
|
429
545
|
);
|
|
430
546
|
|
|
431
547
|
return result;
|
package/lib/worktree-repo.ts
CHANGED
|
@@ -37,6 +37,7 @@
|
|
|
37
37
|
*/
|
|
38
38
|
|
|
39
39
|
import { spawnSync } from "child_process";
|
|
40
|
+
import { existsSync } from "fs";
|
|
40
41
|
|
|
41
42
|
/** Returned by `readWorktreeRemote`, so a failure carries its own reason. */
|
|
42
43
|
export interface RemoteReading {
|
|
@@ -261,6 +262,170 @@ export function worktreeIdentity(
|
|
|
261
262
|
};
|
|
262
263
|
}
|
|
263
264
|
|
|
265
|
+
/**
|
|
266
|
+
* What a reading of the DISK can say, beyond what a reply can (#414).
|
|
267
|
+
*
|
|
268
|
+
* `worktreeIdentity` above compares a remote an agent REPORTED. Reading the
|
|
269
|
+
* checkout adds two answers a reply cannot produce:
|
|
270
|
+
*
|
|
271
|
+
* missing — the worktree is not there at gate time. A removed worktree and
|
|
272
|
+
* a matching one must not give the same answer; "nothing to read"
|
|
273
|
+
* read as "nothing to report" is the fail-open
|
|
274
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about.
|
|
275
|
+
* forged — the reply named the RIGHT repository and the checkout is a
|
|
276
|
+
* different one. This is the case #218 structurally cannot see,
|
|
277
|
+
* because the only remote it has is the one being contradicted,
|
|
278
|
+
* and it is the whole reason #414 exists.
|
|
279
|
+
*
|
|
280
|
+
* `forged` is not an accusation of intent. An agent answering from its brief
|
|
281
|
+
* rather than from `git remote get-url origin` produces exactly this, and so
|
|
282
|
+
* does a worktree that moved after the reply. Both have the same consequence
|
|
283
|
+
* — the run's identity check passed on a string nothing checked — and a
|
|
284
|
+
* different remedy from an ordinary mismatch, which is why it is its own
|
|
285
|
+
* verdict rather than a flavour of one.
|
|
286
|
+
*/
|
|
287
|
+
export type DiskVerdict = IdentityVerdict | "missing" | "forged";
|
|
288
|
+
|
|
289
|
+
export interface DiskIdentityResult {
|
|
290
|
+
verdict: DiskVerdict;
|
|
291
|
+
/** The slug the CHECKOUT has, when one could be read. */
|
|
292
|
+
actual: string | null;
|
|
293
|
+
/** The slug the run expects. */
|
|
294
|
+
expected: string | null;
|
|
295
|
+
/** The slug the agent REPORTED, when it reported anything parseable. */
|
|
296
|
+
reported: string | null;
|
|
297
|
+
/** Null when the verdict is `match`; otherwise an operator-facing sentence. */
|
|
298
|
+
refusal: string | null;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/**
|
|
302
|
+
* Which repository is this worktree, according to the worktree?
|
|
303
|
+
*
|
|
304
|
+
* `read` is injectable so a test can plant a reading git cannot produce. It
|
|
305
|
+
* defaults to the real reader, and that default is asserted: a gate whose
|
|
306
|
+
* default reader is a stub is the check that never looked.
|
|
307
|
+
*
|
|
308
|
+
* Every refusal names the path and both slugs, and every refusal says
|
|
309
|
+
* `read from the checkout` and `#414`, because the operator's first question
|
|
310
|
+
* is which of the two readings refused. ship.js's refusal comes from the
|
|
311
|
+
* reply; this one comes from the disk; they have different causes and
|
|
312
|
+
* different fixes, and a shared sentence would make them one fact.
|
|
313
|
+
*
|
|
314
|
+
* Paths are redacted on the way into a refusal for the same reason remotes
|
|
315
|
+
* are: a worktree path is attacker-adjacent data (#155) and a CI path can
|
|
316
|
+
* carry a token in it.
|
|
317
|
+
*/
|
|
318
|
+
export function worktreeDiskIdentity(
|
|
319
|
+
worktreePath: string,
|
|
320
|
+
expectedRepo: string | null | undefined,
|
|
321
|
+
reportedRepo: string | null | undefined,
|
|
322
|
+
read: (p: string) => RemoteReading = readWorktreeRemote,
|
|
323
|
+
): DiskIdentityResult {
|
|
324
|
+
const expected = repoSlug(expectedRepo);
|
|
325
|
+
const reported = repoSlug(reportedRepo);
|
|
326
|
+
const path = typeof worktreePath === "string" ? worktreePath.trim() : "";
|
|
327
|
+
const where = redactRemote(path || "(no path reported)");
|
|
328
|
+
|
|
329
|
+
if (!path) {
|
|
330
|
+
return {
|
|
331
|
+
verdict: "unreported",
|
|
332
|
+
actual: null,
|
|
333
|
+
expected,
|
|
334
|
+
reported,
|
|
335
|
+
refusal:
|
|
336
|
+
`a result row named no worktree, so there is nothing to read from the checkout — ` +
|
|
337
|
+
`a row with no path is not a row with nothing to check, it is a row whose origin ` +
|
|
338
|
+
`cannot be established (#414)`,
|
|
339
|
+
};
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
if (!expected) {
|
|
343
|
+
return {
|
|
344
|
+
verdict: "unreported",
|
|
345
|
+
actual: null,
|
|
346
|
+
expected: null,
|
|
347
|
+
reported,
|
|
348
|
+
refusal:
|
|
349
|
+
`${where} could not be checked against the checkout — the run did not state a ` +
|
|
350
|
+
`repository to compare against ` +
|
|
351
|
+
`(repo was ${JSON.stringify(expectedRepo == null ? null : redactRemote(String(expectedRepo)))}), ` +
|
|
352
|
+
`so a worktree in any repository would pass (#414)`,
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
if (!existsSync(path)) {
|
|
357
|
+
// Before the read, not after: `git -C <gone>` fails with a message about
|
|
358
|
+
// the directory, which is indistinguishable from a dozen other failures
|
|
359
|
+
// and would land every removed worktree in `unreadable`.
|
|
360
|
+
return {
|
|
361
|
+
verdict: "missing",
|
|
362
|
+
actual: null,
|
|
363
|
+
expected,
|
|
364
|
+
reported,
|
|
365
|
+
refusal:
|
|
366
|
+
`${where} is named by this run but does not exist at gate time, so its origin ` +
|
|
367
|
+
`could not be read from the checkout. A worktree that is gone is not a worktree ` +
|
|
368
|
+
`that matched — whatever was built there was measured against nothing (#414)`,
|
|
369
|
+
};
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
const reading = read(path);
|
|
373
|
+
if (reading.error || !reading.url) {
|
|
374
|
+
return {
|
|
375
|
+
verdict: "unreadable",
|
|
376
|
+
actual: null,
|
|
377
|
+
expected,
|
|
378
|
+
reported,
|
|
379
|
+
refusal:
|
|
380
|
+
`${where} exists but its origin could not be read from the checkout ` +
|
|
381
|
+
`(${reading.error || "git printed no url"}), so it cannot be compared against ` +
|
|
382
|
+
`${expected}. A reading that failed is not a checkout that matched (#414)`,
|
|
383
|
+
};
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
const actual = repoSlug(reading.url);
|
|
387
|
+
if (!actual) {
|
|
388
|
+
return {
|
|
389
|
+
verdict: "unreadable",
|
|
390
|
+
actual: null,
|
|
391
|
+
expected,
|
|
392
|
+
reported,
|
|
393
|
+
refusal:
|
|
394
|
+
`${where} has an origin this run cannot read as owner/name ` +
|
|
395
|
+
`(${JSON.stringify(redactRemote(reading.url.trim()))}), read from the checkout, ` +
|
|
396
|
+
`so it cannot be compared against ${expected} (#414)`,
|
|
397
|
+
};
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
if (actual === expected) {
|
|
401
|
+
return { verdict: "match", actual, expected, reported, refusal: null };
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
if (reported && reported === expected) {
|
|
405
|
+
return {
|
|
406
|
+
verdict: "forged",
|
|
407
|
+
actual,
|
|
408
|
+
expected,
|
|
409
|
+
reported,
|
|
410
|
+
refusal:
|
|
411
|
+
`${where} reported ${reported}, which is this run's repository, but the checkout ` +
|
|
412
|
+
`read from the checkout is ${actual}. The reply and the disk disagree, so the ` +
|
|
413
|
+
`self-reported check in the ship workflow passed on a string nothing verified — ` +
|
|
414
|
+
`send the agent back rather than moving the worktree (#414, follow-up to #218).`,
|
|
415
|
+
};
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
return {
|
|
419
|
+
verdict: "mismatch",
|
|
420
|
+
actual,
|
|
421
|
+
expected,
|
|
422
|
+
reported,
|
|
423
|
+
refusal:
|
|
424
|
+
`${where} is a worktree of ${actual}, read from the checkout, but this run targets ` +
|
|
425
|
+
`${expected}. Work done there would be written into the wrong repository (#414).`,
|
|
426
|
+
};
|
|
427
|
+
}
|
|
428
|
+
|
|
264
429
|
/** One result row as the workflow reports them: a path and the remote it read. */
|
|
265
430
|
export interface WorktreeReport {
|
|
266
431
|
worktreePath?: string | null;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rungate",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
|
|
6
6
|
"repository": {
|
|
@@ -23,6 +23,10 @@
|
|
|
23
23
|
"scripts/audit-specs.ts",
|
|
24
24
|
"scripts/create-spec.ts",
|
|
25
25
|
"scripts/create-sc.ts",
|
|
26
|
+
"scripts/split-spec.ts",
|
|
27
|
+
"scripts/sync-sc-status.ts",
|
|
28
|
+
"scripts/audit-transcript.ts",
|
|
29
|
+
"scripts/detect-sc-drift.ts",
|
|
26
30
|
"package.json"
|
|
27
31
|
],
|
|
28
32
|
"exports": {
|
package/scripts/audit-specs.ts
CHANGED
|
@@ -45,6 +45,13 @@ export interface RewriteEntry {
|
|
|
45
45
|
after: string;
|
|
46
46
|
patternUsed: string;
|
|
47
47
|
ambiguous: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* Set when the line was DELIBERATELY left alone (#426), carrying why.
|
|
50
|
+
* `before === after` alone cannot say this: it is also what a rewrite that
|
|
51
|
+
* happened to be a no-op looks like, and the caller reports the two
|
|
52
|
+
* differently.
|
|
53
|
+
*/
|
|
54
|
+
kept?: string;
|
|
48
55
|
}
|
|
49
56
|
|
|
50
57
|
export interface AuditResult {
|
|
@@ -258,6 +265,100 @@ function findClosestPattern(
|
|
|
258
265
|
return null;
|
|
259
266
|
}
|
|
260
267
|
|
|
268
|
+
// ── Whether to rewrite at all, and into what (#426) ───────────
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* A file-ish leading token: `workflows/ship.js`, `AGENTS.md`, `specs/X.md`.
|
|
272
|
+
*
|
|
273
|
+
* Anchored, because the question is whether the statement OPENS by naming
|
|
274
|
+
* its target. A filename mentioned halfway through a sentence of prose is
|
|
275
|
+
* not a structured criterion, and treating it as one is how
|
|
276
|
+
* `findClosestPattern`'s last resort turns a whole criterion into
|
|
277
|
+
* `foo.ts exists`.
|
|
278
|
+
*/
|
|
279
|
+
function leadingFileToken(statement: string): string | null {
|
|
280
|
+
const m = /^(\S*[./]\S*)\s/.exec(statement);
|
|
281
|
+
return m ? m[1]! : null;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** The prose after the em dash — the part that says why the criterion exists. */
|
|
285
|
+
function rationaleOf(statement: string): string | null {
|
|
286
|
+
const m = /\s+—\s+(.+)$/.exec(statement);
|
|
287
|
+
return m ? m[1]!.trim() : null;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Is this already written in the structured grammar?
|
|
292
|
+
*
|
|
293
|
+
* A target named up front and a bracketed payload. That is the authored
|
|
294
|
+
* shape of every matcher in `config/matcher-registry.json` that takes one —
|
|
295
|
+
* `contains [...]`, `not contains [...]`, `is under [N] lines`,
|
|
296
|
+
* `has field [x]` — and it is deliberately asked of the SHAPE rather than
|
|
297
|
+
* by running the registry.
|
|
298
|
+
*
|
|
299
|
+
* The distinction matters: SC-1469 is structured and the registry did not
|
|
300
|
+
* recognise it, because `content-not-contains` accepted `must NOT contain`
|
|
301
|
+
* and `has no` but not the `not contains` form the compound matcher's own
|
|
302
|
+
* example uses. Asking the registry would therefore have answered "rewrite
|
|
303
|
+
* it", which is the bug. A matcher gap is a matcher gap; it is not a licence
|
|
304
|
+
* to delete what the author wrote.
|
|
305
|
+
*/
|
|
306
|
+
export function alreadyStructured(statement: string): boolean {
|
|
307
|
+
return leadingFileToken(statement) !== null && /\[[^\]]+\]/.test(statement);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
export type RewriteDecision =
|
|
311
|
+
| { kind: "keep"; reason: string }
|
|
312
|
+
| { kind: "rewrite"; statement: string };
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* What `--fix` may do to one SC line (#426).
|
|
316
|
+
*
|
|
317
|
+
* `scaffold . --fix` is the documented way to take a harness update, and it
|
|
318
|
+
* was rewriting SC-1469 on every run into
|
|
319
|
+
* `not contains [s.environments.prod.rebuild = 'PASS']` — dropping both the
|
|
320
|
+
* file the criterion is about and the whole rationale clause, silently, under
|
|
321
|
+
* a summary line naming `ci.yml`.
|
|
322
|
+
*
|
|
323
|
+
* Three rules, and the third is the one that makes this a fix rather than a
|
|
324
|
+
* patch over one line:
|
|
325
|
+
*
|
|
326
|
+
* 1. A statement already in the structured grammar is never rewritten.
|
|
327
|
+
* 2. A rewrite that would drop the file the criterion names is refused
|
|
328
|
+
* outright. `findClosestPattern`'s last resort collapses anything with a
|
|
329
|
+
* filename in it to `<file> exists`, which is an assertion that holds
|
|
330
|
+
* vacuously against a file that obviously exists.
|
|
331
|
+
* 3. A rewrite that survives both carries the em-dash rationale across.
|
|
332
|
+
*
|
|
333
|
+
* One exported binding, so there is exactly one thing to mutate.
|
|
334
|
+
*/
|
|
335
|
+
export function decideRewrite(
|
|
336
|
+
statement: string,
|
|
337
|
+
closest: { patternName: string; rewrite: string; ambiguous: boolean } | null,
|
|
338
|
+
): RewriteDecision {
|
|
339
|
+
if (alreadyStructured(statement)) {
|
|
340
|
+
return { kind: "keep", reason: "already a structured criterion — a matcher gap is not a licence to rewrite it" };
|
|
341
|
+
}
|
|
342
|
+
if (!closest) {
|
|
343
|
+
return { kind: "keep", reason: "no registry pattern was close enough" };
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
const file = leadingFileToken(statement);
|
|
347
|
+
if (file !== null && !closest.rewrite.includes(file)) {
|
|
348
|
+
return {
|
|
349
|
+
kind: "keep",
|
|
350
|
+
reason: `rewriting as ${closest.patternName} would drop the file ${file} the criterion names`,
|
|
351
|
+
};
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
const rationale = rationaleOf(statement);
|
|
355
|
+
const rewritten = rationale ? `${closest.rewrite} — ${rationale}` : closest.rewrite;
|
|
356
|
+
if (rewritten === statement) {
|
|
357
|
+
return { kind: "keep", reason: "the rewrite is what is already written" };
|
|
358
|
+
}
|
|
359
|
+
return { kind: "rewrite", statement: rewritten };
|
|
360
|
+
}
|
|
361
|
+
|
|
261
362
|
// ── Core audit function ───────────────────────────────────────
|
|
262
363
|
|
|
263
364
|
export function auditSpecs(
|
|
@@ -319,52 +420,48 @@ export function auditSpecs(
|
|
|
319
420
|
|
|
320
421
|
for (const usc of unmatchedSCs) {
|
|
321
422
|
const closest = findClosestPattern(usc.statement);
|
|
322
|
-
|
|
323
|
-
// Can't rewrite — mark with REVIEW comment
|
|
324
|
-
const scLinePattern = new RegExp(
|
|
325
|
-
`^(- \\[ \\] ${usc.id}:\\s*)(.+)$`,
|
|
326
|
-
"m"
|
|
327
|
-
);
|
|
328
|
-
const scMatch = modified.match(scLinePattern);
|
|
329
|
-
if (scMatch) {
|
|
330
|
-
// `closest` is null inside this branch, so the rewrite arm of the
|
|
331
|
-
// old ternary was unreachable. Only the REVIEW marker can apply.
|
|
332
|
-
const replacement = `${scMatch[0]}\n<!-- REVIEW: original — ${usc.statement} -->`;
|
|
333
|
-
modified = modified.replace(scLinePattern, replacement);
|
|
334
|
-
hasChanges = true;
|
|
335
|
-
rewrites.push({
|
|
336
|
-
scId: usc.id,
|
|
337
|
-
specFile,
|
|
338
|
-
before: usc.statement,
|
|
339
|
-
after: usc.statement, // unchanged
|
|
340
|
-
patternUsed: "none",
|
|
341
|
-
ambiguous: true,
|
|
342
|
-
});
|
|
343
|
-
}
|
|
344
|
-
continue;
|
|
345
|
-
}
|
|
423
|
+
const decision = decideRewrite(usc.statement, closest);
|
|
346
424
|
|
|
347
|
-
const scLinePattern = new RegExp(
|
|
348
|
-
`^(- \\[ \\] ${usc.id}:\\s*)(.+)$`,
|
|
349
|
-
"m"
|
|
350
|
-
);
|
|
425
|
+
const scLinePattern = new RegExp(`^(- \\[ \\] ${usc.id}:\\s*)(.+)$`, "m");
|
|
351
426
|
const scMatch = modified.match(scLinePattern);
|
|
352
|
-
if (scMatch)
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
427
|
+
if (!scMatch) continue;
|
|
428
|
+
|
|
429
|
+
// #426: a line we decline to rewrite keeps its text exactly. The
|
|
430
|
+
// REVIEW marker records that the matcher could not bind it — which
|
|
431
|
+
// is a coverage gap worth seeing — without the line itself losing
|
|
432
|
+
// the file it names or the prose that says why it exists.
|
|
433
|
+
if (decision.kind === "keep") {
|
|
434
|
+
const marker = `<!-- REVIEW: unmatched (${decision.reason}) -->`;
|
|
435
|
+
if (!modified.includes(marker)) {
|
|
436
|
+
modified = modified.replace(scLinePattern, `${scMatch[0]}\n${marker}`);
|
|
437
|
+
hasChanges = true;
|
|
356
438
|
}
|
|
357
|
-
modified = modified.replace(scLinePattern, replacement);
|
|
358
|
-
hasChanges = true;
|
|
359
439
|
rewrites.push({
|
|
360
440
|
scId: usc.id,
|
|
361
441
|
specFile,
|
|
362
442
|
before: usc.statement,
|
|
363
|
-
after:
|
|
364
|
-
patternUsed: closest
|
|
365
|
-
ambiguous:
|
|
443
|
+
after: usc.statement, // unchanged, and that is the point
|
|
444
|
+
patternUsed: closest?.patternName ?? "none",
|
|
445
|
+
ambiguous: true,
|
|
446
|
+
kept: decision.reason,
|
|
366
447
|
});
|
|
448
|
+
continue;
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
let replacement = `${scMatch[1]}${decision.statement}`;
|
|
452
|
+
if (closest!.ambiguous) {
|
|
453
|
+
replacement += `\n<!-- REVIEW: original — ${usc.statement} -->`;
|
|
367
454
|
}
|
|
455
|
+
modified = modified.replace(scLinePattern, replacement);
|
|
456
|
+
hasChanges = true;
|
|
457
|
+
rewrites.push({
|
|
458
|
+
scId: usc.id,
|
|
459
|
+
specFile,
|
|
460
|
+
before: usc.statement,
|
|
461
|
+
after: decision.statement,
|
|
462
|
+
patternUsed: closest!.patternName,
|
|
463
|
+
ambiguous: closest!.ambiguous,
|
|
464
|
+
});
|
|
368
465
|
}
|
|
369
466
|
|
|
370
467
|
if (hasChanges) {
|