rungate 0.4.0 → 0.5.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/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- package/lib/ac-quality.ts +119 -0
- package/lib/cli-commands.ts +7 -1
- package/lib/config-loader.ts +129 -5
- package/lib/conformity.ts +1122 -31
- 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/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/organize.ts +129 -40
- package/lib/package-closure.ts +387 -0
- package/lib/project-aliases.ts +100 -0
- package/lib/release-preflight.ts +352 -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/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +6 -0
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +355 -0
- package/lib/scaffold/steps.ts +787 -105
- package/lib/scaffold/write-steps.ts +208 -0
- package/lib/scratch-cleanup.ts +198 -0
- package/lib/scratch-roots.ts +94 -0
- package/lib/source-anchor.ts +144 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +194 -0
- package/lib/test-census.ts +199 -0
- package/lib/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +52 -35
- package/lib/workflow-security.ts +152 -7
- package/lib/workflow-test-harness.ts +349 -0
- package/lib/worktree-cleanup.ts +123 -7
- package/lib/worktree-repo.ts +165 -0
- package/package.json +10 -1
- package/scripts/audit-specs.ts +134 -37
- package/scripts/audit-transcript.ts +259 -0
- package/scripts/create-sc.ts +15 -1
- package/scripts/create-success.ts +162 -0
- package/scripts/detect-sc-drift.ts +200 -0
- package/scripts/extract-constraints.ts +16 -36
- package/scripts/scaffold-project.ts +51 -137
- package/scripts/split-spec.ts +315 -0
- package/scripts/sync-sc-status.ts +751 -0
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
|
@@ -0,0 +1,779 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `SUCCESS.md` — the one file the methodology calls the measure, and the one
|
|
3
|
+
* the scaffold never wrote (#485).
|
|
4
|
+
*
|
|
5
|
+
* `CLAUDE.md` opens its rules with:
|
|
6
|
+
*
|
|
7
|
+
* > **SUCCESS.md is the measure** — it states what we are building and the
|
|
8
|
+
* > falsifiable claims that mean it works. Before filing an issue, reviewing
|
|
9
|
+
* > a PR, or acting on an audit finding, say which claim it moves.
|
|
10
|
+
*
|
|
11
|
+
* No generator, no template, no step produced it. rungate's own was
|
|
12
|
+
* hand-written once in `22aa5b20` and nothing reproduced that for anyone
|
|
13
|
+
* else, while `specs/HARNESS-STANDARD.md` carried SC-822 asserting a
|
|
14
|
+
* property of a file the scaffold never created. A consumer scaffolded a
|
|
15
|
+
* project, read the generated `AGENTS.md`, and never learned the file was
|
|
16
|
+
* supposed to exist.
|
|
17
|
+
*
|
|
18
|
+
* ## Why a validator and not just a generator
|
|
19
|
+
*
|
|
20
|
+
* A generator alone makes it worse. **An unfilled template is
|
|
21
|
+
* indistinguishable from a considered one to everything except a reader** —
|
|
22
|
+
* that is the same argument `.claude/rules/checks-must-be-able-to-fail.md`
|
|
23
|
+
* makes about guards, applied to a document. A project that ran
|
|
24
|
+
* `create-success` and stopped would now have a `SUCCESS.md` that every
|
|
25
|
+
* "does it exist" check waves through, and five TODO claims read as
|
|
26
|
+
* deliberate at a glance.
|
|
27
|
+
*
|
|
28
|
+
* So the template ships placeholders that are obviously placeholders, marked
|
|
29
|
+
* with a token no prose would contain, and `successViolations` refuses while
|
|
30
|
+
* any survive. **The generator must not invent claims**: five plausible
|
|
31
|
+
* generated claims would be worse than none, because they read as considered
|
|
32
|
+
* and are not.
|
|
33
|
+
*
|
|
34
|
+
* ## Absent is UNMEASURED, not FAIL
|
|
35
|
+
*
|
|
36
|
+
* A project that never opted in has not failed at anything, but it has not
|
|
37
|
+
* succeeded either, and `SKIP` is indistinguishable from success — see
|
|
38
|
+
* `.claude/rules/config-access.md`. So an absent file produces a loud
|
|
39
|
+
* UNMEASURED and a present-but-unfilled one produces a refusal.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
import { existsSync, lstatSync, readFileSync } from "fs";
|
|
43
|
+
import { dirname, join } from "path";
|
|
44
|
+
import { fileURLToPath } from "url";
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* The token the template puts on every line a human must replace.
|
|
48
|
+
*
|
|
49
|
+
* An HTML comment, so it renders as nothing and a consumer who leaves one in
|
|
50
|
+
* sees a clean document — which is exactly why a machine has to be the thing
|
|
51
|
+
* that notices. Distinctive enough that no prose contains it by accident.
|
|
52
|
+
*/
|
|
53
|
+
export const PLACEHOLDER_MARKER = "rungate:placeholder";
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* ## Two accepted forms, and why that is not a weakening
|
|
57
|
+
*
|
|
58
|
+
* The template below writes `### Claim N — statement`. rungate's own
|
|
59
|
+
* `SUCCESS.md` — hand-written in `22aa5b20`, four months before this
|
|
60
|
+
* validator, and the ONLY real instance of the document this file validates —
|
|
61
|
+
* writes `1. **statement**` with an indented `Check:` underneath.
|
|
62
|
+
*
|
|
63
|
+
* The first draft of this parser recognised only the template's form, and the
|
|
64
|
+
* consequence was immediate: run against the document that defines the genre,
|
|
65
|
+
* it reported *"SUCCESS.md defines no claims"*. A validator whose single
|
|
66
|
+
* real-world example fails it is not strict, it is miscalibrated — and the
|
|
67
|
+
* repair everybody actually reaches for is to stop running the validator.
|
|
68
|
+
*
|
|
69
|
+
* So both forms parse. This costs nothing in strictness, because **neither
|
|
70
|
+
* form is what the check is about**: the refusals are placeholders left in,
|
|
71
|
+
* claims with nothing that can falsify them, and a standing table that
|
|
72
|
+
* disagrees with the claims. A document can satisfy either syntax and still
|
|
73
|
+
* fail all three. Widening the syntax does not widen what passes.
|
|
74
|
+
*/
|
|
75
|
+
const CLAIM_FORMS: RegExp[] = [
|
|
76
|
+
/** `### Claim N — statement`, the form the template writes. */
|
|
77
|
+
/^###\s+Claim\s+(\d+)\s*[—–-]\s*(.*)$/,
|
|
78
|
+
/** `N. **statement**`, the form rungate's own SUCCESS.md has always used. */
|
|
79
|
+
/^(\d+)\.\s+\*\*(.+?)\*\*\s*$/,
|
|
80
|
+
];
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The falsifiability line. Its absence is the defect this file exists for.
|
|
84
|
+
*
|
|
85
|
+
* `Check:` is rungate's spelling of it and `**How it fails:**` is the
|
|
86
|
+
* template's; they are one field asked two ways.
|
|
87
|
+
*
|
|
88
|
+
* **`**How to measure it:**` is deliberately NOT one of them.** It is the
|
|
89
|
+
* other half of the template and it answers a different question — the
|
|
90
|
+
* command that produces the observation, not the observation that would prove
|
|
91
|
+
* the claim false. Admitting it here was the first draft, and it meant a
|
|
92
|
+
* claim could satisfy the falsifiability rule while saying only how to look:
|
|
93
|
+
* "run the suite" with nothing stating what a failure would look like is the
|
|
94
|
+
* slogan this refusal exists to catch. An unfilled measurement line is still
|
|
95
|
+
* caught, by the placeholder and TODO checks.
|
|
96
|
+
*/
|
|
97
|
+
const FALSIFIABILITY = /^(?:\*\*How it fails:\*\*|Check:)\s*(.*)$/;
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* A standing-table row, keyed by the claim number in its first cell.
|
|
101
|
+
*
|
|
102
|
+
* `| 1 | untested |` (template) and `| 1 — gates can fail | Partial… |`
|
|
103
|
+
* (rungate) both key on 1. A first cell that does not START with a number is
|
|
104
|
+
* not a claim row and is skipped rather than refused — rungate's table has a
|
|
105
|
+
* `| consumer list |` row, and the file carries two unrelated `| mutation |`
|
|
106
|
+
* tables whose cells are prose.
|
|
107
|
+
*/
|
|
108
|
+
const STANDING_ROW = /^\|\s*(\d+)\s*(?:[—–-][^|]*)?\|/;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Text that means the author stopped at the template.
|
|
112
|
+
*
|
|
113
|
+
* The first version was `/^(TODO\b|-+$|—$)/` — uppercase `TODO` only — and a
|
|
114
|
+
* review walked straight through it: `todo`, `TBD`, `FIXME`, `???`, `xxx`,
|
|
115
|
+
* `N/A` and a one-character `.` all scored zero violations as both the claim
|
|
116
|
+
* statement AND its `How it fails`. A detector narrower than what it detects,
|
|
117
|
+
* and the narrowing was a `[A-Z]`.
|
|
118
|
+
*
|
|
119
|
+
* The length floor catches the rest of the family without needing to
|
|
120
|
+
* enumerate it. Ten characters is below any real claim and above every
|
|
121
|
+
* placeholder anyone writes; a claim shorter than that is not a falsifiable
|
|
122
|
+
* statement whatever words are in it.
|
|
123
|
+
*/
|
|
124
|
+
const UNFILLED = /^(TODO|TBD|FIXME|XXX|N\/?A)\b|^(\?+|-+|—|\.+)$/i;
|
|
125
|
+
const MIN_MEANINGFUL = 10;
|
|
126
|
+
function unfilled(text: string): boolean {
|
|
127
|
+
const t = text.trim();
|
|
128
|
+
return t.length < MIN_MEANINGFUL || UNFILLED.test(t);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export interface SuccessClaim {
|
|
132
|
+
number: number;
|
|
133
|
+
statement: string;
|
|
134
|
+
/** The text after `**How it fails:**`, or null when the line is absent. */
|
|
135
|
+
howItFails: string | null;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
export interface SuccessDoc {
|
|
139
|
+
claims: SuccessClaim[];
|
|
140
|
+
/** Claim numbers the standing table names. */
|
|
141
|
+
standingRows: number[];
|
|
142
|
+
/** Lines still carrying the placeholder marker, by 1-based line number. */
|
|
143
|
+
placeholderLines: number[];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** Read the structure out of a SUCCESS.md. Pure; takes the text. */
|
|
147
|
+
export function parseSuccessDoc(text: string): SuccessDoc {
|
|
148
|
+
const claims: SuccessClaim[] = [];
|
|
149
|
+
const standingRows: number[] = [];
|
|
150
|
+
const placeholderLines: number[] = [];
|
|
151
|
+
const lines = text.split("\n");
|
|
152
|
+
|
|
153
|
+
let current: SuccessClaim | null = null;
|
|
154
|
+
let fenced = false;
|
|
155
|
+
for (let i = 0; i < lines.length; i++) {
|
|
156
|
+
const line = lines[i];
|
|
157
|
+
if (/^\s*(```|~~~)/.test(line)) {
|
|
158
|
+
fenced = !fenced;
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
if (line.includes(PLACEHOLDER_MARKER)) placeholderLines.push(i + 1);
|
|
162
|
+
if (fenced) continue;
|
|
163
|
+
|
|
164
|
+
let heading: RegExpExecArray | null = null;
|
|
165
|
+
for (const form of CLAIM_FORMS) {
|
|
166
|
+
heading = form.exec(line);
|
|
167
|
+
if (heading) break;
|
|
168
|
+
}
|
|
169
|
+
if (heading) {
|
|
170
|
+
current = { number: Number(heading[1]), statement: heading[2].trim(), howItFails: null };
|
|
171
|
+
claims.push(current);
|
|
172
|
+
continue;
|
|
173
|
+
}
|
|
174
|
+
const fails = FALSIFIABILITY.exec(line.trim());
|
|
175
|
+
// Attributed to the claim it sits under. A `How it fails` before any
|
|
176
|
+
// claim heading belongs to nothing and is not counted, which is right —
|
|
177
|
+
// the template's own prose mentions the phrase above the first claim.
|
|
178
|
+
// FIRST one wins, so a claim's refusal always quotes the line a reader
|
|
179
|
+
// would look at rather than whichever duplicate came last.
|
|
180
|
+
//
|
|
181
|
+
// `current` is cleared at the next heading and the scan skips fenced
|
|
182
|
+
// regions, both for the same reason: without them the first matching
|
|
183
|
+
// line ANYWHERE below a claim satisfied it. A `Check:` six lines down
|
|
184
|
+
// under `## Appendix` counted, and so did one inside a ```markdown block
|
|
185
|
+
// — so a SUCCESS.md that documents its own format handed every claim
|
|
186
|
+
// below the example a falsifiability line for free.
|
|
187
|
+
if (fails && current && current.howItFails === null) {
|
|
188
|
+
current.howItFails = fails[1].trim();
|
|
189
|
+
continue;
|
|
190
|
+
}
|
|
191
|
+
// Any heading ends the previous claim's scope, so a falsifiability line
|
|
192
|
+
// under a later section cannot be borrowed by an earlier claim.
|
|
193
|
+
if (/^#{1,6}\s/.test(line)) current = null;
|
|
194
|
+
const row = STANDING_ROW.exec(line.trim());
|
|
195
|
+
if (row) standingRows.push(Number(row[1]));
|
|
196
|
+
}
|
|
197
|
+
return { claims, standingRows, placeholderLines };
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** What a reading of SUCCESS.md established, and what it could not. */
|
|
201
|
+
export interface SuccessVerdict {
|
|
202
|
+
/** Refusals. Empty means the document is structurally sound. */
|
|
203
|
+
violations: string[];
|
|
204
|
+
/** Set when there is no document to read at all. Never a silent pass. */
|
|
205
|
+
unmeasured: string | null;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* The ONE place that decides whether a SUCCESS.md is real (#485).
|
|
210
|
+
*
|
|
211
|
+
* Kept separate from the conformity test and from the CLI so there is a
|
|
212
|
+
* single binding to mutate, and so every case can be driven without a
|
|
213
|
+
* filesystem.
|
|
214
|
+
*/
|
|
215
|
+
export function successViolations(text: string | null, template: string | null): SuccessVerdict {
|
|
216
|
+
// Three states, not two. `undefined` means the caller is not asking for a
|
|
217
|
+
// residue comparison at all — the parser's own unit tests, which have no
|
|
218
|
+
// template and are not pretending to. `TEMPLATE_MISSING` (or an explicit
|
|
219
|
+
// `null`, in case a future reader reintroduces one) means a template WAS
|
|
220
|
+
// looked for and not found, and that is a refusal rather than a quiet skip.
|
|
221
|
+
const templateAbsent = template === TEMPLATE_MISSING || template === null;
|
|
222
|
+
const residueTemplate =
|
|
223
|
+
templateAbsent || template === NO_RESIDUE_CHECK ? undefined : template;
|
|
224
|
+
if (text === null) {
|
|
225
|
+
return {
|
|
226
|
+
violations: [],
|
|
227
|
+
unmeasured:
|
|
228
|
+
`UNMEASURED: this project has no SUCCESS.md, so there is nothing stating what it is ` +
|
|
229
|
+
`building or which claims would prove it works. That is not a failure and it is not ` +
|
|
230
|
+
`clean either — nothing here can be measured against a target that was never written ` +
|
|
231
|
+
`down. Run \`bunx rungate create-success\` to seed one.`,
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
if (text === UNREADABLE) {
|
|
236
|
+
return {
|
|
237
|
+
violations: [
|
|
238
|
+
`SUCCESS.md exists but could not be read as a regular file — it may be a symlink, a ` +
|
|
239
|
+
`directory, a device, or have permissions that deny reading. A symlink is refused ` +
|
|
240
|
+
`deliberately, the same way the scaffold refuses to write through one. That is not ` +
|
|
241
|
+
`the same as having no SUCCESS.md, and it is not clean: nothing could be measured.`,
|
|
242
|
+
],
|
|
243
|
+
unmeasured: null,
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
// The generator's seed, untouched, is UNMEASURED rather than a failure.
|
|
248
|
+
//
|
|
249
|
+
// The scaffold now seeds this file whether or not the project asked, so a
|
|
250
|
+
// consumer who re-scaffolds to take an unrelated update would otherwise go
|
|
251
|
+
// from a green suite to a hard FAIL over a document they never wrote, with
|
|
252
|
+
// no way back — deleting it is undone by the next re-scaffold.
|
|
253
|
+
//
|
|
254
|
+
// And it is the honest verdict: a pristine seed carries exactly as much
|
|
255
|
+
// information about this project as no file at all, which is the thing
|
|
256
|
+
// `null` already reports as unmeasured. The refusal is aimed at a document
|
|
257
|
+
// somebody STARTED and left half-written, because that is the state which
|
|
258
|
+
// reads as considered and is not. Any edit at all moves it into that set.
|
|
259
|
+
if (residueTemplate && isPristineSeed(text, residueTemplate)) {
|
|
260
|
+
return {
|
|
261
|
+
violations: [],
|
|
262
|
+
unmeasured:
|
|
263
|
+
`UNMEASURED: SUCCESS.md is the generator's template, unmodified, so this project ` +
|
|
264
|
+
`has not yet stated what it is building or which claims would prove it works. ` +
|
|
265
|
+
`Nothing here is failing — nothing has been claimed yet. Edit it and this check ` +
|
|
266
|
+
`starts measuring; every placeholder you leave behind then becomes a refusal.`,
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
const doc = parseSuccessDoc(text);
|
|
271
|
+
const out: string[] = [];
|
|
272
|
+
|
|
273
|
+
if (doc.placeholderLines.length > 0) {
|
|
274
|
+
out.push(
|
|
275
|
+
`SUCCESS.md still carries ${doc.placeholderLines.length} placeholder marker(s) from the ` +
|
|
276
|
+
`generator, on line(s) ${doc.placeholderLines.join(", ")}. An unfilled template is ` +
|
|
277
|
+
`indistinguishable from a considered one to everything except a reader, which is why ` +
|
|
278
|
+
`this refuses rather than counting the file as present.`,
|
|
279
|
+
);
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// The residue check could not run. Reported rather than skipped: without
|
|
283
|
+
// this branch an installation missing the template reverts to the pre-#502
|
|
284
|
+
// behaviour exactly, and the document that scored 1 violation scores 0 with
|
|
285
|
+
// `unmeasured` still null — indistinguishable from a clean document.
|
|
286
|
+
if (templateAbsent) {
|
|
287
|
+
out.push(
|
|
288
|
+
`SUCCESS.md could not be compared against the generator's template — ` +
|
|
289
|
+
`templates/SUCCESS-TEMPLATE.md is not in this rungate installation, so the check that ` +
|
|
290
|
+
`catches a document still carrying the template's prose did not run. This is not a ` +
|
|
291
|
+
`clean result: see test/package-closure.test.ts, which exists to stop exactly this.`,
|
|
292
|
+
);
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
// The backstop the marker check turned out to need. Asked before the
|
|
296
|
+
// per-claim rules so the loudest problem is reported first.
|
|
297
|
+
if (residueTemplate) {
|
|
298
|
+
const residue = templateResidue(text, residueTemplate);
|
|
299
|
+
if (residue.length > 0) {
|
|
300
|
+
out.push(
|
|
301
|
+
// "passage(s)", not "line(s) verbatim". The check now matches lines
|
|
302
|
+
// AND reflowed sentences, so a hit need not be a line and need not
|
|
303
|
+
// be verbatim — reflow surviving the comparison is the point of
|
|
304
|
+
// #515, and a message saying "verbatim" about a re-wrapped
|
|
305
|
+
// paragraph sends the reader looking for text that is not there.
|
|
306
|
+
// The count is a count of distinct passages, which is why a
|
|
307
|
+
// two-line paragraph can report more hits than it has lines.
|
|
308
|
+
`SUCCESS.md still carries ${residue.length} passage(s) from the generator's ` +
|
|
309
|
+
`template, so this document is partly unwritten: ` +
|
|
310
|
+
residue.slice(0, 3).map(l => JSON.stringify(l.slice(0, 70))).join(", ") +
|
|
311
|
+
`${residue.length > 3 ? `, and ${residue.length - 3} more` : ""}. ` +
|
|
312
|
+
`Deleting the placeholder markers is not the same as replacing the text they mark.`,
|
|
313
|
+
);
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
if (doc.claims.length === 0) {
|
|
318
|
+
out.push(
|
|
319
|
+
`SUCCESS.md defines no claims. The file's whole purpose is the falsifiable statements ` +
|
|
320
|
+
`that mean the project works. Declare one as "### Claim N — ..." or as a numbered ` +
|
|
321
|
+
`"N. **...**" list item.`,
|
|
322
|
+
);
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
for (const claim of doc.claims) {
|
|
326
|
+
if (unfilled(claim.statement)) {
|
|
327
|
+
out.push(`SUCCESS.md claim ${claim.number} has no statement — it still reads "${claim.statement}".`);
|
|
328
|
+
}
|
|
329
|
+
if (claim.howItFails === null) {
|
|
330
|
+
out.push(
|
|
331
|
+
`SUCCESS.md claim ${claim.number} has no "**How it fails:**" (or "Check:") line. A ` +
|
|
332
|
+
`claim nothing can falsify is a slogan — make it measurable or delete it.`,
|
|
333
|
+
);
|
|
334
|
+
} else if (unfilled(claim.howItFails)) {
|
|
335
|
+
out.push(
|
|
336
|
+
`SUCCESS.md claim ${claim.number}'s "How it fails" is still the template's placeholder ` +
|
|
337
|
+
`("${claim.howItFails}"), so nothing states what would prove the claim false.`,
|
|
338
|
+
);
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
// Both directions. A standing table listing a claim nobody defined is as
|
|
343
|
+
// broken as a claim nobody tracks, and the second is the one that rots
|
|
344
|
+
// quietly — a claim added and never given a row reads as met by omission.
|
|
345
|
+
const defined = new Set(doc.claims.map(c => c.number));
|
|
346
|
+
const tracked = new Set(doc.standingRows);
|
|
347
|
+
for (const n of [...tracked].sort((a, b) => a - b)) {
|
|
348
|
+
if (!defined.has(n)) {
|
|
349
|
+
out.push(`SUCCESS.md's standing table has a row for claim ${n}, which no claim defines.`);
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
for (const n of [...defined].sort((a, b) => a - b)) {
|
|
353
|
+
if (!tracked.has(n)) {
|
|
354
|
+
out.push(
|
|
355
|
+
`SUCCESS.md claim ${n} has no row in the standing table, so nothing records where it ` +
|
|
356
|
+
`actually stands. A claim with no standing reads as met by omission.`,
|
|
357
|
+
);
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
return { violations: out, unmeasured: null };
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/**
|
|
365
|
+
* Lines the project still shares, verbatim, with the template it came from.
|
|
366
|
+
*
|
|
367
|
+
* ## Why the placeholder markers were not enough
|
|
368
|
+
*
|
|
369
|
+
* The first version of this check rested entirely on `PLACEHOLDER_MARKER`,
|
|
370
|
+
* and a security review found the hole by reading what the generator PRINTS:
|
|
371
|
+
* `create-success` tells the user "Replace every line marked
|
|
372
|
+
* `rungate:placeholder`". A user who does exactly that — deletes the five
|
|
373
|
+
* marker lines, names the claims, writes a `How it fails` for each, and stops
|
|
374
|
+
* — produced **seven surviving `TODO`s and zero violations**. `## The thing`
|
|
375
|
+
* was still the template's instruction text, every `**How to measure it:**`
|
|
376
|
+
* still read `TODO`, and `owner:`/`updated:` were still `TODO-OWNER` and
|
|
377
|
+
* `TODO-DATE`.
|
|
378
|
+
*
|
|
379
|
+
* One `grep -v` cleared the entire guard. That is the second shape in
|
|
380
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — a detector narrower than
|
|
381
|
+
* what it detects — and the narrowing was *instructed by our own output*.
|
|
382
|
+
*
|
|
383
|
+
* ## Why this shape rather than more rules
|
|
384
|
+
*
|
|
385
|
+
* Adding a rule per section (require a filled `## The thing`, require a
|
|
386
|
+
* `**How to measure it:**`, ...) would be a list that has to stay in sync
|
|
387
|
+
* with the template by hand, and a new template section would silently go
|
|
388
|
+
* unchecked. This asks the question directly instead: **is this document
|
|
389
|
+
* still, in part, the template?** It needs no per-section knowledge.
|
|
390
|
+
*
|
|
391
|
+
* **What it does NOT cover, stated because the first version of this
|
|
392
|
+
* sentence claimed otherwise.** It said "a new template section is covered
|
|
393
|
+
* the day it ships", and sec-485 showed that is false: anything the
|
|
394
|
+
* template writes as a table row, a non-claim heading, or a structurally
|
|
395
|
+
* pure line is invisible to this check permanently. The guarantee is
|
|
396
|
+
* narrower — *template PROSE, and claim statements, are covered the day
|
|
397
|
+
* they ship*. A future template that puts its placeholder text into table
|
|
398
|
+
* cells is not covered, and whoever writes one has to think about it.
|
|
399
|
+
*
|
|
400
|
+
* Two of the exclusions were narrowed in response rather than merely
|
|
401
|
+
* documented: claim headings now compare their statement (see below), and
|
|
402
|
+
* the old flat `length <= 12` floor became a test for structural purity,
|
|
403
|
+
* because a short sentence is still a sentence. The floor was hiding
|
|
404
|
+
* `"prevent."` on today's own template.
|
|
405
|
+
*
|
|
406
|
+
* Structural lines are excluded because they are SUPPOSED to match: headings,
|
|
407
|
+
* table rows, frontmatter keys, and anything too short to be instruction
|
|
408
|
+
* prose. Measured against the one real instance — rungate's own SUCCESS.md,
|
|
409
|
+
* written four months before the template — the only overlap is
|
|
410
|
+
* `doc-type: reference` and `status: active`, both frontmatter.
|
|
411
|
+
*/
|
|
412
|
+
/**
|
|
413
|
+
* Template prose as REFLOW-INVARIANT units: whole sentences, read out of the
|
|
414
|
+
* template with its line breaks collapsed (#515).
|
|
415
|
+
*
|
|
416
|
+
* `templateResidue` compared line against line, so it saw a copy-pasted
|
|
417
|
+
* paragraph only while the line breaks were byte-identical. `prettier
|
|
418
|
+
* --prose-wrap`, a different editor width, or one pass of an LLM rewriting
|
|
419
|
+
* the file moved them without touching a word, and the whole paragraph went
|
|
420
|
+
* invisible. That is the second shape in
|
|
421
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — *text matching that a
|
|
422
|
+
* reformat, a line break or a different platform defeats* — and the
|
|
423
|
+
* docstring above claimed a guarantee it did not have.
|
|
424
|
+
*
|
|
425
|
+
* ## Why the unit is a sentence and not a block
|
|
426
|
+
*
|
|
427
|
+
* #515 proposed comparing normalized BLOCKS. Measured against the shipped
|
|
428
|
+
* template, that catches strictly less than the line check it would have
|
|
429
|
+
* replaced, and it fails the verbatim case it was meant to keep:
|
|
430
|
+
*
|
|
431
|
+
* - The template writes `<!-- rungate:placeholder -->` on the line directly
|
|
432
|
+
* above the prose it marks, with no blank line between, so the block IS
|
|
433
|
+
* the comment plus the prose. A reader who deletes the comment — which
|
|
434
|
+
* that comment instructs them to do — no longer matches the block. That
|
|
435
|
+
* is the likeliest real shape, and block comparison misses it.
|
|
436
|
+
* - A reader who keeps one sentence of a four-sentence paragraph no longer
|
|
437
|
+
* matches the block either, where the line check matched the lines kept.
|
|
438
|
+
*
|
|
439
|
+
* Splitting to sentences fixes both: the unit stops depending on where the
|
|
440
|
+
* newlines are AND on how much of the paragraph survived. It also drops the
|
|
441
|
+
* residual false-refusal surface #515 names — a single wrapped word like
|
|
442
|
+
* `prevent.` is never a sentence, so it stops being a comparable unit at
|
|
443
|
+
* all, where as a LINE it was one.
|
|
444
|
+
*
|
|
445
|
+
* `stripHtmlComments` is applied to BOTH sides, and the battery is the
|
|
446
|
+
* reason it is still here rather than the argument above. Making it a
|
|
447
|
+
* no-op was 0 red of 62 on the first pass: every comment the template
|
|
448
|
+
* carries sits above a `TODO` placeholder that `unfilled()` discards
|
|
449
|
+
* anyway, so no fixture could tell the two apart. The input that can is a
|
|
450
|
+
* reader keeping a template sentence and splitting it with a comment —
|
|
451
|
+
* `test/success-doc.test.ts`'s "an HTML comment interleaved into the prose"
|
|
452
|
+
* case — which is the reformat-defeats-the-detector shape one layer down.
|
|
453
|
+
*
|
|
454
|
+
* Two things measured and NOT changed, recorded so the next reader does not
|
|
455
|
+
* have to measure them again:
|
|
456
|
+
*
|
|
457
|
+
* - **The TEMPLATE-side strip is dead on today's template.** Dropping it is
|
|
458
|
+
* 0 red; dropping the DOCUMENT-side one is 1. An input that distinguishes
|
|
459
|
+
* them exists — template comment text quoted inside a fenced block in a
|
|
460
|
+
* document — but it is contrived, and a fixture built to make a number
|
|
461
|
+
* move is worth less than the sentence saying so. Kept for symmetry, with
|
|
462
|
+
* the asymmetry written down rather than implied.
|
|
463
|
+
* - **`unfilled()`'s 10-character floor was chosen for an EQUALITY test and
|
|
464
|
+
* is reused for a SUBSTRING test.** That is sound today — the shortest
|
|
465
|
+
* live template unit is 22 characters and the shortest non-placeholder
|
|
466
|
+
* one is 45, and 52,333 external markdown files produce zero new
|
|
467
|
+
* refusals. A future template sentence of 10-20 characters becomes a
|
|
468
|
+
* substring landmine against every document in a consumer repo, and the
|
|
469
|
+
* argument below reasons only about the 4-character `TODO`.
|
|
470
|
+
*
|
|
471
|
+
* `unfilled()` is the floor rather than a fresh number. It is already the
|
|
472
|
+
* module's answer to "is this string too slight to mean anything", and the
|
|
473
|
+
* only template unit it removes is the bare `TODO` a claim heading reduces
|
|
474
|
+
* to — four characters, which as a substring test would match almost every
|
|
475
|
+
* document in this repo.
|
|
476
|
+
*/
|
|
477
|
+
function templateSentences(template: string): string[] {
|
|
478
|
+
const out: string[] = [];
|
|
479
|
+
for (const block of stripHtmlComments(template).split(/\n[ \t]*\n/)) {
|
|
480
|
+
const prose: string[] = [];
|
|
481
|
+
// `structural` is a WHOLE-LINE classifier, and inside a block only the
|
|
482
|
+
// leading lines are whole lines — the rest are continuations of a
|
|
483
|
+
// sentence that started above them. Asking it about a continuation is
|
|
484
|
+
// asking the wrong question, and it answers:
|
|
485
|
+
//
|
|
486
|
+
// Name the one thing that is true when this works. Do not
|
|
487
|
+
// hedge: a hedged claim cannot fail, and a claim that cannot
|
|
488
|
+
// fail is not a claim.
|
|
489
|
+
//
|
|
490
|
+
// `hedge: ...` matches the frontmatter rule, is dropped, and lines 1
|
|
491
|
+
// and 3 join across the hole to produce `Do not fail is not a claim.`
|
|
492
|
+
// — a sentence that exists nowhere, replacing one that does. Re-wrap
|
|
493
|
+
// the same prose one word differently and which sentence survives
|
|
494
|
+
// changes. That is the line-break dependence this function exists to
|
|
495
|
+
// remove, still present in the function that removes it.
|
|
496
|
+
//
|
|
497
|
+
// So structural lines are only recognised as a LEADING RUN. Once prose
|
|
498
|
+
// starts, the rest of the block is its continuation. A heading
|
|
499
|
+
// immediately above a paragraph still drops; a paragraph that happens
|
|
500
|
+
// to wrap onto `hedge:` does not.
|
|
501
|
+
//
|
|
502
|
+
// Found by sec-515 on a synthetic template. Zero instances on today's,
|
|
503
|
+
// which is why the fixture in `test/success-doc.test.ts` is synthetic
|
|
504
|
+
// too — a latent falsification of a documented guarantee is still a
|
|
505
|
+
// falsification.
|
|
506
|
+
let leading = true;
|
|
507
|
+
for (const line of block.split("\n").map(l => l.trim()).filter(l => l.length > 0)) {
|
|
508
|
+
const claim = CLAIM_HEADING.exec(line);
|
|
509
|
+
// A claim heading contributes its STATEMENT and not its prefix, for
|
|
510
|
+
// the same reason the line path strips it: `### Claim 1 — <text>` is
|
|
511
|
+
// a heading by syntax and the claim itself by content.
|
|
512
|
+
if (claim) {
|
|
513
|
+
if (claim[2].trim()) {
|
|
514
|
+
prose.push(claim[2].trim());
|
|
515
|
+
leading = false;
|
|
516
|
+
}
|
|
517
|
+
continue;
|
|
518
|
+
}
|
|
519
|
+
if (leading && structural(line)) continue;
|
|
520
|
+
leading = false;
|
|
521
|
+
prose.push(line);
|
|
522
|
+
}
|
|
523
|
+
if (prose.length === 0) continue;
|
|
524
|
+
// Joined FIRST, then split. Splitting per line would re-introduce the
|
|
525
|
+
// dependency on where the breaks are, which is the whole defect.
|
|
526
|
+
for (const sentence of collapseWhitespace(prose.join(" ")).split(SENTENCE_BREAK)) {
|
|
527
|
+
// No dedup here. `templateResidue` already refuses to push a unit it
|
|
528
|
+
// has, so a second `!out.includes` was a decider nothing could
|
|
529
|
+
// distinguish — measured at 0 red of 71, where the two sites in
|
|
530
|
+
// `templateResidue` are 1 each. Two guards answering one question are
|
|
531
|
+
// behaviourally one, and the dead one is invisible.
|
|
532
|
+
const u = sentence.trim();
|
|
533
|
+
if (u.length > 0 && !unfilled(u)) out.push(u);
|
|
534
|
+
}
|
|
535
|
+
}
|
|
536
|
+
return out;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
/** After a terminator, before something that can open a sentence. */
|
|
540
|
+
const SENTENCE_BREAK = /(?<=[.!?])\s+(?=[A-Z"`*\[(])/;
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* ONE binding each, shared by both halves of `templateResidue` (#515).
|
|
544
|
+
*
|
|
545
|
+
* They were local to the line matcher. The sentence matcher needs the same
|
|
546
|
+
* two questions answered the same way, and a second private copy would be
|
|
547
|
+
* the fourth shape in `.claude/rules/checks-must-be-able-to-fail.md`: two
|
|
548
|
+
* deciders that agree, where mutating either leaves the other holding every
|
|
549
|
+
* case up and no behavioural test can say which one is dead.
|
|
550
|
+
*/
|
|
551
|
+
const CLAIM_HEADING = /^(#{1,6}\s+\w[\w ]*\d+\s*[—–:-]\s*)(.*)$/;
|
|
552
|
+
const structural = (l: string) =>
|
|
553
|
+
l.length === 0
|
|
554
|
+
|| /^[\s|:+_*=~-]*$/.test(l)
|
|
555
|
+
|| l.startsWith("|")
|
|
556
|
+
|| l.startsWith("---")
|
|
557
|
+
|| (l.startsWith("#") && !CLAIM_HEADING.test(l))
|
|
558
|
+
|| /^[a-z][a-z-]*:\s/.test(l);
|
|
559
|
+
const collapseWhitespace = (s: string) => s.replace(/\s+/g, " ").trim();
|
|
560
|
+
|
|
561
|
+
/**
|
|
562
|
+
* Terminated HTML comments become a space. An UNTERMINATED `<!--` is left
|
|
563
|
+
* exactly as it is.
|
|
564
|
+
*
|
|
565
|
+
* Written as a scan rather than `s.replace(/<!--[\s\S]*?-->/g, " ")`, which
|
|
566
|
+
* is quadratic on unterminated openers and runs on consumer documents.
|
|
567
|
+
* Measured by sec-515 through `templateResidue`, doubling the input:
|
|
568
|
+
*
|
|
569
|
+
* | input | regex | this |
|
|
570
|
+
* |---|---|---|
|
|
571
|
+
* | 80 KB (20k openers) | 616 ms | — |
|
|
572
|
+
* | 200 KB | 3.85 s | — |
|
|
573
|
+
* | 400 KB | 15.70 s | — |
|
|
574
|
+
* | 800 KB | 61.77 s | — |
|
|
575
|
+
* | 320 KB, isolated | 9.99 s | 0.1 ms |
|
|
576
|
+
*
|
|
577
|
+
* For each `<!--` the lazy body scans to end-of-input looking for `-->`,
|
|
578
|
+
* fails, backtracks, and the engine advances one position: O(N·L). Properly
|
|
579
|
+
* closed comments are fine either way — 200k of them in 3.8 ms — so the
|
|
580
|
+
* blowup needs only one malformed document to arrive.
|
|
581
|
+
*
|
|
582
|
+
* Anchoring the unterminated case with `(?:-->|$)` would also be linear, and
|
|
583
|
+
* is NOT what this does: it would make a stray `<!--` swallow the rest of
|
|
584
|
+
* the file, and everything after it would stop being comparable. That is a
|
|
585
|
+
* silent narrowing of the check, bought to fix a performance bug.
|
|
586
|
+
*/
|
|
587
|
+
const stripHtmlComments = (s: string) => {
|
|
588
|
+
let out = "";
|
|
589
|
+
let i = 0;
|
|
590
|
+
for (;;) {
|
|
591
|
+
const open = s.indexOf("<!--", i);
|
|
592
|
+
if (open === -1) break;
|
|
593
|
+
const close = s.indexOf("-->", open + 4);
|
|
594
|
+
if (close === -1) break;
|
|
595
|
+
out += `${s.slice(i, open)} `;
|
|
596
|
+
i = close + 3;
|
|
597
|
+
}
|
|
598
|
+
return out + s.slice(i);
|
|
599
|
+
};
|
|
600
|
+
|
|
601
|
+
export function templateResidue(text: string, template: string): string[] {
|
|
602
|
+
// A claim heading is NOT structural. `### Claim 1 — TODO` is a heading by
|
|
603
|
+
// syntax and the claim's whole statement by content, and excluding it
|
|
604
|
+
// outright made every claim statement permanently invisible to this check
|
|
605
|
+
// — held up only by `unfilled()`, which catches `TODO` and nothing else.
|
|
606
|
+
// sec-485 demonstrated the consequence on a plausible next-version
|
|
607
|
+
// template: a document whose two claims still read "the system behaves as
|
|
608
|
+
// intended under normal use" scored ZERO violations, because that text
|
|
609
|
+
// lives in a heading. So the prefix is stripped and the STATEMENT is
|
|
610
|
+
// compared.
|
|
611
|
+
//
|
|
612
|
+
// The prefix is matched by SHAPE — a word-run, a number, a separator —
|
|
613
|
+
// rather than by the literal word `Claim` and the literal em-dash today's
|
|
614
|
+
// template happens to use. sec-500 measured the narrow version against
|
|
615
|
+
// four spellings of one statement: `Claim 1 —` and `Claim 1 -` were
|
|
616
|
+
// caught, `Claim 1:` and `SC 1 —` were INVISIBLE, because a heading that
|
|
617
|
+
// misses the pattern falls back to being excluded as structural. That is
|
|
618
|
+
// sec-485's finding surviving for every spelling but one, and a colon is
|
|
619
|
+
// not an exotic choice, so keying the check to a template detail would
|
|
620
|
+
// have reopened the hole on the next template edit.
|
|
621
|
+
//
|
|
622
|
+
// The cost, named because it is real: this cannot tell `Claim 1 — <a
|
|
623
|
+
// statement the reader must write>` from `Phase 2 - <a section title the
|
|
624
|
+
// reader must keep>`, so a template carrying the second gets a false
|
|
625
|
+
// refusal. Zero instances today — the shipped template has no numbered
|
|
626
|
+
// heading but its claims, and the widening flags nothing new across all
|
|
627
|
+
// 227 markdown files in this repo — and `test/success-doc.test.ts`'s
|
|
628
|
+
// "R1 cost" case fails loudly for whoever adds the first one.
|
|
629
|
+
const comparable = (l: string) => {
|
|
630
|
+
const m = CLAIM_HEADING.exec(l);
|
|
631
|
+
return m ? m[2].trim() : l;
|
|
632
|
+
};
|
|
633
|
+
|
|
634
|
+
// Structurally pure, rather than merely short.
|
|
635
|
+
//
|
|
636
|
+
// This replaced a flat `l.length <= 12` floor, which was the weakest rule
|
|
637
|
+
// in the check and the only one with no second layer behind it. On today's
|
|
638
|
+
// template it already hid a real line of body prose — `"prevent."`, eight
|
|
639
|
+
// characters — and on sec-485's next-version fixture it hid `Describe it.`
|
|
640
|
+
// and `List them.`, the entire contents of two sections. A short sentence
|
|
641
|
+
// is still a sentence; what cannot be residue is punctuation and table
|
|
642
|
+
// scaffolding, so that is what this excludes.
|
|
643
|
+
const mine = new Set(text.split("\n").map(l => comparable(l.trim())));
|
|
644
|
+
const out: string[] = [];
|
|
645
|
+
for (const raw of template.split("\n")) {
|
|
646
|
+
const l = raw.trim();
|
|
647
|
+
if (structural(l)) continue;
|
|
648
|
+
const c = comparable(l);
|
|
649
|
+
if (!mine.has(c)) continue;
|
|
650
|
+
if (!out.includes(c)) out.push(c);
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
// UNION, not replacement, and the two halves are kept because each
|
|
654
|
+
// reaches an input the other cannot (#515).
|
|
655
|
+
//
|
|
656
|
+
// This is the arrangement `.claude/rules/checks-must-be-able-to-fail.md`
|
|
657
|
+
// permits for two deciders — "keep both and give each an input only it
|
|
658
|
+
// can reach" — rather than the one it warns about, and the inputs are
|
|
659
|
+
// written down as named cases in `test/success-doc.test.ts`:
|
|
660
|
+
//
|
|
661
|
+
// | Input | Caught by |
|
|
662
|
+
// |---|---|
|
|
663
|
+
// | the paragraph REFLOWED onto one line | sentences only |
|
|
664
|
+
// | the paragraph with one word changed mid-sentence | lines only |
|
|
665
|
+
// | the paragraph verbatim | both |
|
|
666
|
+
//
|
|
667
|
+
// The line half is not redundant: a sentence is a coarser unit, so an
|
|
668
|
+
// edit anywhere inside one destroys the whole match, while the untouched
|
|
669
|
+
// LINES either side of that edit still match. Dropping it to "simplify"
|
|
670
|
+
// loses the partial-edit case, which is the lazy-fill this check exists
|
|
671
|
+
// for. Measured: the union flags nothing new across all 227 markdown
|
|
672
|
+
// files in this repo — the only file it refuses is the template itself.
|
|
673
|
+
const normalised = collapseWhitespace(stripHtmlComments(text));
|
|
674
|
+
for (const sentence of templateSentences(template)) {
|
|
675
|
+
if (!normalised.includes(sentence)) continue;
|
|
676
|
+
if (!out.includes(sentence)) out.push(sentence);
|
|
677
|
+
}
|
|
678
|
+
return out;
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
/**
|
|
682
|
+
* The installation is missing `templates/SUCCESS-TEMPLATE.md`.
|
|
683
|
+
*
|
|
684
|
+
* A distinct value rather than `null`, for the reason `UNREADABLE` is: the
|
|
685
|
+
* residue check is the half of this validator that catches a document which
|
|
686
|
+
* deleted the markers and kept the prose, and a falsy template silently
|
|
687
|
+
* switched it off. Same document, same checker, template absent: **1
|
|
688
|
+
* violation became 0, with nothing recorded.** That is the first shape in
|
|
689
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — a read failure defaulting
|
|
690
|
+
* to an empty violation list — and #484 is this repo's standing proof that
|
|
691
|
+
* "`templates/` is in `files[]`, so it cannot happen" is a thing that has
|
|
692
|
+
* already happened once while every check stayed green.
|
|
693
|
+
*
|
|
694
|
+
* `create-success` and `seedSuccessDoc` both name a missing template loudly.
|
|
695
|
+
* This makes `successViolations` the third reader of that file rather than
|
|
696
|
+
* the only one that shrugs.
|
|
697
|
+
*/
|
|
698
|
+
export const TEMPLATE_MISSING = "\u0000rungate:template-missing";
|
|
699
|
+
|
|
700
|
+
/**
|
|
701
|
+
* "I am deliberately not comparing against the template."
|
|
702
|
+
*
|
|
703
|
+
* The opt-out the parser's own unit cases need, made explicit. The
|
|
704
|
+
* parameter used to be optional, so OMITTING it switched the residue check
|
|
705
|
+
* off silently — and the only thing keeping it on in production was that
|
|
706
|
+
* nobody had yet written a third call site that forgot the argument.
|
|
707
|
+
* Nothing asserted it; it was convention.
|
|
708
|
+
*
|
|
709
|
+
* sec-485's note, and the same move as `readSuccessTemplate(): string`
|
|
710
|
+
* applied to the parameter rather than the return: omission is now a type
|
|
711
|
+
* error, and an opt-out is something a reader sees at the call site.
|
|
712
|
+
*/
|
|
713
|
+
export const NO_RESIDUE_CHECK = "\u0000rungate:no-residue-check";
|
|
714
|
+
|
|
715
|
+
/**
|
|
716
|
+
* The template the generator copies.
|
|
717
|
+
*
|
|
718
|
+
* Never returns `null` — an absent template is `TEMPLATE_MISSING`, which
|
|
719
|
+
* `successViolations` refuses. Returning a falsy value here is what made the
|
|
720
|
+
* residue check fail open, so the type no longer permits it.
|
|
721
|
+
*/
|
|
722
|
+
export function readSuccessTemplate(): string {
|
|
723
|
+
const p = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "SUCCESS-TEMPLATE.md");
|
|
724
|
+
return existsSync(p) ? readFileSync(p, "utf-8") : TEMPLATE_MISSING;
|
|
725
|
+
}
|
|
726
|
+
|
|
727
|
+
/** Read the project's SUCCESS.md, or null when there is none. */
|
|
728
|
+
export const UNREADABLE = "\u0000rungate:unreadable";
|
|
729
|
+
|
|
730
|
+
export function readSuccessDoc(root: string): string | null {
|
|
731
|
+
const p = join(root, "SUCCESS.md");
|
|
732
|
+
// `existsSync` is true for a DIRECTORY, and `readFileSync` then throws
|
|
733
|
+
// EISDIR. The throw escaped `seedSuccessDoc` and aborted the whole scaffold
|
|
734
|
+
// run mid-way — after some files were written and before others — which is
|
|
735
|
+
// a worse outcome than any verdict this function can return.
|
|
736
|
+
//
|
|
737
|
+
// It returns a distinct UNREADABLE rather than `null`, because "the file is
|
|
738
|
+
// there and I could not read it" and "there is no file" are different
|
|
739
|
+
// answers and collapsing them is the SKIP-is-indistinguishable-from-success
|
|
740
|
+
// shape. UNREADABLE refuses; absent is unmeasured.
|
|
741
|
+
let stat;
|
|
742
|
+
try {
|
|
743
|
+
stat = lstatSync(p);
|
|
744
|
+
} catch {
|
|
745
|
+
return null;
|
|
746
|
+
}
|
|
747
|
+
if (!stat.isFile()) return UNREADABLE;
|
|
748
|
+
try {
|
|
749
|
+
return readFileSync(p, "utf-8");
|
|
750
|
+
} catch {
|
|
751
|
+
return UNREADABLE;
|
|
752
|
+
}
|
|
753
|
+
}
|
|
754
|
+
|
|
755
|
+
/**
|
|
756
|
+
* Fill the template's owner and date. ONE substitution, two callers.
|
|
757
|
+
*
|
|
758
|
+
* `create-success` did this and `seedSuccessDoc` wrote the template raw, so
|
|
759
|
+
* the same logical seed produced different bytes depending on which path
|
|
760
|
+
* created it — a scaffolded SUCCESS.md kept `owner: TODO-OWNER` and
|
|
761
|
+
* `updated: TODO-DATE` forever, and nothing checked frontmatter.
|
|
762
|
+
*/
|
|
763
|
+
export function seedFromTemplate(template: string, owner: string, date: string): string {
|
|
764
|
+
return template
|
|
765
|
+
.replace("owner: TODO-OWNER", `owner: ${owner}`)
|
|
766
|
+
.replace("updated: TODO-DATE", `updated: ${date}`);
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
/**
|
|
770
|
+
* Is this document the generator's seed, untouched?
|
|
771
|
+
*
|
|
772
|
+
* Owner and date are normalised out, because those are the two things the
|
|
773
|
+
* generator itself fills in — a seed with them substituted is still a seed.
|
|
774
|
+
*/
|
|
775
|
+
export function isPristineSeed(text: string, template: string): boolean {
|
|
776
|
+
const norm = (t: string) =>
|
|
777
|
+
t.replace(/^owner:.*$/m, "owner:").replace(/^updated:.*$/m, "updated:").trim();
|
|
778
|
+
return norm(text) === norm(template);
|
|
779
|
+
}
|