rungate 0.2.1 → 0.4.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 (129) 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/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,368 @@
1
+ /**
2
+ * Reading a goal and its acceptance criteria out of an issue body (#210, #202).
3
+ *
4
+ * `scripts/precompute-goal.ts` replaces two ceremony agents with two regexes
5
+ * run over the raw markdown of a GitHub issue. Both were wrong in the same
6
+ * way, and the shared cause is worth stating before either case:
7
+ *
8
+ * **The extractor had no model of the document it was reading.** It matched
9
+ * lines. A line inside a fenced code block, a line under a "Scope" heading,
10
+ * and a line the harness itself wrote into the issue are all just lines.
11
+ *
12
+ * Two measured instances:
13
+ *
14
+ * - **#210.** Shipping #209, the criteria list came back as exactly one AC:
15
+ * ``SC-N: `workflows/ship.js` executes [MARKER-NAME]``. That is an
16
+ * illustration inside a fenced block showing the SYNTAX of a proposed SC.
17
+ * Marcus was about to be briefed with one acceptance criterion made
18
+ * entirely of placeholders, and nothing downstream would have asked.
19
+ * - **#202.** When a run rescopes an issue for the 6-AC limit it PREPENDS a
20
+ * blockquote banner, which then becomes the first paragraph and therefore
21
+ * the goal. Measured on #200: 414 characters describing the split, none
22
+ * describing the defect. The harness degraded its own input, and only on
23
+ * the LARGE issues where the goal statement matters most.
24
+ *
25
+ * ## Why this is a module and not twenty lines in the script
26
+ *
27
+ * It was twenty lines in the script, at module top level, so none of it was
28
+ * reachable from a test — which is why both defects were found by reading
29
+ * pipeline output by hand rather than by the suite. The functions here take a
30
+ * string and return a value; every case below is a fixture.
31
+ *
32
+ * ## The direction these are allowed to be wrong in
33
+ *
34
+ * Toward extracting LESS and saying so. A criterion missed costs Discovery
35
+ * writing one, which is the designed path. A criterion invented out of
36
+ * documentation is briefed to an agent as a thing to build.
37
+ */
38
+
39
+ /**
40
+ * Markers that identify a blockquote as harness-authored metadata rather than
41
+ * the author's prose.
42
+ *
43
+ * Exported and asserted against `workflows/ship.js`'s decompose prompt by
44
+ * `test/issue-extraction.test.ts`, which is the "fails loudly" half: the
45
+ * banner is written by an agent told to use this wording, so a change to the
46
+ * instruction and no change here turns the suite red instead of silently
47
+ * handing the banner back as a goal (#202).
48
+ *
49
+ * A leading blockquote carrying NONE of these is kept. That is the positive
50
+ * control, and it is the whole difficulty of the case: a parser that
51
+ * discarded every leading blockquote would pass the banner cases for free and
52
+ * lose the goal of any issue whose author opens with a quote.
53
+ */
54
+ export const HARNESS_BANNER_MARKERS = [
55
+ "Rescoped to Phase",
56
+ "Sub-issues:",
57
+ ] as const;
58
+
59
+ /**
60
+ * Line prefixes that make a leading paragraph harness-written front matter.
61
+ *
62
+ * Found by this change rather than reported: `test/fixtures/github/issue-48.json`
63
+ * is a sub-issue, sub-issue bodies open with `Parent: #47`, and the old regex
64
+ * took the first paragraph. So **every decomposed run has briefed its agent
65
+ * with the goal "Parent: #N"** — eleven characters of cross-reference. Same
66
+ * defect as #202's banner, one producer earlier and far more frequent: the
67
+ * banner fires only on a rescope, this fires on every sub-issue.
68
+ *
69
+ * `workflows/ship.js`'s decompose step is told to write both lines, and
70
+ * `test/issue-extraction.test.ts` asserts they are still in that prompt.
71
+ *
72
+ * A paragraph is skipped only when EVERY line in it is one of these and short.
73
+ * An author writing a sentence that begins "Spec: the contract says…" keeps
74
+ * their goal.
75
+ */
76
+ export const HARNESS_PREAMBLE_MARKERS = [
77
+ "Parent: #",
78
+ "Spec: ",
79
+ ] as const;
80
+
81
+ /** Above this, a line is prose that happens to start with a marker. */
82
+ const MAX_PREAMBLE_LINE_CHARS = 120;
83
+
84
+ /** A goal shorter than this is a failed extraction, not a terse author. */
85
+ export const MIN_GOAL_CHARS = 40;
86
+
87
+ /**
88
+ * The one exit code every refusal in `scripts/precompute-goal.ts` routes
89
+ * through, per `.claude/rules/checks-must-be-able-to-fail.md`. Declared once
90
+ * so the test can build a mutant copy of the script with it set to `0` and
91
+ * watch the refusals stop refusing.
92
+ *
93
+ * Not `1`: `1` is the usage error the script already exits with for missing
94
+ * arguments, and a caller that cannot tell "you called me wrong" from "this
95
+ * issue cannot be read" learns nothing from either.
96
+ */
97
+ export const GOAL_REFUSE_EXIT = 3;
98
+
99
+ export interface GoalReading {
100
+ /** The goal paragraph, or null when nothing usable was left. */
101
+ goal: string | null;
102
+ /** Non-null when the body yielded no goal a brief could be written from. */
103
+ refusal: string | null;
104
+ /** True when a harness banner was recognised and stepped over. */
105
+ skippedBanner: boolean;
106
+ }
107
+
108
+ export interface CriteriaReading {
109
+ criteria: string[];
110
+ /** Where they came from, so "none found" can say which question it answered. */
111
+ source: "success-criteria-section" | "none";
112
+ /** Non-null when what was found cannot be briefed — see `isPlaceholder`. */
113
+ refusal: string | null;
114
+ }
115
+
116
+ /**
117
+ * Blank out code so a line inside it cannot be read as content.
118
+ *
119
+ * Lines are REPLACED with empty lines rather than removed: every caller below
120
+ * reasons about headings and ordering, and silently renumbering the document
121
+ * would make a section boundary land somewhere else than the author put it.
122
+ *
123
+ * Indented code is only recognised outside a list. Four-space indentation is
124
+ * also how a nested checkbox is written, and `- [ ] SC-2` nested under a
125
+ * bullet is an acceptance criterion in every issue in this repo — treating it
126
+ * as code would delete real criteria to catch a rare fake one, which is the
127
+ * wrong direction for this module to be wrong in.
128
+ */
129
+ export function stripCodeBlocks(body: string): string {
130
+ const lines = String(body ?? "").split("\n");
131
+ const out: string[] = [];
132
+ let fence: string | null = null;
133
+ let inList = false;
134
+
135
+ for (const line of lines) {
136
+ if (fence !== null) {
137
+ // A closing fence is the same character, at least as long, alone on its
138
+ // line. Anything else is content.
139
+ const close = line.match(/^\s{0,3}(`{3,}|~{3,})\s*$/);
140
+ out.push("");
141
+ if (close && close[1]![0] === fence[0] && close[1]!.length >= fence.length) fence = null;
142
+ continue;
143
+ }
144
+
145
+ const open = line.match(/^\s{0,3}(`{3,}|~{3,})/);
146
+ if (open) {
147
+ fence = open[1]!;
148
+ out.push("");
149
+ continue;
150
+ }
151
+
152
+ if (line.trim() === "") {
153
+ inList = false;
154
+ out.push(line);
155
+ continue;
156
+ }
157
+
158
+ // Indentation is checked BEFORE the list marker, and only outside a list.
159
+ // An indented bullet is a nested list item when a list is open and an
160
+ // indented code block when one is not, and the two are the same bytes —
161
+ // the only thing that tells them apart is what came before.
162
+ if (!inList && /^(?: {4,}|\t)/.test(line)) {
163
+ out.push("");
164
+ continue;
165
+ }
166
+
167
+ if (/^\s*(?:[-*+]|\d+[.)])\s/.test(line)) {
168
+ inList = true;
169
+ out.push(line);
170
+ continue;
171
+ }
172
+
173
+ out.push(line);
174
+ }
175
+
176
+ return out.join("\n");
177
+ }
178
+
179
+ /** `## Heading` → its level, or 0 for a line that is not a heading. */
180
+ function headingLevel(line: string): number {
181
+ const m = line.match(/^(#{1,6})\s+\S/);
182
+ return m ? m[1]!.length : 0;
183
+ }
184
+
185
+ /**
186
+ * The lines under the Success Criteria heading, or null when there is none.
187
+ *
188
+ * Ends at the next heading of the SAME OR HIGHER level, so a `### Phase 2`
189
+ * subsection inside the criteria is kept and the next `## Acceptance` is not.
190
+ */
191
+ export function successCriteriaSection(body: string): string | null {
192
+ const lines = String(body ?? "").split("\n");
193
+ for (let i = 0; i < lines.length; i++) {
194
+ const level = headingLevel(lines[i]!);
195
+ if (!level) continue;
196
+ if (!/^#{1,6}\s+success\s+criteria\b/i.test(lines[i]!)) continue;
197
+ const taken: string[] = [];
198
+ for (let j = i + 1; j < lines.length; j++) {
199
+ const nextLevel = headingLevel(lines[j]!);
200
+ if (nextLevel > 0 && nextLevel <= level) break;
201
+ taken.push(lines[j]!);
202
+ }
203
+ return taken.join("\n");
204
+ }
205
+ return null;
206
+ }
207
+
208
+ /**
209
+ * Is this criterion made of placeholders rather than of a requirement?
210
+ *
211
+ * `SC-N`, `[MARKER-NAME]` and `<thing>` are how this repo writes a TEMPLATE.
212
+ * An AC list consisting of them is the #210 reading exactly, and it reached
213
+ * the point of being briefed.
214
+ */
215
+ export function isPlaceholder(text: string): boolean {
216
+ const s = String(text ?? "").trim();
217
+ if (!s) return true;
218
+ // SC- followed by anything that is not a digit: SC-N, SC-X, SC-NNN.
219
+ if (/\bSC-(?![0-9])[A-Za-z]/.test(s) && !/\bSC-A\d/.test(s)) return true;
220
+ // A bracketed ALL-CAPS slug, which is this repo's template notation.
221
+ if (/\[[A-Z][A-Z0-9_-]{2,}\]/.test(s)) return true;
222
+ // An angle-bracketed placeholder that is not an HTML tag or an email.
223
+ if (/<[a-z][a-z0-9 _-]*>/i.test(s) && !/<\/|@/.test(s)) return true;
224
+ if (/\b(?:TBD|TODO|FIXME|XXX)\b/.test(s)) return true;
225
+ return false;
226
+ }
227
+
228
+ /**
229
+ * Acceptance criteria, from the Success Criteria section only.
230
+ *
231
+ * **Section-scoped, not body-scoped.** The ship skill's own contract says
232
+ * "all lines matching `- [ ] SC-` … under '## Success Criteria'"; the regex
233
+ * it replaced ignored the heading and matched the whole document, so a
234
+ * checklist under "Scope" or "Open questions" was silently promoted to an
235
+ * acceptance criterion (#210).
236
+ *
237
+ * **No section is `[]`, not a refusal.** Most issues in this repo have none,
238
+ * and Discovery authoring the ACs is the designed path. The refusal is for
239
+ * criteria that were found and cannot be briefed.
240
+ */
241
+ export function extractSuccessCriteria(body: string): CriteriaReading {
242
+ const section = successCriteriaSection(stripCodeBlocks(body));
243
+ if (section === null) {
244
+ return { criteria: [], source: "none", refusal: null };
245
+ }
246
+
247
+ const criteria: string[] = [];
248
+ // `SC-` is required, not decorative. The old pattern's `|.+` branch made
249
+ // every `- [ ]` line qualify, so the prefix tested nothing.
250
+ const line = /^\s*-\s*\[[ xX]\]\s*(.+)$/gm;
251
+ let m: RegExpExecArray | null;
252
+ while ((m = line.exec(section)) !== null) {
253
+ const text = m[1]!.trim();
254
+ if (text) criteria.push(text);
255
+ }
256
+
257
+ if (criteria.length === 0) {
258
+ return { criteria, source: "success-criteria-section", refusal: null };
259
+ }
260
+
261
+ const fake = criteria.filter(isPlaceholder);
262
+ if (fake.length === criteria.length) {
263
+ return {
264
+ criteria: [],
265
+ source: "success-criteria-section",
266
+ refusal:
267
+ `every acceptance criterion read from this issue is a placeholder — ` +
268
+ `${JSON.stringify(fake)}. Briefing an agent with a criterion made of ` +
269
+ `placeholders is worse than briefing it with none, because Discovery ` +
270
+ `writes criteria when there are none and accepts these when there are (#210).`,
271
+ };
272
+ }
273
+
274
+ return { criteria, source: "success-criteria-section", refusal: null };
275
+ }
276
+
277
+ /** Does this blockquote carry a marker that makes it harness metadata? */
278
+ function isHarnessBanner(block: string): boolean {
279
+ return HARNESS_BANNER_MARKERS.some(marker => block.includes(marker));
280
+ }
281
+
282
+ /**
283
+ * The goal paragraph: the first prose paragraph the author wrote.
284
+ *
285
+ * Steps over a leading blockquote ONLY when it carries a harness banner
286
+ * marker, so an author who opens with a quote keeps their goal (#202 AC-3 —
287
+ * the parser has to be correct for prose it did not write, because consumer
288
+ * repos have their own conventions).
289
+ */
290
+ export function extractGoal(body: string, title: string): GoalReading {
291
+ const stripped = stripCodeBlocks(body);
292
+ const lines = stripped.split("\n");
293
+ let i = 0;
294
+ let skippedBanner = false;
295
+
296
+ const skipBanner = () => {
297
+ while (i < lines.length && lines[i]!.trim() === "") i++;
298
+ if (i >= lines.length || !/^\s*>/.test(lines[i]!)) return false;
299
+ const start = i;
300
+ while (i < lines.length && (/^\s*>/.test(lines[i]!) || lines[i]!.trim() === "")) {
301
+ // A blank line ends the quote unless the next line resumes it.
302
+ if (lines[i]!.trim() === "" && !/^\s*>/.test(lines[i + 1] ?? "")) break;
303
+ i++;
304
+ }
305
+ const block = lines.slice(start, i).join("\n");
306
+ if (isHarnessBanner(block)) return true;
307
+ i = start; // the author's own quote — keep it
308
+ return false;
309
+ };
310
+
311
+ if (skipBanner()) skippedBanner = true;
312
+
313
+ /** The next paragraph's lines, without consuming them. */
314
+ const peekParagraph = (from: number): { lines: string[]; next: number } => {
315
+ let k = from;
316
+ while (k < lines.length && lines[k]!.trim() === "") k++;
317
+ const taken: string[] = [];
318
+ for (; k < lines.length; k++) {
319
+ if (lines[k]!.trim() === "") break;
320
+ if (headingLevel(lines[k]!) > 0) break;
321
+ taken.push(lines[k]!);
322
+ }
323
+ return { lines: taken, next: k };
324
+ };
325
+
326
+ // Step over harness front matter the same way, and for the same reason. A
327
+ // paragraph counts only if EVERY line is a short marker line, so prose that
328
+ // opens with one of the words is kept.
329
+ for (;;) {
330
+ const { lines: para, next } = peekParagraph(i);
331
+ if (para.length === 0) break;
332
+ const allMetadata = para.every(
333
+ l =>
334
+ l.trim().length <= MAX_PREAMBLE_LINE_CHARS &&
335
+ HARNESS_PREAMBLE_MARKERS.some(marker => l.trim().startsWith(marker)),
336
+ );
337
+ if (!allMetadata) break;
338
+ skippedBanner = true;
339
+ i = next;
340
+ }
341
+
342
+ const paragraph = peekParagraph(i).lines;
343
+ const goal = paragraph.join("\n").trim();
344
+
345
+ if (!goal) {
346
+ return {
347
+ goal: null,
348
+ skippedBanner,
349
+ refusal:
350
+ `this issue body yielded no goal paragraph${skippedBanner ? " after its harness banner" : ""} — ` +
351
+ `the title alone is not a problem statement, and a brief written from it would ` +
352
+ `describe the work by its name rather than by what is wrong (#202).`,
353
+ };
354
+ }
355
+
356
+ if (goal.length < MIN_GOAL_CHARS) {
357
+ return {
358
+ goal: null,
359
+ skippedBanner,
360
+ refusal:
361
+ `the goal paragraph read from this issue is ${goal.length} characters, under the ` +
362
+ `${MIN_GOAL_CHARS} a problem statement needs — ${JSON.stringify(goal)}. A short goal and a ` +
363
+ `missing goal are not the same state, and neither is a goal (#202).`,
364
+ };
365
+ }
366
+
367
+ return { goal, refusal: null, skippedBanner };
368
+ }
@@ -0,0 +1,250 @@
1
+ /**
2
+ * Remove string, template, comment and regex-literal CONTENT from JavaScript
3
+ * source, leaving the code that actually executes (#89).
4
+ *
5
+ * This exists because the #69 guard — "ship.js must not call require() at top
6
+ * level, the sandbox has no module loading" — was stripping template literals
7
+ * with a regex:
8
+ *
9
+ * src.replace(/`(?:\\[\s\S]|[^\\`])*`/g, " `` ")
10
+ *
11
+ * ship.js contains backticks that are not template delimiters: inside
12
+ * single-quoted strings, inside comments, inside other templates. A regex has
13
+ * no way to tell which is which, so one stray backtick paired with a later
14
+ * unrelated one and everything between them was deleted — real code included.
15
+ * 61% of the file vanished, and `buildSafeGitAdd` and `validateFilePaths`,
16
+ * the two helpers #69 is actually about, were invisible to the check that
17
+ * protects them. Two functions calling require('path') and require('fs') were
18
+ * added and the suite reported 48 pass, 0 fail.
19
+ *
20
+ * A single-pass tokenizer is not clever, but it is correct for the thing a
21
+ * regex cannot do: it knows what context it is in, so a backtick inside a
22
+ * comment is just a character.
23
+ *
24
+ * TEMPLATE INTERPOLATIONS ARE KEPT. `${...}` evaluates in the enclosing scope,
25
+ * so a require() there is top-level code and must stay visible. That requires
26
+ * tracking brace depth per template, which is the other thing the regex could
27
+ * not express.
28
+ */
29
+
30
+ /** Characters after which a `/` begins a regex literal rather than division. */
31
+ function regexCanFollow(prev: string): boolean {
32
+ // Scanning back over the last significant character is enough in practice:
33
+ // after a value (identifier, number, closing bracket) a slash is division;
34
+ // after an operator, keyword or opening bracket it starts a regex.
35
+ return !/[A-Za-z0-9_$)\]]/.test(prev);
36
+ }
37
+
38
+ export function stripStringsAndComments(src: string): string {
39
+ let out = "";
40
+ let i = 0;
41
+ // Stack of brace depths, one entry per template literal currently open. An
42
+ // entry is pushed on ` and popped on the matching `; while inside an
43
+ // interpolation the depth counts { } so the template's closing backtick is
44
+ // not confused with a backtick in nested code.
45
+ const templates: number[] = [];
46
+ let lastSignificant = "\n";
47
+
48
+ while (i < src.length) {
49
+ const c = src[i];
50
+ const next = src[i + 1];
51
+
52
+ // Inside a template, but NOT inside one of its interpolations.
53
+ if (templates.length > 0 && templates[templates.length - 1] === 0) {
54
+ if (c === "\\") {
55
+ i += 2;
56
+ continue;
57
+ }
58
+ if (c === "`") {
59
+ templates.pop();
60
+ out += "`";
61
+ lastSignificant = "`";
62
+ i++;
63
+ continue;
64
+ }
65
+ if (c === "$" && next === "{") {
66
+ templates[templates.length - 1] = 1;
67
+ out += "${";
68
+ lastSignificant = "{";
69
+ i += 2;
70
+ continue;
71
+ }
72
+ // Template text: drop it, but keep newlines so line numbers survive.
73
+ out += c === "\n" ? "\n" : "";
74
+ i++;
75
+ continue;
76
+ }
77
+
78
+ // Block comment.
79
+ if (c === "/" && next === "*") {
80
+ const end = src.indexOf("*/", i + 2);
81
+ const body = src.slice(i, end === -1 ? src.length : end + 2);
82
+ out += body.replace(/[^\n]/g, " ");
83
+ i = end === -1 ? src.length : end + 2;
84
+ continue;
85
+ }
86
+
87
+ // Line comment.
88
+ if (c === "/" && next === "/") {
89
+ let end = src.indexOf("\n", i);
90
+ if (end === -1) end = src.length;
91
+ out += " ".repeat(end - i);
92
+ i = end;
93
+ continue;
94
+ }
95
+
96
+ // Quoted string.
97
+ if (c === '"' || c === "'") {
98
+ const quote = c;
99
+ out += quote;
100
+ i++;
101
+ while (i < src.length) {
102
+ if (src[i] === "\\") {
103
+ i += 2;
104
+ continue;
105
+ }
106
+ if (src[i] === quote) break;
107
+ // Unterminated strings must not swallow the rest of the file.
108
+ if (src[i] === "\n") break;
109
+ out += src[i] === "\n" ? "\n" : "";
110
+ i++;
111
+ }
112
+ if (src[i] === quote) {
113
+ out += quote;
114
+ i++;
115
+ }
116
+ lastSignificant = quote;
117
+ continue;
118
+ }
119
+
120
+ // Regex literal. Only when a `/` cannot be division here.
121
+ if (c === "/" && regexCanFollow(lastSignificant)) {
122
+ let j = i + 1;
123
+ let inClass = false;
124
+ let closed = false;
125
+ while (j < src.length) {
126
+ const d = src[j];
127
+ if (d === "\\") {
128
+ j += 2;
129
+ continue;
130
+ }
131
+ if (d === "\n") break; // not a regex after all
132
+ if (d === "[") inClass = true;
133
+ else if (d === "]") inClass = false;
134
+ else if (d === "/" && !inClass) {
135
+ closed = true;
136
+ break;
137
+ }
138
+ j++;
139
+ }
140
+ if (closed) {
141
+ while (j + 1 < src.length && /[a-z]/.test(src[j + 1])) j++; // flags
142
+ // Emit a valid placeholder, not spaces. Blanking the literal leaves
143
+ // `const SHELL_METACHARACTERS = ` with no right-hand side, which makes
144
+ // the output unparseable — and the output has to stay parseable,
145
+ // because "does a real parser still accept this?" is the only
146
+ // independent check that the tokenizer did not mangle the file.
147
+ // The shortest possible regex literal is 3 characters, so this always
148
+ // fits.
149
+ out += "/x/" + " ".repeat(Math.max(0, j - i + 1 - 3));
150
+ i = j + 1;
151
+ lastSignificant = ")"; // a regex is a value
152
+ continue;
153
+ }
154
+ // Fall through: it was division.
155
+ }
156
+
157
+ // Template start.
158
+ if (c === "`") {
159
+ templates.push(0);
160
+ out += "`";
161
+ lastSignificant = "`";
162
+ i++;
163
+ continue;
164
+ }
165
+
166
+ // Brace tracking so an interpolation knows where it ends.
167
+ if (templates.length > 0) {
168
+ if (c === "{") templates[templates.length - 1]++;
169
+ else if (c === "}") {
170
+ templates[templates.length - 1]--;
171
+ if (templates[templates.length - 1] === 0) {
172
+ // Closing `}` of the interpolation: back to template text.
173
+ out += "}";
174
+ lastSignificant = "}";
175
+ i++;
176
+ continue;
177
+ }
178
+ }
179
+ }
180
+
181
+ out += c;
182
+ if (!/\s/.test(c)) lastSignificant = c;
183
+ i++;
184
+ }
185
+
186
+ // Unbalanced state at EOF is the signature of a mis-parse: a template that
187
+ // was opened by something that was not a template delimiter, and therefore a
188
+ // run of real code consumed as template text. That is precisely the failure
189
+ // this module exists to end, so refuse rather than hand back a plausible
190
+ // looking fragment.
191
+ if (templates.length > 0) {
192
+ throw new Error(
193
+ `stripStringsAndComments: ${templates.length} template literal(s) still open at end of input — ` +
194
+ `the tokenizer mis-parsed and the result cannot be trusted`,
195
+ );
196
+ }
197
+
198
+ return out;
199
+ }
200
+
201
+ export interface SyntaxWitness {
202
+ /** True only for `clean`. Both failure modes are failures. */
203
+ ok: boolean;
204
+ verdict: "clean" | "input-unparseable" | "stripping-broke-syntax";
205
+ detail?: string;
206
+ }
207
+
208
+ /**
209
+ * Check the stripper against a real parser.
210
+ *
211
+ * Removing string and comment CONTENT must not change whether the source is
212
+ * syntactically valid. If the stripped output stops parsing, the tokenizer ate
213
+ * something it should not have — which is the whole defect being fixed here,
214
+ * and exactly the parser-differential risk of hand-rolling a lexer.
215
+ *
216
+ * `new Function` here is a PARSER, not an evaluator. Construction compiles the
217
+ * body and stops; the resulting function is discarded without ever being
218
+ * called, so nothing in the input runs. That distinction is the only reason
219
+ * this is acceptable at all — if the result were invoked, feeding it a repo
220
+ * file would be arbitrary code execution. It must stay uninvoked.
221
+ *
222
+ * The wrapping neutralises `export` and makes ship.js's top-level `return`
223
+ * legal; both sides get identical treatment, so only a DIFFERENCE is reported.
224
+ */
225
+ export function strippingPreservesSyntax(src: string): SyntaxWitness {
226
+ const prep = (c: string) => "(async function(){" + c.replace(/^export\s+/gm, "") + "\n})";
227
+ const parses = (c: string): string | null => {
228
+ try {
229
+ new Function(prep(c));
230
+ return null;
231
+ } catch (e) {
232
+ return (e as Error).message;
233
+ }
234
+ };
235
+
236
+ // If the input does not parse, there is no differential to draw — but that
237
+ // is NOT a pass. Returning ok here would mean an unparseable ship.js
238
+ // silently turns the witness into a no-op, which is the exact failure this
239
+ // module was written to end: a check reporting green because of what it
240
+ // could not look at. The caller has to decide, so say which case it is.
241
+ const before = parses(src);
242
+ if (before !== null) {
243
+ return { ok: false, verdict: "input-unparseable", detail: before };
244
+ }
245
+
246
+ const after = parses(stripStringsAndComments(src));
247
+ return after === null
248
+ ? { ok: true, verdict: "clean" }
249
+ : { ok: false, verdict: "stripping-broke-syntax", detail: after };
250
+ }