@feigi/fleet-ctl 3.23.36 → 3.23.38

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 (205) hide show
  1. package/package.json +1 -1
  2. package/scripts/cell-readout.mjs +38 -11
  3. package/scripts/main-checkout.mjs +1 -1
  4. package/scripts/member-write-guard.mjs +1 -1
  5. package/scripts/repo-root.mjs +1 -1
  6. package/skills/run-team/references/reaping.md +1 -1
  7. package/scripts/agent-test-dir-prose.test.mjs +0 -59
  8. package/scripts/agent-test.test.mjs +0 -1640
  9. package/scripts/ambient-git-vars-mjs-prose.test.mjs +0 -397
  10. package/scripts/ambient-git-vars-prose.test.mjs +0 -192
  11. package/scripts/ancestry-check-position-prose.test.mjs +0 -175
  12. package/scripts/apply-ruleset.test.mjs +0 -421
  13. package/scripts/arg-header-probes-prose.test.mjs +0 -394
  14. package/scripts/arg.test.mjs +0 -1354
  15. package/scripts/board-cli.test.mjs +0 -710
  16. package/scripts/board-identity.test.mjs +0 -429
  17. package/scripts/board-liveness-banner.test.mjs +0 -119
  18. package/scripts/board-prev-shape.test.mjs +0 -228
  19. package/scripts/board-tryparse-null.test.mjs +0 -119
  20. package/scripts/board.test.mjs +0 -3121
  21. package/scripts/brief-after-cut-prose.test.mjs +0 -53
  22. package/scripts/candidates-exit3-prose.test.mjs +0 -302
  23. package/scripts/candidates.test.mjs +0 -2312
  24. package/scripts/caveat-unification-prose.test.mjs +0 -98
  25. package/scripts/cell-readout.test.mjs +0 -615
  26. package/scripts/ci-comment-rot-prose.test.mjs +0 -2025
  27. package/scripts/ci-completes-premise-prose.test.mjs +0 -257
  28. package/scripts/ci-state-prose.test.mjs +0 -113
  29. package/scripts/ci-state.test.mjs +0 -1933
  30. package/scripts/ci-vacuous-green.test.mjs +0 -368
  31. package/scripts/citation-sweep-prose.test.mjs +0 -1712
  32. package/scripts/claim-lifecycle.test.mjs +0 -187
  33. package/scripts/claim-ticket.test.mjs +0 -1122
  34. package/scripts/closing-keyword-prose.test.mjs +0 -193
  35. package/scripts/cockpit-launch-idempotent-prose.test.mjs +0 -165
  36. package/scripts/cockpit-tick-nonblocking.test.mjs +0 -210
  37. package/scripts/compute-board.test.mjs +0 -1214
  38. package/scripts/compute-spend.test.mjs +0 -517
  39. package/scripts/consumer-technology-prose.test.mjs +0 -126
  40. package/scripts/cross-repo-citation-prose.test.mjs +0 -155
  41. package/scripts/cwd-isolation-pins.mjs +0 -83
  42. package/scripts/dedupe-guard-prose.test.mjs +0 -243
  43. package/scripts/delete-merged-branch.test.mjs +0 -576
  44. package/scripts/derive-testcmd.test.mjs +0 -595
  45. package/scripts/diff-stats.test.mjs +0 -404
  46. package/scripts/dispatch-block-golden-prose.test.mjs +0 -1130
  47. package/scripts/dispatch-block-pins-prose.test.mjs +0 -615
  48. package/scripts/dispositions-check.test.mjs +0 -936
  49. package/scripts/dispositions-gate-prose.test.mjs +0 -129
  50. package/scripts/drop-merged-label.test.mjs +0 -479
  51. package/scripts/exec-stub.mjs +0 -93
  52. package/scripts/exec-stub.test.mjs +0 -69
  53. package/scripts/expected-jobs-prose.test.mjs +0 -80
  54. package/scripts/fan-out-authorization-prose.test.mjs +0 -80
  55. package/scripts/filing-bar-seat-prose.test.mjs +0 -242
  56. package/scripts/filing-claim-bar-prose.test.mjs +0 -166
  57. package/scripts/finisher-died-prose.test.mjs +0 -31
  58. package/scripts/finisher-dispatch-premise-prose.test.mjs +0 -312
  59. package/scripts/finisher-halt-prose.test.mjs +0 -106
  60. package/scripts/finisher-name-prose.test.mjs +0 -134
  61. package/scripts/finisher-own-tree-prose.test.mjs +0 -299
  62. package/scripts/finisher-pin-race-prose.test.mjs +0 -339
  63. package/scripts/finisher-test-verdict-prose.test.mjs +0 -102
  64. package/scripts/fix-applier-correction-rules-prose.test.mjs +0 -202
  65. package/scripts/fix-applier-result-file-prose.test.mjs +0 -149
  66. package/scripts/fleet-bootstrap.test.mjs +0 -75
  67. package/scripts/fleet-heartbeat.test.mjs +0 -450
  68. package/scripts/fleet-provenance.test.mjs +0 -138
  69. package/scripts/fleet-run.test.mjs +0 -90
  70. package/scripts/fleet-state.test.mjs +0 -460
  71. package/scripts/fleet-tick-prose.test.mjs +0 -300
  72. package/scripts/fleet-tick.test.mjs +0 -2444
  73. package/scripts/force-with-lease-reason-prose.test.mjs +0 -184
  74. package/scripts/frontmatter-check.test.mjs +0 -436
  75. package/scripts/git-env.test.mjs +0 -149
  76. package/scripts/git-status-untracked-mode-sweep.test.mjs +0 -216
  77. package/scripts/gone-walk.test.mjs +0 -213
  78. package/scripts/gp-sep-invariant-prose.test.mjs +0 -188
  79. package/scripts/head-moved-after-label-prose.test.mjs +0 -233
  80. package/scripts/immutable-body-claim-prose.test.mjs +0 -204
  81. package/scripts/implementer-model-tier.test.mjs +0 -235
  82. package/scripts/inflight-citation-prose.test.mjs +0 -144
  83. package/scripts/inflight-exit2-prose.test.mjs +0 -81
  84. package/scripts/inflight-probe-guard-prose.test.mjs +0 -109
  85. package/scripts/inflight-scan-scope-prose.test.mjs +0 -57
  86. package/scripts/inflight.test.mjs +0 -2882
  87. package/scripts/injection-control-prose.test.mjs +0 -404
  88. package/scripts/install-root-audit.test.mjs +0 -464
  89. package/scripts/instrument-check-prose.test.mjs +0 -235
  90. package/scripts/instruments.test.mjs +0 -787
  91. package/scripts/is-cli.test.mjs +0 -99
  92. package/scripts/issue-tracker-prose.test.mjs +0 -71
  93. package/scripts/json.test.mjs +0 -364
  94. package/scripts/ledger-dispatch.test.mjs +0 -927
  95. package/scripts/ledger-grammar.test.mjs +0 -227
  96. package/scripts/ledger-read-require-file.test.mjs +0 -197
  97. package/scripts/ledger-rotate.test.mjs +0 -142
  98. package/scripts/ledger.test.mjs +0 -3436
  99. package/scripts/line-distance-prose.test.mjs +0 -245
  100. package/scripts/liveness-rationale-prose.test.mjs +0 -83
  101. package/scripts/locale-pin-prose.test.mjs +0 -189
  102. package/scripts/main-checkout.test.mjs +0 -332
  103. package/scripts/member-outcome-prose.test.mjs +0 -167
  104. package/scripts/member-outcomes-header.test.mjs +0 -129
  105. package/scripts/member-outcomes-prose.test.mjs +0 -63
  106. package/scripts/member-outcomes.test.mjs +0 -638
  107. package/scripts/member-prompt-prose.test.mjs +0 -165
  108. package/scripts/member-record.test.mjs +0 -541
  109. package/scripts/member-write-guard.test.mjs +0 -214
  110. package/scripts/merge-commit-probe-prose.test.mjs +0 -122
  111. package/scripts/merge-gate.test.mjs +0 -613
  112. package/scripts/muted-git-guard-sweep.test.mjs +0 -493
  113. package/scripts/net-ssh-precedence-prose.test.mjs +0 -91
  114. package/scripts/net-watchdog-prose.test.mjs +0 -79
  115. package/scripts/net.test.mjs +0 -211
  116. package/scripts/no-ci-gate-prose.test.mjs +0 -108
  117. package/scripts/no-undo-audit.test.mjs +0 -3961
  118. package/scripts/no-wave.test.mjs +0 -138
  119. package/scripts/node-floor-sweep.test.mjs +0 -611
  120. package/scripts/pointer-target-prose.test.mjs +0 -186
  121. package/scripts/pr-cost.test.mjs +0 -521
  122. package/scripts/pr-overlap.test.mjs +0 -692
  123. package/scripts/printf-die-sweep.test.mjs +0 -384
  124. package/scripts/prompt-renderer.mjs +0 -40
  125. package/scripts/prompt-renderer.test.mjs +0 -68
  126. package/scripts/prose-pin.mjs +0 -807
  127. package/scripts/prose-pin.test.mjs +0 -1034
  128. package/scripts/prove-merge.test.mjs +0 -995
  129. package/scripts/pull-table-relabel-prose.test.mjs +0 -60
  130. package/scripts/quiet-payload-prose.test.mjs +0 -222
  131. package/scripts/reap-cherry-check-prose.test.mjs +0 -80
  132. package/scripts/reap.test.mjs +0 -4432
  133. package/scripts/reaping-prose.test.mjs +0 -239
  134. package/scripts/reaping-reap-authorizers-prose.test.mjs +0 -112
  135. package/scripts/reaping-release-authorizers-prose.test.mjs +0 -85
  136. package/scripts/recipe-derivation-prose.test.mjs +0 -112
  137. package/scripts/recipe-prove.test.mjs +0 -1042
  138. package/scripts/refuter-scratch-prose.test.mjs +0 -135
  139. package/scripts/release-label-required-prose.test.mjs +0 -71
  140. package/scripts/release-label-split-prose.test.mjs +0 -184
  141. package/scripts/release-ticket-reap-pairing-prose.test.mjs +0 -63
  142. package/scripts/release-ticket.test.mjs +0 -5099
  143. package/scripts/renovate-release-contract.test.mjs +0 -379
  144. package/scripts/repo-root.test.mjs +0 -873
  145. package/scripts/reporter-output-rule-prose.test.mjs +0 -208
  146. package/scripts/review-agent-report-only.test.mjs +0 -49
  147. package/scripts/review-core-booking.test.mjs +0 -35
  148. package/scripts/review-core-cwd-isolation.test.mjs +0 -374
  149. package/scripts/review-core-reads.test.mjs +0 -478
  150. package/scripts/review-core-refuter-scratch.test.mjs +0 -148
  151. package/scripts/review-core-scratch-refusal.test.mjs +0 -64
  152. package/scripts/review-core-shared-test-run.test.mjs +0 -275
  153. package/scripts/review-core-snapshot-path.test.mjs +0 -830
  154. package/scripts/review-core-specialist-scratch.test.mjs +0 -191
  155. package/scripts/review-core-testcmd.test.mjs +0 -335
  156. package/scripts/review-core-unrun.test.mjs +0 -566
  157. package/scripts/review-core-unverified-discriminant.test.mjs +0 -208
  158. package/scripts/review-eval-resolver-path.test.mjs +0 -55
  159. package/scripts/review-host-fixture.mjs +0 -89
  160. package/scripts/review-in-run-retry.test.mjs +0 -211
  161. package/scripts/review-no-vendor-dispatch.test.mjs +0 -45
  162. package/scripts/review-path-default.test.mjs +0 -796
  163. package/scripts/review-runner-spawns.test.mjs +0 -95
  164. package/scripts/review-runner.test.mjs +0 -166
  165. package/scripts/review-tier-audit.test.mjs +0 -140
  166. package/scripts/run-artifact-pr-prose.test.mjs +0 -341
  167. package/scripts/run-merge-bot-prose.test.mjs +0 -1413
  168. package/scripts/run-team-local-hook.test.mjs +0 -442
  169. package/scripts/scratch-partition-invariant-prose.test.mjs +0 -74
  170. package/scripts/scripts-path-citation-sweep.test.mjs +0 -73
  171. package/scripts/section-between-guard-prose.test.mjs +0 -379
  172. package/scripts/select-dimensions.test.mjs +0 -674
  173. package/scripts/shared-refusal.test.mjs +0 -388
  174. package/scripts/shell-traps-prose.test.mjs +0 -504
  175. package/scripts/shortlist.test.mjs +0 -380
  176. package/scripts/slow-transport.mjs +0 -72
  177. package/scripts/snapshot-repo.test.mjs +0 -1006
  178. package/scripts/snapshot-runner-audience-prose.test.mjs +0 -130
  179. package/scripts/spend-view.test.mjs +0 -312
  180. package/scripts/staleness-qualifier-prose.test.mjs +0 -251
  181. package/scripts/staleness-verdict-prose.test.mjs +0 -142
  182. package/scripts/staleness.test.mjs +0 -893
  183. package/scripts/stalled-member-liveness-prose.test.mjs +0 -219
  184. package/scripts/stash-prohibition-prose.test.mjs +0 -313
  185. package/scripts/strip-comments.mjs +0 -44
  186. package/scripts/temp-dir.mjs +0 -47
  187. package/scripts/ticket-router.test.mjs +0 -981
  188. package/scripts/tier-check.test.mjs +0 -828
  189. package/scripts/tier-outcomes-header.test.mjs +0 -518
  190. package/scripts/tier-outcomes.test.mjs +0 -572
  191. package/scripts/tier-roles.test.mjs +0 -535
  192. package/scripts/tracker-block-copy-prose.test.mjs +0 -288
  193. package/scripts/triage-labels-gloss-prose.test.mjs +0 -97
  194. package/scripts/unattended-git-sweep.test.mjs +0 -142
  195. package/scripts/verify-sha-exit2-prose.test.mjs +0 -269
  196. package/scripts/verify-sha.test.mjs +0 -692
  197. package/scripts/watcher-degraded-block.test.mjs +0 -369
  198. package/scripts/watcher-key-prose.test.mjs +0 -106
  199. package/scripts/within-run-pair-prose.test.mjs +0 -212
  200. package/scripts/worktree-audit.test.mjs +0 -1408
  201. package/scripts/worktree-head-prose.test.mjs +0 -276
  202. package/scripts/worktree-listing-sweep.test.mjs +0 -217
  203. package/scripts/worktree-model-prose.test.mjs +0 -216
  204. package/scripts/worktree-porcelain.mjs +0 -35
  205. package/scripts/worktree-porcelain.test.mjs +0 -102
@@ -1,807 +0,0 @@
1
- // THE PIN CONVENTION (#491), for every new prose pin in this directory.
2
- // Existing pins move onto it only where a hole in them is measured.
3
- //
4
- // A pin holding a claim asserts ONE contiguous `phrase()` span: the smallest
5
- // clause that makes the claim, never independent keywords. Keywords each
6
- // satisfied somewhere in the slice stay green when the sentence carrying them
7
- // is gutted and its words restated beside it with the meaning inverted: the
8
- // slice bounds WHERE the words are, only a span binds them to each other.
9
- // Measured on ci-state-prose.test.mjs, where three independent checks (two
10
- // regexes and a substring match) stayed green
11
- // under exactly that restatement inside the pinned paragraph. A literal the
12
- // source owns (a reason string read out of the script) may be interpolated
13
- // into the span, so renaming it there reddens the pin too.
14
- //
15
- // A reflow stays green, since `phrase()` joins words on `\s+`; so does a `**`
16
- // move, where the slice is matched through `unemphasized()`. A reword inside
17
- // the span goes red, and that is accepted as the loud direction: the assertion
18
- // message names what the span protects, so whoever rewords it re-pins
19
- // deliberately. `sentences()` may locate a sentence; it does not replace the
20
- // span.
21
- //
22
- // THE CEILING: a negating sentence added beside an intact span stays green.
23
- // No tighter regex closes that; it is the limit of pinning prose by matching it.
24
- //
25
- // A list item is sliced with `bullet()`, never with a bare `between()` on a
26
- // fixed end anchor, for the same reason one level up: every sibling item
27
- // inserted between the anchors joins that slice and can carry the span the
28
- // real item lost.
29
-
30
- import assert from "node:assert/strict";
31
-
32
- // How many times `needle` occurs in `haystack`, overlaps included — two
33
- // overlapping hits are two places a slice could start, which is exactly the
34
- // ambiguity the caller below refuses. A count, not the offsets: the caller
35
- // needs only "more than one" and the number to say so with. Cursor-bounded
36
- // rather than chained off the previous hit, so an anchor that strips to ""
37
- // terminates instead of spinning on `indexOf("", i)`'s clamped return.
38
- function occurrenceCount(haystack, needle) {
39
- let n = 0;
40
- for (let i = 0; i <= haystack.length; ) {
41
- const hit = haystack.indexOf(needle, i);
42
- if (hit === -1) break;
43
- n += 1;
44
- i = hit + 1;
45
- }
46
- return n;
47
- }
48
-
49
- // Bound at BOTH ends: an unbounded end lets a later, unrelated occurrence of the
50
- // same phrase satisfy the assertion with the real clause deleted.
51
- //
52
- // `emphasisTolerant` mirrors the option `anchorAt` and `quoteBlock` already
53
- // carry — same name, same default of off — and reuses their `unemphasized`/
54
- // `rawOffset` pair rather than carrying a second stripper. On, BOTH the anchors
55
- // and the document are read through `unemphasized`, so `**` may be removed,
56
- // added, narrowed, widened, or moved to another word boundary anywhere inside
57
- // an anchor without moving the slice. Stripping the ANCHOR too is what
58
- // `anchorAt`'s own tolerant mode does not do, and is the direction this family
59
- // needs: its anchors are typed WITH `**` when the source is, so a document that
60
- // loses the emphasis is the common break.
61
- //
62
- // BOTH anchors must then resolve EXACTLY ONCE when tolerant — the standard
63
- // `anchorAt` and `quoteBlock` already hold for their one anchor, and the price
64
- // of tolerance here, paid at both ends alike (`occurrenceCount` below is
65
- // shared by both guards). Stripping `**` can only ADD matches to a search over
66
- // the stripped view, never remove one the literal anchor had, so a tolerant
67
- // anchor can resolve somewhere the literal one never could: on a text-identical
68
- // phrase sitting in a different emphasis state elsewhere in the document, or —
69
- // when an anchor literal itself carries a `*` run that does not collapse to a
70
- // clean `**`-pair count — on a shorter, less specific phrase the literal anchor
71
- // never matched at all, which can make a tolerant match genuinely WIDER than
72
- // the literal one, not merely earlier. Either direction is invisible to every
73
- // assertion inside the slice: at the START, the pinned words are all present,
74
- // sourced from the wrong copy; at the END, a slice that lands short silently
75
- // DELETES content, which can flip a `doesNotMatch` pin from correctly RED to
76
- // falsely GREEN — the same false-green class a wrong START does, just reached
77
- // from the other side. Both throw instead, for the reason a missing anchor
78
- // throws rather than widening to the whole file.
79
- //
80
- // Only the TOLERANT path pays that price. The literal path's END anchor keeps
81
- // first-hit-after-the-start and stays non-unique ON PURPOSE — an end bound's
82
- // job there is to be the next one, not the only one — and two of this
83
- // directory's real end anchors depend on exactly that:
84
- // `snapshot-runner-audience-prose.test.mjs`'s `"\n- **"` means "wherever the
85
- // next bullet starts", and `instrument-check-prose.test.mjs`'s `"**Exit 0 is
86
- // the only code"` names a sentence `run-team/SKILL.md` states twice, once bold
87
- // and once inside a blockquote. Neither callsite turns `emphasisTolerant` on,
88
- // so the guard above never sees them; an exactly-once literal-mode end bound
89
- // would refuse both while preventing no widening that exists today.
90
- //
91
- // Matching stays a literal `indexOf` over the stripped view, NOT `phrase()` as
92
- // `anchorAt` uses: #1492's own ticket measured that trade. `phrase()` is
93
- // `s.trim().split(/\s+/)`, which discards a leading newline — and `between`
94
- // anchors carry load-bearing ones, e.g. `fix-applier-correction-rules-prose
95
- // .test.mjs`'s `PROMPT_END`, `"\n**Put the standing CI facts"`: the leading
96
- // `\n` is what ties that anchor to the phrase's own line start rather than to
97
- // any mid-line occurrence of the same words. `phrase()`'s `.trim()` would
98
- // strip that newline before matching, silently loosening the anchor. A
99
- // tolerant mode built on `phrase()` would trade this family's false reds for
100
- // that false green. Emphasis tolerance and whitespace tolerance are separate
101
- // axes; this option moves only the first.
102
- //
103
- // The returned slice is raw bytes with `**` intact — `rawOffset` maps each
104
- // endpoint back and stops BEFORE the marker, so a tolerant slice keeps the
105
- // emphasis its caller goes on to compare.
106
- export function between(text, from, to, what, { emphasisTolerant = false } = {}) {
107
- const haystack = emphasisTolerant ? unemphasized(text) : text;
108
- const start = emphasisTolerant ? unemphasized(from) : from;
109
- const stop = emphasisTolerant ? unemphasized(to) : to;
110
- const at = haystack.indexOf(start);
111
- assert.notEqual(at, -1, `${what} no longer contains "${from}" — update this test`);
112
- if (emphasisTolerant) {
113
- const hits = occurrenceCount(haystack, start);
114
- assert.equal(
115
- hits,
116
- 1,
117
- `${what}: emphasis-tolerant slice anchor "${from}" occurs ${hits} times once \`**\` is ignored — the slice would start at the first and pull in what the literal anchor excluded; narrow the anchor or drop emphasisTolerant`,
118
- );
119
- }
120
- const searchFrom = at + start.length;
121
- const end = haystack.indexOf(stop, searchFrom);
122
- assert.notEqual(end, -1, `${what} no longer contains "${to}" after "${from}" — update this test`);
123
- if (emphasisTolerant) {
124
- const hits = occurrenceCount(haystack.slice(searchFrom), stop);
125
- assert.equal(
126
- hits,
127
- 1,
128
- `${what}: emphasis-tolerant slice end anchor "${to}" occurs ${hits} times after the start once \`**\` is ignored — the slice would end at the first and could drop or admit content the literal anchor did not; narrow the anchor or drop emphasisTolerant`,
129
- );
130
- }
131
- return emphasisTolerant ? text.slice(rawOffset(text, at), rawOffset(text, end)) : text.slice(at, end);
132
- }
133
-
134
- // Regex metacharacters escaped so a caller's literal stays a literal. One
135
- // definition because both consumers below take arbitrary caller text — a
136
- // second copy of this class is how the two drift apart.
137
- const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
138
-
139
- // `\s+` between every word, never a literal space — prose this matches against
140
- // is often hard-wrapped, so any inter-word space in the source may be a
141
- // newline plus indent. Regex metacharacters in the phrase are escaped first.
142
- export const phrase = (s) => new RegExp(s.trim().split(/\s+/).map(escapeRe).join("\\s+"));
143
-
144
- // The paragraph carrying a rule, and no more of the document than that. A
145
- // positive regex matched over a whole file is satisfiable from OUTSIDE the
146
- // clause it guards — a stray copy of the wording left anywhere else buys the
147
- // pass — so a prose pin's slice bound is the pin, and the regex is the easy
148
- // half. Ends at the blank line, because a paragraph boundary is the one
149
- // bound a rewrap cannot move; the ANCHOR goes through `phrase()` for the
150
- // mirror-image reason, since `between`'s literal `indexOf` would break on a
151
- // rewrap the pinned clause itself survives, turning a reflow into a red.
152
- // A missing anchor throws rather than widening: silently falling back to the
153
- // whole document is the false green this bound exists to prevent.
154
- //
155
- // The blank line is matched as `\n[ \t]*\n`, never the literal `\n\n`: an
156
- // editor that keeps a list item's indent on the line between two paragraphs
157
- // writes `\n \n`, which a literal search does not see — the slice then
158
- // widens silently into the next paragraph, and a decoy there buys the green
159
- // this bound exists to deny. No `*.md` in this repo carries a whitespace-only
160
- // line today and nothing enforces that — no `.editorconfig`, no prettier or
161
- // markdownlint config, no CI check — and every paragraph pinned so far is
162
- // indented list content, which is exactly where an editor produces that shape.
163
- //
164
- // The anchor must match EXACTLY ONCE — see `anchorAt`, which holds that half.
165
- //
166
- // The single definition of a paragraph bound in this directory. It was
167
- // extracted (#823) while pins elsewhere still hand-rolled this same
168
- // search-to-blank-line slicer locally, every copy carrying both false greens
169
- // above by construction; #1372 migrated them onto it. A pin needing this bound
170
- // imports it — a local copy is the defect, not a style choice.
171
- export function paragraph(text, anchor, what, options) {
172
- const rest = text.slice(anchorAt(text, anchor, what, options));
173
- const end = rest.search(/\n[ \t]*\n/);
174
- return end === -1 ? rest : rest.slice(0, end);
175
- }
176
-
177
- // One list item: from `from` to where markdown ends the item, and never past
178
- // `to`. `between` alone on a fixed end anchor takes every item between the two
179
- // anchors, so a sibling inserted there joins the slice and carries a pin the
180
- // real item lost. Measured on run-team's `no-ci` edge (#747, #491): the ruling
181
- // clause gutted, then restated in an inserted sibling bullet, stayed green. `to`
182
- // stays as the outer bound and as the "moved — update this test" tripwire
183
- // `between` already raises.
184
- //
185
- // A line belongs to the item only if it is indented to the item's CONTENT
186
- // column — past the marker and the gap after it, CommonMark's rule — or is a
187
- // lazy continuation: a plain line straight after the item's text, which
188
- // markdown renders inside the item's paragraph. A shallower line ends the item
189
- // when it opens a list marker (a sibling, whatever its marker: `-`, `*`, `+`,
190
- // `1.`, `1)`), when it opens a block that interrupts a paragraph (an ATX
191
- // heading, `>`, a fence, a thematic break — not an HTML block, which CommonMark
192
- // also lets interrupt one: a shallower `<div>`, `</div>`, `<!--`, `<script>`,
193
- // `<?` or `<!DOCTYPE` line ends the item in CommonMark, yet this reads it as
194
- // lazy and keeps it; a `<span>`-style line interrupts in neither), or when a
195
- // blank line precedes it.
196
- // Only the first ended it before #2077, so a restatement in a paragraph after
197
- // the item, or under a new heading, stayed inside the slice and held the pin.
198
- // The marker and interrupt cases count only short of the item's MARKER column
199
- // + 4: from there on, with no blank line before it, the line is lazy
200
- // continuation, since 4+ columns past its container a line cannot open a block
201
- // or a list item and indented code cannot interrupt a paragraph. That zone
202
- // exists only when the content column is past marker column + 4 — a `100.`
203
- // marker, or a 4-space gap (#2100); a blank line still ends the item there.
204
- // Not modelled: which block the previous line was, so a shallower plain line
205
- // straight after the item's own heading, fence, thematic break, indented code
206
- // or HTML block — none of them a paragraph a lazy line could continue — reads
207
- // as lazy and stays in; so does a shallower line inside the item's own
208
- // still-open fence, where CommonMark ends the fence and the item both; and so
209
- // does any shallower line at marker column + 4 or deeper in that zone.
210
- // Nor the parent's content column: marker column + 4 stands in for it + 4,
211
- // exact while the marker sits AT that column, as in any normal list. A marker
212
- // indented 1-3 columns past it (` 100. **Item**` at top level) still ends
213
- // the item at a heading or marker line CommonMark reads as lazy.
214
- //
215
- // Columns are visual, a tab advancing to the next multiple of 4 (CommonMark's
216
- // tab stop): counted in characters, a one-tab item read a two-space sibling as
217
- // a deeper child (#2077). The item's line is the one `from`'s first
218
- // non-whitespace character sits on, and the walk starts after `from`'s trailing
219
- // whitespace, so a leading-`\n` anchor — load-bearing in `between` — measures
220
- // its own line and not the one before it, and a trailing-`\n` anchor does not
221
- // eat the line break the next line's check needs (#2077). `from` must occur
222
- // exactly once: a list-item anchor is a start anchor, and a second copy would
223
- // silently decide which item is read.
224
- //
225
- // Returns raw bytes starting with `from` in full, like `between`. When a line
226
- // of the text ends the item, the blank lines before that line are dropped;
227
- // when `to` ends it, the slice comes back as `between` gives it, trailing blank
228
- // lines and all (run-team's no-ci edge ends in `\n\n`). A caller flattens or
229
- // matches through `phrase()`.
230
- //
231
- // The single definition of a list-item bound in this directory (#491), moved
232
- // out of no-ci-gate-prose.test.mjs, where #747 had clamped a local copy.
233
- export function bullet(text, from, to, what) {
234
- const slice = between(text, from, to, what);
235
- const hits = occurrenceCount(text, from);
236
- assert.equal(hits, 1, `${what}: list-item anchor "${from}" occurs ${hits} times — the item would be read off the first copy; narrow the anchor`);
237
- const at = text.indexOf(from) + (from.length - from.trimStart().length);
238
- const lineStart = text.lastIndexOf("\n", at - 1) + 1;
239
- const lineEnd = text.indexOf("\n", at);
240
- const itemLine = text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd);
241
- const content = contentColumn(itemLine);
242
- const lazyFrom = columnOf(itemLine.match(/^[ \t]*/)[0]) + 4;
243
- let kept = slice.indexOf("\n", from.trimEnd().length);
244
- let blankBefore = false;
245
- for (let nl = kept; nl !== -1; ) {
246
- const next = slice.indexOf("\n", nl + 1);
247
- const line = slice.slice(nl + 1, next === -1 ? slice.length : next);
248
- const indent = line.match(/^[ \t]*/)[0];
249
- const col = columnOf(indent);
250
- if (indent.length === line.length) {
251
- blankBefore = true;
252
- } else if (col < content && (blankBefore || (col < lazyFrom && (ITEM_MARKER.test(line) || PARAGRAPH_INTERRUPT.test(line))))) {
253
- return slice.slice(0, Math.max(kept, from.length));
254
- } else {
255
- blankBefore = false;
256
- kept = next;
257
- }
258
- nl = next;
259
- }
260
- return slice;
261
- }
262
-
263
- // Visual width of leading whitespace, a tab advancing to the next multiple of 4.
264
- function columnOf(whitespace) {
265
- let col = 0;
266
- for (const c of whitespace) col = c === "\t" ? col + 4 - (col % 4) : col + 1;
267
- return col;
268
- }
269
-
270
- // Where a list item's text starts: past the marker and its gap, or one column
271
- // past the marker when the gap is over 4 (the rest is an indented code block).
272
- // A line with no marker has no content column of its own, so anything deeper
273
- // than its indent counts as its child.
274
- function contentColumn(line) {
275
- const item = line.match(/^([ \t]*(?:[-*+]|\d+[.)]))([ \t]+)/);
276
- if (!item) return columnOf(line.match(/^[ \t]*/)[0]) + 1;
277
- const marker = columnOf(item[1]);
278
- const gap = columnOf(item[1] + item[2]) - marker;
279
- return gap > 4 ? marker + 1 : marker + gap;
280
- }
281
-
282
- // A marker with nothing after it on its own line (content on the next,
283
- // indented line) is still a valid, separate list item — `(?:[ \t]|$)`, not
284
- // only `[ \t]`, so a bare `-`/`2.` sibling is recognised too. Reviewed PR
285
- // #2091, hand-dispatched review: `bullet('- **A** body\n-\n restated
286
- // claim\nEND','- **A**','END')` kept the bare-marker sibling inside the
287
- // slice under the narrower form — the same #747/#2077 escape this bound
288
- // exists to close, just via a marker shape the sibling regex didn't cover.
289
- const ITEM_MARKER = /^[ \t]*(?:[-*+]|\d+[.)])(?:[ \t]|$)/;
290
- // A thematic break may space its repeated character out (`- - -`, `_ _ _`,
291
- // `* * *`), not only run it together — CommonMark's own rule. The `_`/`*`
292
- // forms have no marker regex to fall back on (unlike `-`, which ITEM_MARKER
293
- // already catches), so an unspaced-only rule here missed them. Same review.
294
- const PARAGRAPH_INTERRUPT = /^[ \t]*(?:#{1,6}(?:[ \t]|$)|>|```|~~~|(?:-[ \t]*){3,}$|(?:\*[ \t]*){3,}$|(?:_[ \t]*){3,}$)/;
295
-
296
- // Prose cut into sentences, for a pin that holds a claim to ONE sentence. A
297
- // sentence ends at `.`, `!` or `?` followed by whitespace, with any closing
298
- // marks between the two — `.**`, `.)`, `."` — so a bold lead-in, a
299
- // parenthetical sentence or a quoted one ends where its reader sees it end.
300
- // Without them a pinned sentence runs on into whatever follows a bold one, a
301
- // shape run-team's SKILL.md opens paragraphs with throughout (#1940). A
302
- // backtick is not one: a code span ending in punctuation (`git restore .`,
303
- // `runSubprocess(...)`) sits mid-sentence far more often than it ends one.
304
- //
305
- // A period closing an abbreviation that never ends a sentence — "e.g.",
306
- // "i.e.", "cf.", "viz.", "vs." — is no break, closing marks or not ("e.g.)"):
307
- // splitting there scattered one sentence's words across two fragments, neither
308
- // of which satisfied the pin, so a paraphrase using one was refused (#1852).
309
- // "etc." is deliberately absent: it ends sentences as often as not, and reading
310
- // past it would join two real sentences. A period inside a word ("ci.yml",
311
- // "v1.2") is no break either, since no whitespace follows it.
312
- //
313
- // Only a letter or digit right before the abbreviation disqualifies it, so an
314
- // italic `_e.g._` is one (#2053). A `\b` there read the `_` as a word
315
- // character, so the period split the sentence mid-abbreviation — the same gap
316
- // #2021/#2043 closed in citation-sweep's SENTENCE_END and jsonCountFault's
317
- // re-split, whose guard this now matches. Running first does not make the
318
- // narrower guard moot for a caller that re-splits a slice: a re-split can only
319
- // cut a piece further, never rejoin two this function wrongly parted. The
320
- // cost: a bare snake_case word ending in any of the five — `_vs.`, `_cf.`,
321
- // `_viz.`, `_e.g.`, `_i.e.` — at a sentence's real end now joins the next
322
- // one, the same underscore-adjacency this fix widens the guard to accept.
323
- // Measured over every tracked .md/.mjs/.yml/.sh/
324
- // .json file, the widening moved no split but three in fixtures of those two
325
- // sibling fixes, each an italic abbreviation.
326
- //
327
- // The abbreviations match lowercase only, as this repo's prose spells every
328
- // one of them (#1899). Folded case, a sentence genuinely ending in a word
329
- // that merely shares their letters — a proper noun "Vs.", a stray "E.g." —
330
- // read as the abbreviation and joined the sentence after it, the same silent
331
- // merge "etc." is kept off the list to avoid. The cost runs the other way: a
332
- // capitalized one anywhere — a sentence OPENING "E.g. …", a parenthetical
333
- // "(Cf. …)" mid-sentence — now ends the sentence right there, not only at a
334
- // sentence's own start. No file's PROSE spells any of the five capitalized,
335
- // outside this ticket's own fixtures illustrating the defect (#1899 grepped
336
- // the corpus).
337
- //
338
- // This replaces the first-period `[^.]*` scan (#1898, #1940), which is wrong
339
- // both ways at once: it ends the window at every period above, and it runs
340
- // straight past a `?` or `!` into the next sentence. Which of the two is the
341
- // SILENT direction depends on the pin. For one that requires something to be
342
- // IN the sentence, a window cut short reds on a valid rewording and a window
343
- // run long lets a neighbour supply what the sentence lacks; for one that checks
344
- // everything the sentence holds — citationFault's quoted spans — the two swap.
345
- // So a boundary this function misjudges is silent for some caller whichever
346
- // way it errs, and the calls above are the ones prose makes far more often
347
- // than not. Two it gets wrong: a bolded or quoted question used mid-sentence
348
- // as a name (`judge **decided?** — …`) splits, as a bare `?` always has; and a
349
- // whole sentence in parentheses mid-sentence ends the outer one at its `.)`.
350
- //
351
- // One definition, extracted (#1940) from ci-comment-rot-prose.test.mjs, where
352
- // it bounded ci.yml's comment prose alone — the same reason `paragraph()`
353
- // gives: a local copy is the defect, not a style choice.
354
- // The closing-mark class `[*_)"'\u201d\u2019]*` appears once, not twice: it
355
- // used to be spelled again inside the abbreviation guard's own lookbehind,
356
- // two copies of the same set free to drift apart on a future edit. Nesting
357
- // the abbreviation check onto the `.` alternative alone (never `!`/`?`, which
358
- // no abbreviation ends in) keeps the same splits with one copy (verified:
359
- // 20000 random terminator/closer/abbreviation fixtures and every .md/.mjs/
360
- // .yml/.sh file in this repo split identically both ways).
361
- //
362
- // A footnote-style marker straight behind the terminator — `.[1]`, `?[^2]`,
363
- // `.[1][2]`, closing marks allowed after it — is part of the sentence it
364
- // annotates, and the end falls after it (#1987). Without it a `.[1]` ended
365
- // nothing, so two real sentences merged: the silent direction for a pin that
366
- // needs a word IN its sentence, which could borrow it from the next one. The
367
- // marker holds at least one character and no whitespace, and must follow a
368
- // terminator that closes a word, a digit, a code span, a paren or a curly
369
- // quote. A word here is a letter in any script, combining marks on it
370
- // included (#2041): an NFD "é" is `e` + U+0301 and Devanagari "हिंदी" ends in
371
- // the vowel sign U+0940, so a word's last code point can be a mark, and the
372
- // guard reads past any run of them to whichever of the five bases above sits
373
- // under it. A mark with no accepted base under it closes nothing. Code quoted
374
- // in prose puts brackets straight after a period too, with whitespace after
375
- // them — jq's
376
- // `'.[] | …'`, JavaScript's `m?.[1] || …`,
377
- // a glob's `*.[0-9]*' ` — behind a quote, a `?`, a `*` or a space, and jq's
378
- // `.jobs.[] | …` or `.jobs.[0, 1] | …` behind a word, with an empty or
379
- // comma-spaced bracket. Measured over every tracked .md/.mjs/.yml/.sh/.json
380
- // file: a bare `\[[^\]]*\]` after the terminator split 15 such code spots,
381
- // and this rule none — its one new split is a real footnote, `only.[^1] `,
382
- // in a citation-sweep fixture. Three shapes are known and left unfixed,
383
- // none of them occurring in that same corpus today: a marker behind bold
384
- // or italics (`**late**.[1]`) still merges, same as before; so does one
385
- // behind a closing quote or paren that itself follows the terminator
386
- // (`"stop."[1]`, `(noon.)[1]`) — the guard only tolerates closing marks
387
- // AFTER the bracket run, not before it; and a single, unspaced jq index
388
- // straight behind a word (`.jobs.[0] | …`) is the same shape as a real
389
- // marker at the regex level, so it still splits — wrongly, the direction
390
- // this rule exists to avoid.
391
- export const sentences = (block) =>
392
- block.split(/(?<=(?:[!?]|(?<!(?<![A-Za-z\d])(?:e\.g|i\.e|cf|viz|vs))\.)(?:(?<=[\p{L}\p{N}`)\u201d\u2019]\p{M}*[.!?])(?:\[[^\]\s]+\])+)?[*_)"'\u201d\u2019]*)\s+/u);
393
-
394
- // A phrase-bounded slice — `paragraph`'s shape, with the end bound a second
395
- // phrase instead of the next blank line. `from` is `anchorAt`'s own
396
- // exactly-once anchor; `to` is a phrase asserted exactly once inside the
397
- // optional `bound` — a regex searched for in the text after `from`, so the
398
- // search for `to` stops there rather than reaching the end of the document.
399
- // Without `bound`, `to` is searched over the rest of the document, the same
400
- // reach as an unbounded `between`.
401
- //
402
- // `bound` exists for the reason `between`'s own header gives for its literal
403
- // end anchor, applied to a phrase search instead of `indexOf`: an unbounded
404
- // search for `to` is satisfiable from a LATER, unrelated occurrence once the
405
- // true `to` is reworded away, silently widening the slice into whatever
406
- // follows. A `bound` that excludes any such later occurrence turns that
407
- // silent widening into a throw: the exactly-once assert below then sees
408
- // zero hits inside the bound, never one from past it.
409
- //
410
- // `to`'s "occurs more than once" assert is scoped to `bound` too, not the
411
- // whole rest of the document — a restatement of `to` PAST the bound must
412
- // not count, or a pin could never pass once any later, unrelated copy of
413
- // the same phrase exists anywhere below it.
414
- //
415
- // A bound can also match BEFORE an intact `to` — e.g. a reflow that puts
416
- // `3.` at column 0 mid-step, which the `\n\d+\.\s` list-item bound reads as the
417
- // next item, and CommonMark renders as one too, so the red is real. Reporting
418
- // that as `to` having "moved" sends the reader after an edit to an anchor
419
- // nobody touched, so a zero-hit scope looks past the cut before choosing the
420
- // message: a `to` still found there names the line the bound first matched
421
- // instead. That also covers a `to` reworded away with a later copy left past
422
- // the bound — the helper cannot tell the two apart, so the message names both.
423
- // A `to` found nowhere after `from` keeps "moved". Every one of these throws;
424
- // only which message a red carries changes.
425
- //
426
- // The line named is the one the bound's match starts on, past one leading
427
- // `\n` the match itself consumed — that newline terminates the text before
428
- // the match, which is how a bound says "at the start of a line". Only one: a
429
- // blank-line bound (`\n\n`, `\n\s*\n`, a zero-width `^$` with `m`) names the
430
- // blank line it matched, never the next paragraph's text past it (#2268).
431
- //
432
- // Extracted (#1611) from `finisher-dispatch-premise-prose.test.mjs`'s
433
- // `dispatchPremise`, which hand-rolled this exact shape locally — `paragraph`'s
434
- // own header above names the class: a local copy is the defect, not a style
435
- // choice.
436
- export function betweenPhrases(text, from, to, what, { bound } = {}) {
437
- const at = anchorAt(text, from, what);
438
- const rest = text.slice(at);
439
- const toPhrase = phrase(to);
440
- let scope = rest;
441
- let boundEnd = -1;
442
- let boundLead = 0;
443
- if (bound) {
444
- // `exec` rather than `search` for the match text too; a copy without `g`
445
- // so it starts at index 0 the way `search` does.
446
- const boundMatch = new RegExp(bound, bound.flags.replace("g", "")).exec(rest);
447
- boundEnd = boundMatch ? boundMatch.index : -1;
448
- boundLead = boundMatch?.[0].startsWith("\n") ? 1 : 0;
449
- assert.notEqual(
450
- boundEnd,
451
- -1,
452
- `${what}: end bound no longer matches after "${from}" — re-anchor this test, never widen it to the whole document`,
453
- );
454
- scope = rest.slice(0, boundEnd);
455
- }
456
- const hits = [...scope.matchAll(new RegExp(toPhrase.source, "g"))];
457
- // Zero hits inside the bound but one in `rest` means that hit ends past the
458
- // cut — a hit ending inside it would have matched `scope` — so this also
459
- // catches a bound that cuts through the middle of `to`.
460
- if (hits.length === 0 && bound && toPhrase.test(rest)) {
461
- const cut = at + boundEnd + boundLead;
462
- const lineStart = text.lastIndexOf("\n", cut - 1) + 1;
463
- const lineEnd = text.indexOf("\n", cut);
464
- const line = text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd);
465
- const excerpt = line.length > 72 ? `${line.slice(0, 72)}…` : line;
466
- const lineNo = text.slice(0, lineStart).split("\n").length;
467
- assert.fail(
468
- `${what}: slice end anchor "${to}" lies past the end bound, which first matched at line ${lineNo} ("${excerpt}") — an edit put a block boundary inside the slice, or reworded the anchor away and left a later copy past the bound; fix whichever it is, never widen the bound`,
469
- );
470
- }
471
- assert.notEqual(
472
- hits.length,
473
- 0,
474
- `${what}: slice end anchor "${to}" moved — re-anchor this test, never widen it to the whole file`,
475
- );
476
- assert.equal(
477
- hits.length,
478
- 1,
479
- bound
480
- ? `${what}: slice end anchor "${to}" occurs ${hits.length} times inside the bound — a pin would bind the wrong copy; narrow the anchor`
481
- : `${what}: slice end anchor "${to}" occurs ${hits.length} times — a pin would bind the wrong copy; narrow the anchor`,
482
- );
483
- return scope.slice(0, hits[0].index);
484
- }
485
-
486
- // Anchor matching only — never the compared text, so a caller that turns this
487
- // on still returns raw bytes with emphasis intact. Exported so a pin comparing
488
- // two files' copies of the same block (`**` moving on one side is real drift)
489
- // does not hand-roll a second definition to locate the block it is comparing.
490
- export const unemphasized = (s) => s.replace(/\*\*/g, "");
491
-
492
- // Maps an offset found in `unemphasized(text)` back to `text`, stopping before
493
- // any `**` at that point rather than after it — so a slice starting there
494
- // keeps the marker instead of silently dropping it from the raw bytes a
495
- // caller goes on to compare or substring-replace.
496
- function rawOffset(text, unemphasizedOffset) {
497
- let seen = 0;
498
- let i = 0;
499
- while (seen < unemphasizedOffset) {
500
- if (text.startsWith("**", i)) i += 2;
501
- else {
502
- seen += 1;
503
- i += 1;
504
- }
505
- }
506
- return i;
507
- }
508
-
509
- // The offset of an anchor that must occur EXACTLY ONCE, asserted by count because
510
- // a search takes the FIRST match silently, so an un-gutter'd restatement of the
511
- // anchored block ABOVE the real one — the shape this repo's prose already uses
512
- // where a phase quotes a member prompt back at itself — binds the pin to the copy
513
- // while the real rule is gutted. A blockquoted copy is harmless (`\s+` cannot
514
- // span the `>` gutter); a plain one is not. A missing anchor throws rather than
515
- // widening, for `paragraph`'s reason.
516
- //
517
- // Split out of `paragraph` rather than left inside it because a slice whose END
518
- // bound is not a blank line needs the same guarantee and must not copy it:
519
- // `runAbove` below anchors on a declaration and takes the comment block ABOVE
520
- // it, bounded by code at both ends, and imports this half rather than
521
- // re-deriving it.
522
- // `emphasisTolerant` is opt-in and off by default: most anchors here are
523
- // typed WITH `**` when the source is (see e.g. `ancestry-check-position-prose
524
- // .test.mjs`), so matching against `unemphasized(text)` unconditionally would
525
- // break every anchor that itself carries emphasis. On, it lets an anchor
526
- // typed WITHOUT `**` still find its target after a meaning-preserving
527
- // emphasis move on the matched words — measured need in
528
- // `tracker-block-copy-prose.test.mjs`, where the opener anchor has none.
529
- export function anchorAt(text, anchor, what, { emphasisTolerant = false } = {}) {
530
- const haystack = emphasisTolerant ? unemphasized(text) : text;
531
- const hits = [...haystack.matchAll(new RegExp(phrase(anchor).source, "g"))];
532
- assert.notEqual(hits.length, 0, `${what}: slice anchor "${anchor}" moved — re-anchor this test, never widen it to the whole file`);
533
- assert.equal(hits.length, 1, `${what}: slice anchor "${anchor}" occurs ${hits.length} times — a pin would bind the wrong copy; narrow the anchor`);
534
- return emphasisTolerant ? rawOffset(text, hits[0].index) : hits[0].index;
535
- }
536
-
537
- // The comment run immediately ABOVE a declaration, gutter intact, bounded by
538
- // CODE at both ends. The bound `paragraph` cannot give a SOURCE file: there the
539
- // blank line after a comment block sits below the code the block documents, so
540
- // a blank-line slice runs past the prose into live code and a decoy pasted
541
- // there takes the pin green (measured #695). Anchoring on the declaration
542
- // instead puts code at both ends, so no edit to the prose the slice holds can
543
- // move either bound — which is the whole reason a pin over source prose gets to
544
- // be a slice at all rather than a search of the file.
545
- //
546
- // `marker` is the gutter literal (`#` for shell, `//` for `.mjs`), matched only
547
- // as a line's FIRST token after indent: a `//` inside a string on a code line
548
- // does not extend the run, which is what keeps "bounded by code" true rather
549
- // than merely stated. It is escaped, so a `*` continuation gutter cannot turn
550
- // the run into `.*` and swallow every line above the anchor. No
551
- // `emphasisTolerant` pass-through, unlike `paragraph`: `**` is markdown
552
- // emphasis, and every anchor this bound takes is a declaration in source.
553
- //
554
- // Returns "" rather than throwing when nothing but code sits above the anchor,
555
- // because its callers diagnose that differently and both are right:
556
- // `gp-sep-invariant-prose.test.mjs` slices at module load and wants the empty
557
- // case as a NAMED test rather than an import-time crash, while
558
- // `ed9f2967^:plugin/scripts/review-pr-inbound-citation-prose.test.mjs` asserted
559
- // non-empty on the spot.
560
- // The exactly-once half is not the caller's and is not optional: it is
561
- // `anchorAt`'s, so a second copy of the anchored declaration reds here instead
562
- // of silently binding the pin to whichever copy comes first.
563
- //
564
- // The one thing this closes that all three hand-rolled copies had open: an
565
- // INDENTED anchor. Each copy ended its run at `$`, so a declaration inside a
566
- // function body — the text above it ending in the anchor's own indent, not a
567
- // newline — matched nothing and handed back "" with the comment sitting right
568
- // there, which reads as "the block is gone" and names the wrong fault. The
569
- // tolerated gap is `[ \t]*` and nothing else, so it cannot widen: no code can
570
- // hide in horizontal whitespace, the run itself is still returned without that
571
- // indent, and all three migrated anchors sit at column 0 today, so the bytes
572
- // they get back are unchanged.
573
- //
574
- // #1622: a SAME-LINE keyword prefix needed the same fix as the indent did.
575
- // `export const TARGET` anchored on `const TARGET` left `"export "` — not
576
- // whitespace — at the tail, so `[ \t]*$` could not match either, and the run
577
- // above came back "" while the comment sat right there, the identical wrong
578
- // fault the indent fix closed. The gap this bound now also tolerates is
579
- // `DECLARATION_PREFIX_KEYWORDS`, a fixed, closed list of the JS/TS keywords
580
- // that legally sit between a comment block and the declaration keyword an
581
- // anchor starts with (`export`, `default`, `async`, visibility and
582
- // modifier keywords, …) — never arbitrary text. Each tolerated token must
583
- // still be followed by more whitespace before the next token or the anchor,
584
- // so the widening cannot reach past the anchor's own line: a decoy code line
585
- // sitting between the comment block and the anchor still breaks the run,
586
- // because that line does not end in `\n` followed only by keywords and
587
- // whitespace up to the anchor.
588
- //
589
- // The single definition of this bound in this directory (#1604), for
590
- // `paragraph`'s reason and after its history: three pins hand-rolled this same
591
- // regex locally first, each carrying its own chance of dropping a guard. A pin
592
- // needing this bound imports it — a local copy is the defect, not a style
593
- // choice.
594
-
595
- // The closed list `runAbove`'s tail bound tolerates between the comment block
596
- // and the anchor's own declaration keyword. Deliberately narrow: modifiers
597
- // and the declaration keywords themselves, nothing that could also open a
598
- // statement a comment block should not be glued to (no `if`, `for`, `return`,
599
- // …). Case-sensitive and matched as whole identifier tokens only (surrounded
600
- // by mandatory whitespace), so it cannot partially match inside a longer
601
- // identifier.
602
- const DECLARATION_PREFIX_KEYWORDS =
603
- "export|default|async|function|class|const|let|var|public|private|protected|static|readonly|abstract|declare|override|get|set";
604
-
605
- export function runAbove(text, anchor, what, marker) {
606
- assert.ok(marker, `${what}: runAbove needs a non-empty marker — empty matches every line above the anchor instead of just the comment block`);
607
- const above = text.slice(0, anchorAt(text, anchor, what));
608
- const run = above.match(
609
- new RegExp(`(?:^|\\n)((?:[ \\t]*${escapeRe(marker)}[^\\n]*\\n)+)[ \\t]*(?:(?:${DECLARATION_PREFIX_KEYWORDS})[ \\t]+)*$`),
610
- );
611
- return run ? run[1] : "";
612
- }
613
-
614
- // A shell comment block wraps at `#`, so a pinned phrase can break across lines
615
- // with the comment gutter, not whitespace, at the break — `\s+` does not span a
616
- // `#`. Strip the gutter and rejoin with the single inter-word space a wrap point
617
- // replaces.
618
- export const stripHashGutter = (text) => text.split("\n").map((l) => l.replace(/^\s*#\s?/, "")).join(" ");
619
-
620
- // A markdown blockquote wraps every line in a leading `>` gutter, so a
621
- // dispatch instruction embedded inside a quoted prompt (#1341's grandchild
622
- // recipe, nested under run-team's fix-applier prompt) does not begin with its
623
- // harness token until the gutter is stripped. Mirrors stripHashGutter's
624
- // reason for existing, one gutter shape later.
625
- export const stripQuoteGutter = (text) => text.split("\n").map((l) => l.replace(/^\s*>+\s?/, "")).join("\n");
626
-
627
- // One verbatim dispatch block, bounded by its OWN quote run rather than by the
628
- // next block's opening words, and returned with the gutter intact so the caller
629
- // owns the normalization. #1002: a whole-block golden fixture needs a slice that
630
- // is exactly one block, and the neighbour-anchored form every presence pin in
631
- // this directory uses is not one. Measured on `run-team/SKILL.md`:
632
- // `dispatch-block-pins-prose.test.mjs`'s `commitBlock` runs from `Commit
633
- // incrementally` to `**Every scratch file` and so already contains the whole
634
- // stash-prohibition block that landed between them, and its `worktreeBlock`
635
- // likewise contains the distilled-brief block. Both slices silently grew a
636
- // second block, which a presence pin never notices and a golden could not
637
- // survive: the fixture would be "this block plus whatever lands after it", and
638
- // re-blessing it would bless the insertion too.
639
- //
640
- // A maximal run of `>` lines is the bound markdown itself uses, so it cannot
641
- // drift: a sentence appended inside the block stays inside the run, and a block
642
- // spliced in after it is a SEPARATE run — which is what makes "every run in the
643
- // region has a fixture" a check a caller can make at all.
644
- //
645
- // Column-0 `>` only, matching how every pin in this directory already strips
646
- // this gutter (`/^>\s?/`) and how `member-prompt-prose.test.mjs` asserts every
647
- // member-facing line carries one. An indented gutter is not silently absorbed
648
- // here: it ends the run, so the block reds against its fixture instead of
649
- // passing under a changed markdown context.
650
- export function quoteBlocks(text) {
651
- const runs = [];
652
- let open = null;
653
- for (const line of text.split("\n")) {
654
- if (line.startsWith(">")) (open ??= []).push(line);
655
- else if (open) {
656
- runs.push(open.join("\n"));
657
- open = null;
658
- }
659
- }
660
- if (open) runs.push(open.join("\n"));
661
- return runs;
662
- }
663
-
664
- // The one quote run that BEGINS with `opener`, for a caller comparing that run
665
- // against a golden copy. Both failure directions throw rather than return, for
666
- // the reason a golden makes sharper than a presence pin does: an extractor that
667
- // returns "" for a block it cannot find compares empty against empty — or
668
- // against a fixture nobody re-blessed — and a deleted block passes.
669
- //
670
- // Anchored at the run's START, not anywhere inside it, so the identifier names
671
- // the block rather than merely occurring in it: a later block quoting the same
672
- // opening words cannot answer to it. Matched through `phrase()` on the
673
- // flattened run for `paragraph`'s reason — a literal `indexOf` reds on a rewrap
674
- // that the opener itself survives, turning a reflow into a red.
675
- // `emphasisTolerant` mirrors `anchorAt`'s option and for the same reason: off
676
- // by default because an opener typed WITH `**` must still match one, on so an
677
- // opener typed WITHOUT it can find a target whose emphasis moved. Safe to
678
- // apply only to the match, never to `hits[0]` itself — the returned run keeps
679
- // its `**` intact, since that is the raw byte content callers go on to
680
- // compare or rewrap.
681
- export function quoteBlock(text, opener, what, { emphasisTolerant = false } = {}) {
682
- const head = new RegExp(`^${phrase(opener).source}`);
683
- const view = emphasisTolerant ? unemphasized : (s) => s;
684
- const hits = quoteBlocks(text).filter((run) =>
685
- head.test(view(run.split("\n").map((l) => l.replace(/^>[ \t]?/, "")).join(" ").split(/\s+/).join(" ").trim())),
686
- );
687
- assert.notEqual(
688
- hits.length,
689
- 0,
690
- `${what}: no quote block opens on "${opener}" — the block was deleted, un-quoted, or its opening words changed. Re-anchor or restore it; this throws rather than comparing a golden fixture against nothing`,
691
- );
692
- assert.equal(
693
- hits.length,
694
- 1,
695
- `${what}: ${hits.length} quote blocks open on "${opener}" — a fixture would bind to whichever came first; narrow the opener`,
696
- );
697
- return hits[0];
698
- }
699
-
700
- // A `.mjs` header comment's prose is wrapped at `// `, one gutter per
701
- // physical line, so a scan that wants the prose as CONTINUOUS text — not
702
- // broken by a comment marker on every line — has to strip it first. Only
703
- // whole-line `//` comments are stripped (mirrors `stripComments.mjs`'s own
704
- // line-based-on-purpose note) — a trailing `code; // a note` is not a
705
- // comment LINE, it is code with a trailing note, and stripping mid-line
706
- // would blur that distinction and corrupt the code beside it.
707
- export const stripSlashGutter = (text) => text.split("\n").map((l) => l.replace(/^\s*\/\/\s?/, "")).join("\n");
708
-
709
- // A paragraph's physical line breaks, removed. `phrase()` holds this axis for
710
- // a pin that KNOWS the words it is looking for; this holds it for a pin that
711
- // DERIVES its subjects from the document. Those are different problems: a
712
- // literal you can pre-tolerate with `\s+`, but a scan like `see \*\*([^*\n]+)\*\*`
713
- // has to keep `\n` out of its own character classes to stay one clause, and a
714
- // generative regex cannot be made whitespace-tolerant and bounded at once.
715
- // #1609: rewrapping `review-and-fix.md`'s step 4 — pure reflow, not one word
716
- // changed — took that scan from 5 pointer names to 3, and the pins for the two
717
- // it lost stopped existing rather than failing. Three separate breaks, all the
718
- // same shape: the literal space in `see `, the literal space in the list
719
- // separator, and `\n` excluded from the name class. Tolerating them one at a
720
- // time in the regex is how the bound gets lost — move the WRAP, not the scan.
721
- //
722
- // The view, never the file: this returns a copy to scan, and `lineAt` maps a
723
- // hit in it back to the physical line a reader has to open. A pin reporting an
724
- // offset into the joined copy names a line that does not exist in the source.
725
- //
726
- // Joining only ADDS matches, so a pin cannot lose a hit to this — but `^` moves,
727
- // and that is the point in both directions. A `**Bold**` that a wrap happens to
728
- // push to column 0 mid-paragraph reads as block-leading to a `/^\*\*/m` scan
729
- // today, which is the mirror false GREEN: a pointer resolving to a target the
730
- // reflow invented. On the joined view it is mid-line again, where it belongs.
731
- //
732
- // What is NOT modelled: an indented (4-space) code block. Its second and later
733
- // lines are indistinguishable from a deeply-indented list continuation without
734
- // a real block parser, so they join and the block collapses to one line. Fenced
735
- // code is modelled and never joined — scan code through a fence, not an indent.
736
-
737
- // Starts a new block, so it never continues its predecessor.
738
- const BLOCK_START = /^ {0,3}(?:#{1,6}\s|[-*+](?:\s|$)|\d+[.)]\s|>|\||```|~~~|(?:-{3,}|\*{3,}|_{3,})\s*$)/;
739
- // Complete in itself, so nothing continues IT. Narrower than
740
- // BLOCK_START on purpose: a list item and a blockquote both take lazy
741
- // continuation lines, a heading and a thematic break take none.
742
- const BLOCK_END = /^ {0,3}(?:#{1,6}\s|\||```|~~~|(?:-{3,}|\*{3,}|_{3,})\s*$)/;
743
- // Two trailing SPACES or a trailing backslash is markdown's hard line break —
744
- // an authored break, not a wrap point, and removing it would change the
745
- // render. Spaces only, per CommonMark: a tab does not make one, and widening
746
- // this to `[ \t]{2}` refuses to join a line an editor left ending in a
747
- // space and a tab, which is the same false red one layer down.
748
- const HARD_BREAK = /(?: {2}|\\)$/;
749
-
750
- export function logicalLines(text) {
751
- const src = text.split("\n");
752
- const joins = new Array(src.length).fill(false);
753
- let fenced = false;
754
- for (let i = 0; i < src.length; i++) {
755
- const fence = /^ {0,3}(?:```|~~~)/.test(src[i]);
756
- joins[i] =
757
- i > 0 &&
758
- !fenced &&
759
- !fence &&
760
- /\S/.test(src[i - 1]) &&
761
- /\S/.test(src[i]) &&
762
- !HARD_BREAK.test(src[i - 1]) &&
763
- !BLOCK_END.test(src[i - 1]) &&
764
- !BLOCK_START.test(src[i]);
765
- if (fence) fenced = !fenced;
766
- }
767
-
768
- const starts = new Array(src.length);
769
- const out = [];
770
- let offset = 0;
771
- for (let i = 0; i < src.length; i++) {
772
- // A wrap point is one inter-word space, so the indent the wrap introduced
773
- // comes off and exactly one space goes back — `stripHashGutter`'s rejoin,
774
- // one gutter shape fewer. The trailing trim is why that space is never two.
775
- let line = joins[i] ? src[i].replace(/^[ \t]+/, "") : src[i];
776
- if (joins[i + 1]) line = line.replace(/[ \t]+$/, "");
777
- if (i > 0) {
778
- const sep = joins[i] ? " " : "\n";
779
- out.push(sep);
780
- offset += sep.length;
781
- }
782
- starts[i] = offset;
783
- out.push(line);
784
- offset += line.length;
785
- }
786
-
787
- // Strictly increasing — an unjoined line contributes its own `\n` and a
788
- // joined one is non-blank by construction — so this bisect has no ties to
789
- // break and an offset inside line i answers i, never i+1.
790
- const joined = out.join("");
791
- const lineAt = (at) => {
792
- assert.equal(
793
- at >= 0 && at < joined.length,
794
- true,
795
- `logicalLines().lineAt(${at}) out of range: the joined view is ${joined.length} bytes — a valid offset comes from a match against \`text\`, never a caller's own guess`,
796
- );
797
- let lo = 0;
798
- let hi = starts.length - 1;
799
- while (lo < hi) {
800
- const mid = (lo + hi + 1) >> 1;
801
- if (starts[mid] <= at) lo = mid;
802
- else hi = mid - 1;
803
- }
804
- return lo + 1;
805
- };
806
- return { text: joined, lineAt };
807
- }