rungate 0.2.1 → 0.3.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/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +400 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +220 -0
- package/lib/compliance-report.ts +504 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/conformity.ts +1818 -131
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +272 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +506 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +489 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +35 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +186 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +114 -4
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/steps.ts +2680 -0
- package/lib/scanner.ts +701 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +177 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +358 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +250 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/package.json +24 -2
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Can this AC's evidence command satisfy this AC's threshold — for ANY
|
|
3
|
+
* implementation?
|
|
4
|
+
*
|
|
5
|
+
* #217. The discovery agent writes the statement, the threshold and the
|
|
6
|
+
* command in one pass, and nothing then checks the three against each other.
|
|
7
|
+
* Measured on `wf_5e3ed885-98c`, in a single AC, two independent ways:
|
|
8
|
+
*
|
|
9
|
+
* grep -n 'SC-\w+' lib/conformity.ts | grep 'x]' threshold: >= 1
|
|
10
|
+
*
|
|
11
|
+
* `+` is a LITERAL in a basic regular expression, so the pattern reads
|
|
12
|
+
* "SC-, one word character, a plus sign" and selects nothing in any file.
|
|
13
|
+
* With `grep -E` it returns lines 199 and 318. The same AC also carried
|
|
14
|
+
* `contains 'checked: boolean'` against a field legitimately declared
|
|
15
|
+
* `checked?: boolean`.
|
|
16
|
+
*
|
|
17
|
+
* ## The mirror of the house defect
|
|
18
|
+
*
|
|
19
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about a check that passed
|
|
20
|
+
* because of what it never looked at. This is that disease inverted: a check
|
|
21
|
+
* that FAILED because of what it could never match. In both the verdict is
|
|
22
|
+
* independent of the code under test, and that — not the direction — is the
|
|
23
|
+
* defect. A check must be able to fail and able to pass.
|
|
24
|
+
*
|
|
25
|
+
* ## What this deliberately does NOT do
|
|
26
|
+
*
|
|
27
|
+
* It does not consult the dry-run's output. Before the work is done,
|
|
28
|
+
* `grep -c newThing src/` returning 0 against a `>= 1` threshold is what a
|
|
29
|
+
* CORRECT acceptance criterion looks like. An unsatisfied threshold is the
|
|
30
|
+
* normal state of an AC; only an UNSATISFIABLE one is a defect, and the
|
|
31
|
+
* difference is whether an implementation could change the answer.
|
|
32
|
+
*
|
|
33
|
+
* So every refusal here holds for all possible code. That is a hard bar and it
|
|
34
|
+
* is why the set is small — three shapes, each of which makes the verdict a
|
|
35
|
+
* constant.
|
|
36
|
+
*/
|
|
37
|
+
|
|
38
|
+
// ── Shell tokenising ─────────────────────────────────────────────────────
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Split one pipeline stage into tokens, honouring quotes, and strip the
|
|
42
|
+
* quotes. Not a shell parser — it is enough to find grep's flags and its
|
|
43
|
+
* pattern argument, and anything it cannot read falls through to NO refusal.
|
|
44
|
+
* A tokeniser that guesses would refuse a working command, and a false
|
|
45
|
+
* refusal here stops a legitimate run cold.
|
|
46
|
+
*/
|
|
47
|
+
function tokenize(stage: string): string[] {
|
|
48
|
+
const tokens: string[] = [];
|
|
49
|
+
let current = "";
|
|
50
|
+
let quote: '"' | "'" | null = null;
|
|
51
|
+
let started = false;
|
|
52
|
+
|
|
53
|
+
for (let i = 0; i < stage.length; i++) {
|
|
54
|
+
const ch = stage[i];
|
|
55
|
+
if (quote) {
|
|
56
|
+
if (ch === quote) quote = null;
|
|
57
|
+
else current += ch;
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
if (ch === '"' || ch === "'") {
|
|
61
|
+
quote = ch;
|
|
62
|
+
started = true;
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
if (/\s/.test(ch)) {
|
|
66
|
+
if (started || current) tokens.push(current);
|
|
67
|
+
current = "";
|
|
68
|
+
started = false;
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
current += ch;
|
|
72
|
+
}
|
|
73
|
+
if (started || current) tokens.push(current);
|
|
74
|
+
return tokens;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The pipeline stages of a command, in order, trimmed. */
|
|
78
|
+
function stages(command: string): string[] {
|
|
79
|
+
return command.split("|").map((s) => s.trim()).filter((s) => s.length > 0);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Strip leading `VAR=value` assignments and return the command word. */
|
|
83
|
+
function commandWord(tokens: string[]): string {
|
|
84
|
+
for (const t of tokens) {
|
|
85
|
+
if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) continue;
|
|
86
|
+
return t;
|
|
87
|
+
}
|
|
88
|
+
return "";
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// ── grep stages ──────────────────────────────────────────────────────────
|
|
92
|
+
|
|
93
|
+
interface GrepStage {
|
|
94
|
+
/** The pattern argument, quotes already removed. */
|
|
95
|
+
pattern: string;
|
|
96
|
+
/** -E, -P, or the egrep name: the pattern is NOT a basic regular expression. */
|
|
97
|
+
extended: boolean;
|
|
98
|
+
/** -c: this stage emits a count, not the matching text. */
|
|
99
|
+
counting: boolean;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Short flags that consume the following token. */
|
|
103
|
+
const ARG_FLAGS = new Set(["m", "A", "B", "C", "d", "D", "f"]);
|
|
104
|
+
const LONG_ARG_FLAGS = new Set([
|
|
105
|
+
"--max-count", "--after-context", "--before-context", "--context",
|
|
106
|
+
"--file", "--include", "--exclude", "--exclude-dir", "--binary-files",
|
|
107
|
+
"--devices", "--directories", "--label", "--color", "--colour",
|
|
108
|
+
]);
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Read one pipeline stage as a grep invocation, or return null if it is not
|
|
112
|
+
* one — or is one this cannot read confidently.
|
|
113
|
+
*/
|
|
114
|
+
function readGrep(stage: string): GrepStage | null {
|
|
115
|
+
const tokens = tokenize(stage);
|
|
116
|
+
const word = commandWord(tokens);
|
|
117
|
+
if (!/^(?:[a-z]*grep)$/.test(word)) return null;
|
|
118
|
+
|
|
119
|
+
let extended = word === "egrep";
|
|
120
|
+
let counting = false;
|
|
121
|
+
let pattern: string | null = null;
|
|
122
|
+
|
|
123
|
+
const rest = tokens.slice(tokens.indexOf(word) + 1);
|
|
124
|
+
for (let i = 0; i < rest.length; i++) {
|
|
125
|
+
const t = rest[i];
|
|
126
|
+
|
|
127
|
+
if (t === "--") {
|
|
128
|
+
pattern = rest[i + 1] ?? null;
|
|
129
|
+
break;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
if (t.startsWith("--")) {
|
|
133
|
+
const name = t.split("=")[0];
|
|
134
|
+
if (name === "--extended-regexp" || name === "--perl-regexp") extended = true;
|
|
135
|
+
if (name === "--regexp") {
|
|
136
|
+
pattern = t.includes("=") ? t.slice(t.indexOf("=") + 1) : rest[++i] ?? null;
|
|
137
|
+
break;
|
|
138
|
+
}
|
|
139
|
+
if (!t.includes("=") && LONG_ARG_FLAGS.has(name)) i++;
|
|
140
|
+
continue;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
if (t.startsWith("-") && t.length > 1) {
|
|
144
|
+
const cluster = t.slice(1);
|
|
145
|
+
if (cluster.includes("E") || cluster.includes("P")) extended = true;
|
|
146
|
+
if (cluster.includes("c")) counting = true;
|
|
147
|
+
// `-e PATTERN` — the pattern is the next token, wherever `e` sits in
|
|
148
|
+
// the cluster, because a cluster can only carry one argument-taking
|
|
149
|
+
// flag and it has to be last.
|
|
150
|
+
if (cluster.endsWith("e")) {
|
|
151
|
+
pattern = rest[++i] ?? null;
|
|
152
|
+
break;
|
|
153
|
+
}
|
|
154
|
+
if (ARG_FLAGS.has(cluster[cluster.length - 1])) i++;
|
|
155
|
+
continue;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
pattern = t;
|
|
159
|
+
break;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
if (pattern === null) return null;
|
|
163
|
+
return { pattern, extended, counting };
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
// ── Clause 1: a quantifier that is a literal ─────────────────────────────
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* `+` and `?` are ordinary characters in a basic regular expression. Most of
|
|
170
|
+
* the time that is harmless or even intended — `grep 'checked?: boolean'` and
|
|
171
|
+
* `grep 'function foo('` are correct BREs whose author meant those characters
|
|
172
|
+
* literally, and refusing them would break far more runs than it saves.
|
|
173
|
+
*
|
|
174
|
+
* What is NOT plausibly intended is a `+` or `?` directly after something that
|
|
175
|
+
* is itself a character class or a group: `\w+`, `[0-9]+`, `)?`. A literal
|
|
176
|
+
* plus sign after a word character is a pattern almost nothing contains, and
|
|
177
|
+
* every instance found in this repo's run history meant the quantifier.
|
|
178
|
+
*
|
|
179
|
+
* So the rule is positional, not a ban on the characters. The boundary is in
|
|
180
|
+
* `test/evidence-satisfiability.test.ts` in both directions, because
|
|
181
|
+
* narrowing a detector is the change most likely to buy green with blindness.
|
|
182
|
+
*/
|
|
183
|
+
const LITERAL_QUANTIFIER = /(\\[wWdDsS]|\[[^\]]*\]|\))[+?]/;
|
|
184
|
+
|
|
185
|
+
function breRefusal(g: GrepStage): string | null {
|
|
186
|
+
if (g.extended) return null;
|
|
187
|
+
const hit = g.pattern.match(LITERAL_QUANTIFIER);
|
|
188
|
+
if (!hit) return null;
|
|
189
|
+
return (
|
|
190
|
+
`the pattern \`${g.pattern}\` is a BASIC regular expression, where \`${hit[0].slice(-1)}\` ` +
|
|
191
|
+
`after \`${hit[1]}\` is a literal character rather than a quantifier, so it matches ` +
|
|
192
|
+
`nothing under any implementation — add \`-E\``
|
|
193
|
+
);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
// ── Clause 2: a count compared as text ───────────────────────────────────
|
|
197
|
+
|
|
198
|
+
/** Does this command's output consist of a number rather than the matched text? */
|
|
199
|
+
function emitsCount(command: string): boolean {
|
|
200
|
+
const all = stages(command);
|
|
201
|
+
// `tr -d ' '` and friends reformat a value without changing what it IS, so
|
|
202
|
+
// the producing stage is the last one that is not pure reformatting.
|
|
203
|
+
let i = all.length - 1;
|
|
204
|
+
while (i > 0 && commandWord(tokenize(all[i])) === "tr") i--;
|
|
205
|
+
const last = all[i];
|
|
206
|
+
if (commandWord(tokenize(last)) === "wc") return true;
|
|
207
|
+
const g = readGrep(last);
|
|
208
|
+
return g?.counting === true;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function thresholdRefusal(command: string, op: string): string | null {
|
|
212
|
+
if (op !== "contains" && op !== "notContains") return null;
|
|
213
|
+
if (!emitsCount(command)) return null;
|
|
214
|
+
return (
|
|
215
|
+
`the command emits a count, not text, so a \`${op}\` threshold can never hold over ` +
|
|
216
|
+
`its output — compare the count with a numeric operator instead`
|
|
217
|
+
);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// ── Clause 3: a count of counts ──────────────────────────────────────────
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* `grep -c ... | wc -l` prints the number of FILES grep reported a count for,
|
|
224
|
+
* which is 1 for the single-file form regardless of how many matches there
|
|
225
|
+
* were. The verdict is then a constant, and a constant satisfies or fails its
|
|
226
|
+
* threshold for reasons that have nothing to do with the code.
|
|
227
|
+
*
|
|
228
|
+
* ship.js carried a comment naming this the "always-1 bug" and avoided
|
|
229
|
+
* creating it in one branch. Nothing refused it when the discovery agent
|
|
230
|
+
* wrote it directly.
|
|
231
|
+
*/
|
|
232
|
+
function countOfCountsRefusal(command: string): string | null {
|
|
233
|
+
const all = stages(command);
|
|
234
|
+
let i = all.length - 1;
|
|
235
|
+
while (i > 0 && commandWord(tokenize(all[i])) === "tr") i--;
|
|
236
|
+
if (i < 1 || commandWord(tokenize(all[i])) !== "wc") return null;
|
|
237
|
+
const upstream = readGrep(all[i - 1]);
|
|
238
|
+
if (!upstream?.counting) return null;
|
|
239
|
+
return (
|
|
240
|
+
"`grep -c` already prints a count, so piping it into `wc -l` counts the lines of " +
|
|
241
|
+
"that count — one per file, whatever the matches were — and the result cannot vary " +
|
|
242
|
+
"with the code"
|
|
243
|
+
);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
// ── The one decider ──────────────────────────────────────────────────────
|
|
247
|
+
|
|
248
|
+
/** The shape this reads. Structurally `ACInput`, repeated so this stays a leaf. */
|
|
249
|
+
export interface SatisfiabilityInput {
|
|
250
|
+
id?: string;
|
|
251
|
+
evidenceMethod?: { type?: string; command?: string };
|
|
252
|
+
threshold?: { op?: string; value?: string | number; unit?: string };
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Why this AC's evidence can never satisfy its own threshold, or null if
|
|
257
|
+
* nothing here can prove that it cannot.
|
|
258
|
+
*
|
|
259
|
+
* Null is "not provably unsatisfiable", NOT "verified satisfiable" — the
|
|
260
|
+
* weaker claim is the honest one, and it is the direction this is allowed to
|
|
261
|
+
* be wrong in. Missing a bad AC costs one failed run that a human reads. A
|
|
262
|
+
* false refusal blocks a correct run, and nobody trusts the refuser again.
|
|
263
|
+
*/
|
|
264
|
+
export function satisfiabilityRefusal(ac: SatisfiabilityInput | null | undefined): string | null {
|
|
265
|
+
const command = ac?.evidenceMethod?.command;
|
|
266
|
+
if (typeof command !== "string" || command.trim().length === 0) return null;
|
|
267
|
+
|
|
268
|
+
const reasons: string[] = [];
|
|
269
|
+
|
|
270
|
+
const countOfCounts = countOfCountsRefusal(command);
|
|
271
|
+
if (countOfCounts) reasons.push(countOfCounts);
|
|
272
|
+
|
|
273
|
+
const op = ac?.threshold?.op;
|
|
274
|
+
if (typeof op === "string") {
|
|
275
|
+
const mismatch = thresholdRefusal(command, op);
|
|
276
|
+
if (mismatch) reasons.push(mismatch);
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
for (const stage of stages(command)) {
|
|
280
|
+
const g = readGrep(stage);
|
|
281
|
+
if (!g) continue;
|
|
282
|
+
const bre = breRefusal(g);
|
|
283
|
+
if (bre) reasons.push(bre);
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
if (reasons.length === 0) return null;
|
|
287
|
+
return reasons.join("; ");
|
|
288
|
+
}
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* #299 — stamping a doc header must ADD fields, never replace the block.
|
|
3
|
+
*
|
|
4
|
+
* A PostToolUse formatter rewrote the frontmatter of every `.md` it touched
|
|
5
|
+
* by rebuilding the block from its four required keys:
|
|
6
|
+
*
|
|
7
|
+
* const fmLines = REQUIRED.map(k => `${k}: ${stamped[k]}`).join('\n');
|
|
8
|
+
* newContent = content.replace(FRONTMATTER_RE, `---\n${fmLines}\n---`);
|
|
9
|
+
*
|
|
10
|
+
* Everything else in the block was discarded. Editing
|
|
11
|
+
* `.claude/rules/key-files.md` dropped its `description:` — the field Claude
|
|
12
|
+
* Code's rule loading surfaces a rule by — and `.claude/rules/*.md` carried
|
|
13
|
+
* that field unanimously. The damage was one file per edit, only to files
|
|
14
|
+
* someone had touched, and nothing went red: a rules file that has stopped
|
|
15
|
+
* being surfaced to agents looks exactly like one that is surfaced and
|
|
16
|
+
* ignored.
|
|
17
|
+
*
|
|
18
|
+
* There is a second failure underneath it. The parser was
|
|
19
|
+
* `line.split(":")`, which cannot see a YAML block value:
|
|
20
|
+
*
|
|
21
|
+
* paths:
|
|
22
|
+
* - ".github/workflows/**"
|
|
23
|
+
*
|
|
24
|
+
* reads as `paths: ""` plus two unparseable lines. So even a merge written
|
|
25
|
+
* over that parser's output would have flattened `harness-managed.md`'s
|
|
26
|
+
* `paths:` list — the list that defines which files the scaffold owns.
|
|
27
|
+
*
|
|
28
|
+
* Both are fixed here, in one place, with the parse and the serialise written
|
|
29
|
+
* against each other so a value the parser cannot represent is a parse
|
|
30
|
+
* failure rather than a silent truncation.
|
|
31
|
+
*
|
|
32
|
+
* ## Scope
|
|
33
|
+
*
|
|
34
|
+
* This is deliberately NOT a YAML implementation. It handles the two shapes
|
|
35
|
+
* doc frontmatter actually uses — `key: scalar` and a `key:` followed by
|
|
36
|
+
* indented lines — and REFUSES anything else by returning null, so a caller
|
|
37
|
+
* leaves a block it does not understand alone rather than rewriting it into
|
|
38
|
+
* something smaller. A formatter that half-understands its input is how this
|
|
39
|
+
* issue happened.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
export interface FrontmatterEntry {
|
|
43
|
+
key: string;
|
|
44
|
+
/** The text after `key:` on the same line, trimmed. Empty for a block. */
|
|
45
|
+
inline: string;
|
|
46
|
+
/** Continuation lines verbatim, including their indentation. */
|
|
47
|
+
block: string[];
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export interface ParsedFrontmatter {
|
|
51
|
+
entries: FrontmatterEntry[];
|
|
52
|
+
/** Everything after the closing `---`, verbatim. */
|
|
53
|
+
body: string;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
const OPEN = /^---\r?\n/;
|
|
57
|
+
|
|
58
|
+
/** A key line: an identifier at column 0, then a colon. */
|
|
59
|
+
const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Parse a document's frontmatter.
|
|
63
|
+
*
|
|
64
|
+
* Returns null when there is no frontmatter block, when it is unterminated,
|
|
65
|
+
* or when it contains a line this module cannot represent. Null means "do not
|
|
66
|
+
* touch it", never "it was empty".
|
|
67
|
+
*/
|
|
68
|
+
export function parseFrontmatter(content: string): ParsedFrontmatter | null {
|
|
69
|
+
if (!OPEN.test(content)) return null;
|
|
70
|
+
const afterOpen = content.replace(OPEN, "");
|
|
71
|
+
const close = afterOpen.search(/^---\r?$|^---$/m);
|
|
72
|
+
if (close === -1) return null;
|
|
73
|
+
|
|
74
|
+
// One trailing newline is the separator before the closing fence, not a
|
|
75
|
+
// blank line in the block. Keeping it parks an empty line on the last
|
|
76
|
+
// entry's block, which then lands in the MIDDLE of the block as soon as a
|
|
77
|
+
// key is appended after it.
|
|
78
|
+
const raw = afterOpen.slice(0, close).replace(/\r?\n$/, "");
|
|
79
|
+
const body = afterOpen.slice(close).replace(/^---\r?\n?/, "");
|
|
80
|
+
|
|
81
|
+
const entries: FrontmatterEntry[] = [];
|
|
82
|
+
for (const line of raw.split("\n")) {
|
|
83
|
+
if (line.trim() === "") {
|
|
84
|
+
// A blank line inside the block belongs to whatever came before it; an
|
|
85
|
+
// entry-less blank at the top is representable as nothing.
|
|
86
|
+
if (entries.length > 0) entries[entries.length - 1].block.push(line);
|
|
87
|
+
continue;
|
|
88
|
+
}
|
|
89
|
+
const m = KEY_LINE.exec(line);
|
|
90
|
+
if (m) {
|
|
91
|
+
entries.push({ key: m[1], inline: m[2].trim(), block: [] });
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
// Not a key line. Only legal as a continuation of the previous key, and
|
|
95
|
+
// only if it is indented — anything else is a shape this module does not
|
|
96
|
+
// understand, and guessing is what caused #299.
|
|
97
|
+
if (entries.length === 0 || !/^\s/.test(line)) return null;
|
|
98
|
+
entries[entries.length - 1].block.push(line);
|
|
99
|
+
}
|
|
100
|
+
return { entries, body };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Render a parsed block back to text. Round-trips byte-for-byte. */
|
|
104
|
+
export function serialiseFrontmatter(parsed: ParsedFrontmatter): string {
|
|
105
|
+
const lines: string[] = [];
|
|
106
|
+
for (const e of parsed.entries) {
|
|
107
|
+
lines.push(e.inline === "" ? `${e.key}:` : `${e.key}: ${e.inline}`);
|
|
108
|
+
lines.push(...e.block);
|
|
109
|
+
}
|
|
110
|
+
// Trailing blanks captured into the last entry's block would double the
|
|
111
|
+
// newline before the closing fence.
|
|
112
|
+
while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
|
|
113
|
+
return `---\n${lines.join("\n")}\n---\n${parsed.body}`;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Add the given fields to a document's frontmatter without removing anything.
|
|
118
|
+
*
|
|
119
|
+
* - A key already present is LEFT AS IT IS, including its block value. The
|
|
120
|
+
* formatter's job is to fill gaps, not to have opinions about values
|
|
121
|
+
* somebody wrote on purpose.
|
|
122
|
+
* - New keys are appended in the order given, after everything existing, so a
|
|
123
|
+
* diff shows additions rather than a reordered block.
|
|
124
|
+
* - A document with no frontmatter gets one.
|
|
125
|
+
* - A block this module cannot parse is returned UNCHANGED, with `stamped`
|
|
126
|
+
* empty and `refused` set. Leaving a file alone is always safe; rewriting
|
|
127
|
+
* one you cannot read is what #299 was.
|
|
128
|
+
*/
|
|
129
|
+
export function stampFrontmatter(
|
|
130
|
+
content: string,
|
|
131
|
+
fields: Record<string, string>,
|
|
132
|
+
): { content: string; stamped: string[]; refused: string | null } {
|
|
133
|
+
const hasOpen = OPEN.test(content);
|
|
134
|
+
const parsed = hasOpen ? parseFrontmatter(content) : { entries: [], body: content };
|
|
135
|
+
|
|
136
|
+
if (!parsed) {
|
|
137
|
+
return {
|
|
138
|
+
content,
|
|
139
|
+
stamped: [],
|
|
140
|
+
refused:
|
|
141
|
+
"the frontmatter block could not be parsed, so it was left alone. Rewriting a " +
|
|
142
|
+
"block you cannot read is how #299 dropped `description:` from every rules file.",
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
const present = new Set(parsed.entries.map(e => e.key));
|
|
147
|
+
const stamped: string[] = [];
|
|
148
|
+
for (const [key, value] of Object.entries(fields)) {
|
|
149
|
+
if (present.has(key)) continue;
|
|
150
|
+
parsed.entries.push({ key, inline: value, block: [] });
|
|
151
|
+
stamped.push(`${key}: ${value}`);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
if (stamped.length === 0) return { content, stamped: [], refused: null };
|
|
155
|
+
|
|
156
|
+
const body = hasOpen ? parsed.body : `\n${parsed.body}`;
|
|
157
|
+
return { content: serialiseFrontmatter({ ...parsed, body }), stamped, refused: null };
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** The keys a document declares, in order. `[]` when there is no block. */
|
|
161
|
+
export function frontmatterKeys(content: string): string[] {
|
|
162
|
+
return parseFrontmatter(content)?.entries.map(e => e.key) ?? [];
|
|
163
|
+
}
|