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.
Files changed (119) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +24 -2
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. 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
+ }