bmad-module-ultracode-goal 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/README.md +12 -4
- package/docs/_internal/RELEASING.md +3 -2
- package/docs/architecture.md +6 -6
- package/docs/comparison.md +25 -25
- package/docs/gate-model.md +1 -1
- package/docs/getting-started.md +9 -5
- package/docs/how-it-works.md +5 -5
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +1 -1
- package/docs/troubleshooting.md +6 -3
- package/docs/why-ultracode-goal.md +3 -3
- package/package.json +6 -2
- package/skills/ucg-formalize/SKILL.md +11 -4
- package/skills/ucg-resolve/SKILL.md +4 -4
- package/skills/ucg-status/SKILL.md +21 -8
- package/skills/ultracode-goal/SKILL.md +4 -4
- package/skills/ultracode-goal/assets/module.yaml +1 -1
- package/skills/ultracode-goal/references/define-done.md +3 -1
- package/skills/ultracode-goal/references/execute.md +16 -16
- package/skills/ultracode-goal/references/finalize.md +6 -5
- package/skills/ultracode-goal/references/gate.md +18 -12
- package/skills/ultracode-goal/references/preflight.md +20 -12
- package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
- package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
- package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
- package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
- package/skills/ultracode-goal/scripts/status_render.py +96 -19
- package/tools/cli/lib/platform-codes.yaml +1 -1
- package/tools/cli/lib/ui.js +1 -1
- package/tools/validate-docs-links.js +302 -29
|
@@ -6,19 +6,22 @@
|
|
|
6
6
|
"""Render what a run is doing, out of the files that run already produced.
|
|
7
7
|
|
|
8
8
|
This is the READ side over the spine's own artifacts. It answers "what is this
|
|
9
|
-
run doing right now" from
|
|
9
|
+
run doing right now" from six sources and nothing else:
|
|
10
10
|
|
|
11
11
|
| what | source |
|
|
12
12
|
| heartbeat | <impl-artifacts>/run-status.json |
|
|
13
13
|
| decision log tail | the run folder's .decision-log.md |
|
|
14
14
|
| ledger | the deferred-work ledger |
|
|
15
15
|
| escalations | .escalation-<story>.md and escalation-<story>.json|
|
|
16
|
+
| advanced stories | <impl-artifacts>/sprint-status.yaml `done` rows |
|
|
16
17
|
| runs index | the runs root's per-run folders |
|
|
17
18
|
|
|
18
19
|
STRICTLY READ-ONLY. It starts no run, attaches to no session, and opens no file
|
|
19
|
-
for output. The
|
|
20
|
-
diff-viewer affordance below
|
|
21
|
-
|
|
20
|
+
for output. The processes it starts are read-only and serve the optional
|
|
21
|
+
diff-viewer affordance below: the `which` probe, and, only when the viewer is
|
|
22
|
+
present and the repository reads, one `git log` per story listing the commits in
|
|
23
|
+
its range (through `gate_trail._git_log`). Their results reach stdout only and
|
|
24
|
+
are never recorded anywhere. Everything else is a read. That property is what
|
|
22
25
|
makes this safe to run against a LIVE run: a status read that touched the
|
|
23
26
|
artifacts would be a status read that changed the thing it reports on.
|
|
24
27
|
|
|
@@ -53,6 +56,7 @@ from pathlib import Path
|
|
|
53
56
|
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
54
57
|
|
|
55
58
|
import gate_trail # noqa: E402 (sibling script, path set above)
|
|
59
|
+
import preflight_check # noqa: E402 (sibling script, path set above)
|
|
56
60
|
|
|
57
61
|
# Rendered wherever a source was absent, empty or unreadable.
|
|
58
62
|
NA = "n/a"
|
|
@@ -61,10 +65,16 @@ NA = "n/a"
|
|
|
61
65
|
# hook-maintained turn counter carry it.
|
|
62
66
|
MACHINE = "[machine-derived]"
|
|
63
67
|
|
|
64
|
-
#
|
|
65
|
-
#
|
|
66
|
-
#
|
|
67
|
-
|
|
68
|
+
# A raw Stop-hook marker with no typed sidecar beside it, for a story that has
|
|
69
|
+
# not advanced. Either its gate has not ruled yet (Execute promotes the marker
|
|
70
|
+
# only when the gate escalates the story on its turn count), or the session
|
|
71
|
+
# died before Execute promoted it. Either way it may be a pending escalation.
|
|
72
|
+
UNPROMOTED = "escalation (unpromoted: no gate verdict yet, or the session ended before Execute promoted it)"
|
|
73
|
+
|
|
74
|
+
# The same raw marker for a story whose gate advanced it. Execute never promotes
|
|
75
|
+
# that one: the gate decided completion, and the overrun is a sizing note in the
|
|
76
|
+
# decision log, so nothing is pending and it is not listed as an escalation.
|
|
77
|
+
CEILING_NOTE = "turn ceiling reached; the story advanced at its gate, so this is a sizing note and nothing is pending"
|
|
68
78
|
|
|
69
79
|
# The other thin record: the typed sidecar IS on disk but is empty or does not
|
|
70
80
|
# parse, so there is nothing to render out of it. Distinct from UNPROMOTED
|
|
@@ -78,8 +88,10 @@ SIDECAR_FIELDS = ("kind", "source", "decision_needed", "evidence")
|
|
|
78
88
|
|
|
79
89
|
# The optional diff viewer. Absent, nothing about it is rendered and the render
|
|
80
90
|
# is otherwise unchanged; present, each story that recorded a baseline commit
|
|
81
|
-
# gains
|
|
91
|
+
# gains a copy-paste line per commit in its range. It is an affordance, never a
|
|
92
|
+
# dependency.
|
|
82
93
|
VIEWER = "hunk"
|
|
94
|
+
MAX_VIEWER_LINES = 10
|
|
83
95
|
|
|
84
96
|
|
|
85
97
|
# --------------------------------------------------------------------------
|
|
@@ -252,6 +264,39 @@ def escalations(impl: Path) -> list[tuple[str, dict | None, Path]]:
|
|
|
252
264
|
return [(story, payload, path) for story, (payload, path) in sorted(found.items())]
|
|
253
265
|
|
|
254
266
|
|
|
267
|
+
def done_stories(impl: Path) -> set[str]:
|
|
268
|
+
"""Story keys whose `sprint-status.yaml` row reads `done`.
|
|
269
|
+
|
|
270
|
+
The gate's advance route writes `done` for every story it advances, and the
|
|
271
|
+
row outlives the heartbeat: `run-status.json` lists in-scope stories only, so
|
|
272
|
+
a later invocation's snapshot no longer carries a story an earlier one
|
|
273
|
+
advanced. Read with preflight's own block-scoped parser, so both agree.
|
|
274
|
+
"""
|
|
275
|
+
text = read_text(impl / "sprint-status.yaml")
|
|
276
|
+
if not text:
|
|
277
|
+
return set()
|
|
278
|
+
statuses = preflight_check._parse_development_status(text)
|
|
279
|
+
return {key for key, value in statuses.items() if value == "done"}
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
def advanced_stories(status: dict | None, impl: Path) -> set[str]:
|
|
283
|
+
"""Stories the gate advanced: by this snapshot's verdict, or by a `done` row."""
|
|
284
|
+
return {
|
|
285
|
+
str(entry.get("story"))
|
|
286
|
+
for entry in story_entries(status)
|
|
287
|
+
if entry.get("story") and entry.get("verdict") in ("advance", "defer")
|
|
288
|
+
} | done_stories(impl)
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
def ceiling_note_only(impl: Path, story: str, advanced: set[str]) -> bool:
|
|
292
|
+
"""True for an advanced story with the hook's raw marker and no typed sidecar."""
|
|
293
|
+
return (
|
|
294
|
+
story in advanced
|
|
295
|
+
and (impl / f".escalation-{story}.md").is_file()
|
|
296
|
+
and not (impl / f"escalation-{story}.json").exists()
|
|
297
|
+
)
|
|
298
|
+
|
|
299
|
+
|
|
255
300
|
def known_runs(runs_root: Path | None) -> list[tuple[str, str]]:
|
|
256
301
|
"""Every run folder under the runs root, as (name, status).
|
|
257
302
|
|
|
@@ -329,6 +374,7 @@ def render(
|
|
|
329
374
|
runs_root: Path | None,
|
|
330
375
|
ledger: Path,
|
|
331
376
|
viewer: bool,
|
|
377
|
+
repo: Path | None = None,
|
|
332
378
|
) -> str:
|
|
333
379
|
"""The whole render. Assembled once, printed once, written nowhere."""
|
|
334
380
|
status_path = impl / "run-status.json"
|
|
@@ -371,7 +417,18 @@ def render(
|
|
|
371
417
|
# Stories.
|
|
372
418
|
lines.extend(["## Stories", ""])
|
|
373
419
|
entries = story_entries(status)
|
|
374
|
-
|
|
420
|
+
advanced = advanced_stories(status, impl)
|
|
421
|
+
# An advanced story a later invocation's heartbeat no longer lists still
|
|
422
|
+
# gets its note, on a line of its own after the listed stories.
|
|
423
|
+
listed = {str(entry.get("story")) for entry in entries}
|
|
424
|
+
unlisted_notes = [
|
|
425
|
+
f"- {story}: {CEILING_NOTE} (`{marker.name}`)"
|
|
426
|
+
for marker in sorted(impl.glob(".escalation-*.md"))
|
|
427
|
+
if (story := marker.name[len(".escalation-") : -len(".md")])
|
|
428
|
+
and story not in listed
|
|
429
|
+
and ceiling_note_only(impl, story, advanced)
|
|
430
|
+
]
|
|
431
|
+
if not entries and not unlisted_notes:
|
|
375
432
|
lines.append(f"- {NA}")
|
|
376
433
|
for entry in entries:
|
|
377
434
|
story = str(entry.get("story") or NA)
|
|
@@ -381,23 +438,42 @@ def render(
|
|
|
381
438
|
f"attempts={entry.get('dev_attempts') if entry.get('dev_attempts') is not None else NA} "
|
|
382
439
|
f"re-loops={entry.get('reloop_count') if entry.get('reloop_count') is not None else NA}"
|
|
383
440
|
)
|
|
441
|
+
if ceiling_note_only(impl, story, advanced):
|
|
442
|
+
lines.append(f" - {CEILING_NOTE} (`.escalation-{story}.md`)")
|
|
384
443
|
sha = gate_trail.baseline_sha(impl, story)
|
|
385
444
|
if sha:
|
|
386
445
|
lines.append(f" - baseline `{sha}`")
|
|
387
446
|
if viewer:
|
|
388
|
-
# The affordance has to point at THIS story's diff
|
|
389
|
-
# the
|
|
390
|
-
#
|
|
391
|
-
#
|
|
392
|
-
#
|
|
393
|
-
# the
|
|
394
|
-
|
|
395
|
-
|
|
447
|
+
# The affordance has to point at THIS story's diff. The baseline
|
|
448
|
+
# is the commit that preceded the story's work, so showing it
|
|
449
|
+
# renders the previous story's diff - silently, since it is a
|
|
450
|
+
# real diff from the same repo. The end commit `.commit-<story>`
|
|
451
|
+
# records is the gate's evidence commit once one was made, which
|
|
452
|
+
# holds the trace files and not the code, so where the repo is
|
|
453
|
+
# readable every commit in the story's range gets its own line.
|
|
454
|
+
# Only where no end commit was recorded is the anchor the sole
|
|
455
|
+
# sha there is to hand the reader.
|
|
456
|
+
# A range longer than a story ever needs (a baseline that is not
|
|
457
|
+
# an ancestor of the end commit, say) falls back to one line
|
|
458
|
+
# rather than printing hundreds.
|
|
459
|
+
end = gate_trail.commit_sha(impl, story)
|
|
460
|
+
in_range = gate_trail._git_log(repo, sha, end) if (repo and end) else None
|
|
461
|
+
if in_range and len(in_range) > MAX_VIEWER_LINES:
|
|
462
|
+
in_range = None
|
|
463
|
+
for commit in reversed(in_range or [end or sha]):
|
|
464
|
+
lines.append(f" - {VIEWER} show {commit}")
|
|
465
|
+
lines.extend(unlisted_notes)
|
|
396
466
|
lines.append("")
|
|
397
467
|
|
|
398
468
|
# Escalations.
|
|
399
469
|
lines.extend(["## Escalations", ""])
|
|
400
|
-
|
|
470
|
+
# An advanced story's raw turn-ceiling marker is a sizing note, shown on its
|
|
471
|
+
# story row above, not a pending escalation.
|
|
472
|
+
pending = [
|
|
473
|
+
(story, payload, path)
|
|
474
|
+
for story, payload, path in escalations(impl)
|
|
475
|
+
if not ceiling_note_only(impl, story, advanced)
|
|
476
|
+
]
|
|
401
477
|
if not pending:
|
|
402
478
|
lines.append(f"- {NA}")
|
|
403
479
|
for story, payload, path in pending:
|
|
@@ -479,6 +555,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
479
555
|
runs_root=runs_root,
|
|
480
556
|
ledger=ledger,
|
|
481
557
|
viewer=viewer_available(),
|
|
558
|
+
repo=repo,
|
|
482
559
|
),
|
|
483
560
|
end="",
|
|
484
561
|
)
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# BMAD Platform Codes Configuration
|
|
2
2
|
#
|
|
3
3
|
# UltraCode Goal is Claude-Code-only: its autonomous run composes Claude Code
|
|
4
|
-
# primitives (
|
|
4
|
+
# primitives (Auto Mode, Auto Memory, PreToolUse/Stop hooks, dynamic
|
|
5
5
|
# workflows) that no other editor provides, so the installer targets Claude Code
|
|
6
6
|
# and only Claude Code. This file stays config-driven (one entry) so the install
|
|
7
7
|
# machinery has a single source of truth.
|
package/tools/cli/lib/ui.js
CHANGED
|
@@ -221,7 +221,7 @@ class UI {
|
|
|
221
221
|
}
|
|
222
222
|
|
|
223
223
|
// UCG is Claude-Code-only: its autonomous run composes Claude Code
|
|
224
|
-
// primitives (
|
|
224
|
+
// primitives (Auto Mode, hooks, dynamic workflows) no other editor
|
|
225
225
|
// provides, so the skill installs to Claude Code with no IDE prompt.
|
|
226
226
|
const ides = ['claude-code'];
|
|
227
227
|
log.info(`The skill installs for ${brand.light('Claude Code')}.`);
|
|
@@ -17,11 +17,19 @@
|
|
|
17
17
|
*
|
|
18
18
|
* So there are two passes:
|
|
19
19
|
*
|
|
20
|
-
* 1. SOURCE (docs/ *.md
|
|
21
|
-
*
|
|
20
|
+
* 1. SOURCE (docs/ *.md, including docs/_internal/, plus CONTRIBUTING.md,
|
|
21
|
+
* README.md and, when present, changes/README.md) - every
|
|
22
|
+
* relative target must exist on disk, and every `#anchor`,
|
|
23
|
+
* same-file or on a `.md` target, must match a heading id in
|
|
24
|
+
* that file. Cheap, and catches a typo or a renamed heading
|
|
25
|
+
* before a build is needed.
|
|
22
26
|
* 2. BUILT (build/site/ *.html) - every internal href must resolve to a
|
|
23
|
-
* real file
|
|
24
|
-
*
|
|
27
|
+
* real file, and its `#fragment` to an id on that page. This is
|
|
28
|
+
* the pass that catches plugin bugs, base-path bugs, and anything
|
|
29
|
+
* else that only manifests as a route.
|
|
30
|
+
*
|
|
31
|
+
* The heading-to-id rules live here, in `extractAnchors`, so every id the
|
|
32
|
+
* source pass checks is computed one way.
|
|
25
33
|
*
|
|
26
34
|
* The built pass is skipped with a warning when no build is present, so the
|
|
27
35
|
* tool stays usable locally without a build step. CI builds the site, so the
|
|
@@ -112,6 +120,36 @@ function pathPortion(href) {
|
|
|
112
120
|
return first === Infinity ? href : href.slice(0, first);
|
|
113
121
|
}
|
|
114
122
|
|
|
123
|
+
/**
|
|
124
|
+
* The decoded fragment of an href, or '' when it has none.
|
|
125
|
+
*
|
|
126
|
+
* Browsers match the percent-decoded fragment against ids, so `#caf%C3%A9`
|
|
127
|
+
* and `#café` name the same heading. A malformed escape is kept as written,
|
|
128
|
+
* which then matches nothing and is reported.
|
|
129
|
+
*/
|
|
130
|
+
function fragmentOf(href) {
|
|
131
|
+
const at = href.indexOf('#');
|
|
132
|
+
if (at === -1) {
|
|
133
|
+
return '';
|
|
134
|
+
}
|
|
135
|
+
const raw = href.slice(at + 1);
|
|
136
|
+
try {
|
|
137
|
+
return decodeURIComponent(raw);
|
|
138
|
+
} catch {
|
|
139
|
+
return raw;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Whether a fragment resolves on a page with these ids.
|
|
145
|
+
*
|
|
146
|
+
* An empty fragment and `#top` (any case) scroll to the top of the page by
|
|
147
|
+
* the HTML standard, whether or not an element carries that id.
|
|
148
|
+
*/
|
|
149
|
+
function fragmentResolves(fragment, ids) {
|
|
150
|
+
return fragment === '' || fragment.toLowerCase() === 'top' || ids.has(fragment);
|
|
151
|
+
}
|
|
152
|
+
|
|
115
153
|
// ---------------------------------------------------------------------------
|
|
116
154
|
// Pass 1: source
|
|
117
155
|
// ---------------------------------------------------------------------------
|
|
@@ -120,25 +158,17 @@ function pathPortion(href) {
|
|
|
120
158
|
const MD_LINK = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
|
|
121
159
|
|
|
122
160
|
/**
|
|
123
|
-
* Blank out code
|
|
124
|
-
*
|
|
125
|
-
* `MD_LINK` is a regex over raw text, so it cannot tell a link from a picture
|
|
126
|
-
* of a link. Without this, documenting the link convention itself, e.g. a
|
|
127
|
-
* ```markdown block containing [label](./example.md), fails the build as a
|
|
128
|
-
* broken link, and the only way to appease it is to create the placeholder
|
|
129
|
-
* file. (`tools/validate-file-refs.js` does NOT do this, so it carries the
|
|
130
|
-
* same latent false positive; worth fixing there too if it ever fires.)
|
|
161
|
+
* Blank out fenced code blocks, keeping every other line as it is.
|
|
131
162
|
*
|
|
132
163
|
* Fences are tracked line by line rather than matched as a pair, so an
|
|
133
164
|
* unterminated fence blanks to end of file instead of silently reverting to
|
|
134
|
-
* prose scanning.
|
|
135
|
-
*
|
|
136
|
-
* preserved, which keeps byte offsets usable if this ever reports positions.
|
|
165
|
+
* prose scanning. Line count is preserved, which keeps byte offsets usable if
|
|
166
|
+
* this ever reports positions.
|
|
137
167
|
*
|
|
138
168
|
* @param {string} text - Raw Markdown
|
|
139
|
-
* @returns {string} The same text with fenced blocks
|
|
169
|
+
* @returns {string} The same text with fenced blocks blanked
|
|
140
170
|
*/
|
|
141
|
-
function
|
|
171
|
+
function blankFences(text) {
|
|
142
172
|
let fence = null;
|
|
143
173
|
|
|
144
174
|
return text
|
|
@@ -157,22 +187,233 @@ function blankCode(text) {
|
|
|
157
187
|
fence = marker[1];
|
|
158
188
|
return '';
|
|
159
189
|
}
|
|
160
|
-
|
|
161
|
-
// Inline spans: a run of N backticks closes on a run of N.
|
|
162
|
-
return line.replaceAll(/(`+)[^`]*\1/g, ' ');
|
|
190
|
+
return line;
|
|
163
191
|
})
|
|
164
192
|
.join('\n');
|
|
165
193
|
}
|
|
166
194
|
|
|
167
195
|
/**
|
|
168
|
-
*
|
|
196
|
+
* Blank out code so a link that is merely *shown* is not read as a real one.
|
|
197
|
+
*
|
|
198
|
+
* `MD_LINK` is a regex over raw text, so it cannot tell a link from a picture
|
|
199
|
+
* of a link. Without this, documenting the link convention itself, e.g. a
|
|
200
|
+
* ```markdown block containing [label](./example.md), fails the build as a
|
|
201
|
+
* broken link, and the only way to appease it is to create the placeholder
|
|
202
|
+
* file. (`tools/validate-file-refs.js` does NOT do this, so it carries the
|
|
203
|
+
* same latent false positive; worth fixing there too if it ever fires.)
|
|
204
|
+
*
|
|
205
|
+
* Inline spans are only stripped outside a fence, so a stray backtick inside
|
|
206
|
+
* a block cannot pair with one outside it.
|
|
207
|
+
*
|
|
208
|
+
* @param {string} text - Raw Markdown
|
|
209
|
+
* @returns {string} The same text with fenced blocks and code spans blanked
|
|
210
|
+
*/
|
|
211
|
+
function blankCode(text) {
|
|
212
|
+
return (
|
|
213
|
+
blankFences(text)
|
|
214
|
+
.split('\n')
|
|
215
|
+
// Inline spans: a run of N backticks closes on a run of N.
|
|
216
|
+
.map((line) => line.replaceAll(/(`+)[^`]*\1/g, ' '))
|
|
217
|
+
.join('\n')
|
|
218
|
+
);
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
// ---------------------------------------------------------------------------
|
|
222
|
+
// Heading ids
|
|
223
|
+
// ---------------------------------------------------------------------------
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* Characters `github-slugger` deletes from a heading: everything except
|
|
227
|
+
* alphabetic characters (letters, letter numbers, and symbols Unicode counts
|
|
228
|
+
* as alphabetic, such as circled letters), marks, decimal digits, connector
|
|
229
|
+
* punctuation (`_`), the ASCII space and the hyphen-minus. Other punctuation
|
|
230
|
+
* (the em dash included), other symbols and emoji, other spaces and control
|
|
231
|
+
* characters all go.
|
|
232
|
+
*/
|
|
233
|
+
const SLUG_STRIP = /[^\p{Alphabetic}\p{M}\p{Nd}\p{Pc} -]/gu;
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Convert heading text to the id GitHub gives it, and the site too except
|
|
237
|
+
* for the two cases below.
|
|
238
|
+
*
|
|
239
|
+
* Must match `github-slugger`, which is what both GitHub and Starlight use to
|
|
240
|
+
* generate heading ids. The distinction that matters: it replaces each space
|
|
241
|
+
* INDIVIDUALLY and never collapses runs, so punctuation between words leaves a
|
|
242
|
+
* doubled hyphen. `## Scenario A: Greenfield + BMM Integration` becomes
|
|
243
|
+
* `scenario-a-greenfield--bmm-integration`, with two hyphens where the `+`
|
|
244
|
+
* was. Collapsing them here produced a slug no page ever has, so a correct
|
|
245
|
+
* anchor was reported broken.
|
|
246
|
+
*
|
|
247
|
+
* github-slugger itself is ESM-only and this tool is CommonJS in a synchronous
|
|
248
|
+
* flow, hence the faithful reimplementation rather than a dependency. Its
|
|
249
|
+
* table dates from Unicode 13, so a letter Unicode assigned later is dropped
|
|
250
|
+
* there and kept here; for every other character the two agree.
|
|
251
|
+
*
|
|
252
|
+
* The site's Markdown pipeline (Astro, under Starlight) differs in two ways:
|
|
253
|
+
* it trims one trailing hyphen off the id, and its SmartyPants step turns a
|
|
254
|
+
* `--` outside code into a dash the slug then drops. So a heading that ends
|
|
255
|
+
* in punctuation, or holds a `--`, gets different ids on GitHub and on the
|
|
256
|
+
* site. The source pass checks GitHub's; the built pass reads the ids the
|
|
257
|
+
* site actually carries.
|
|
258
|
+
*
|
|
259
|
+
* @param {string} text - Heading text as rendered, without Markdown syntax
|
|
260
|
+
* @returns {string} The id, before any `-N` suffix for a repeat
|
|
261
|
+
*/
|
|
262
|
+
function headingToAnchor(text) {
|
|
263
|
+
return text.toLowerCase().replaceAll(SLUG_STRIP, '').replaceAll(' ', '-');
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* An ATX heading line: up to three spaces, one to six `#`, then a space or
|
|
268
|
+
* the end of the line. `#tag` is a paragraph, not a heading. The `\r` of a
|
|
269
|
+
* CRLF line ending is trailing space like any other.
|
|
270
|
+
*/
|
|
271
|
+
const ATX_HEADING = /^ {0,3}#{1,6}(?:[ \t]+(.*?))?[ \t\r]*$/;
|
|
272
|
+
|
|
273
|
+
/** Named entities a heading is likely to carry; numeric ones are decoded too. */
|
|
274
|
+
const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: '\u00A0' };
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Reduce the Markdown of a heading to the text a renderer slugs.
|
|
278
|
+
*
|
|
279
|
+
* Only what changes the id is handled. Characters the slugger deletes anyway
|
|
280
|
+
* (`*`, `~`, brackets) need no care, but the ones it keeps do: a link's URL,
|
|
281
|
+
* an image's alt text (a renderer drops it), an entity's name, and the `_`
|
|
282
|
+
* of emphasis, which survives slugging where `*` does not. Code spans and
|
|
283
|
+
* backslash escapes are literal text, so they are set aside first, behind
|
|
284
|
+
* private-use placeholders that no heading carries.
|
|
285
|
+
*
|
|
286
|
+
* @param {string} raw - Heading content after the `#` markers
|
|
287
|
+
* @returns {string} Plain text
|
|
288
|
+
*/
|
|
289
|
+
function headingText(raw) {
|
|
290
|
+
const literals = [];
|
|
291
|
+
const keep = (literal) => {
|
|
292
|
+
literals.push(literal);
|
|
293
|
+
return `\uE000${literals.length - 1}\uE001`;
|
|
294
|
+
};
|
|
295
|
+
const text = raw
|
|
296
|
+
// A closing sequence of `#` is syntax when a space precedes it.
|
|
297
|
+
.replace(/(?:^|[ \t]+)#+[ \t]*$/, '')
|
|
298
|
+
// One space is stripped from each side of a code span when both have one.
|
|
299
|
+
.replaceAll(/(`+)(.+?)\1(?!`)/g, (_, _ticks, body) =>
|
|
300
|
+
keep(body.startsWith(' ') && body.endsWith(' ') && body.trim() ? body.slice(1, -1) : body),
|
|
301
|
+
)
|
|
302
|
+
// A backslash-escaped character is literal, never syntax.
|
|
303
|
+
.replaceAll(/\\([!-/:-@[-`{-~])/g, (_, char) => keep(char))
|
|
304
|
+
.replaceAll(/!\[[^\]]*\]\([^)]*\)/g, '')
|
|
305
|
+
.replaceAll(/\[([^\]]*)\]\([^)]*\)/g, '$1')
|
|
306
|
+
.replaceAll(/\[([^\]]*)\]\[[^\]]*\]/g, '$1')
|
|
307
|
+
.replaceAll(/<((?:https?|mailto):[^>\s]*)>/gi, '$1')
|
|
308
|
+
.replaceAll(/<\/?[a-z][^>]*>/gi, '')
|
|
309
|
+
.replaceAll(/(^|[^\p{L}\p{N}_])(__?)(?=\S)(.*?\S)\2(?![\p{L}\p{N}_])/gu, '$1$3')
|
|
310
|
+
.replaceAll(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name) => {
|
|
311
|
+
if (name[0] === '#') {
|
|
312
|
+
const code = /x/i.test(name[1]) ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1));
|
|
313
|
+
return code > 0 && code <= 0x10_ff_ff ? String.fromCodePoint(code) : '\uFFFD';
|
|
314
|
+
}
|
|
315
|
+
return ENTITIES[name.toLowerCase()] ?? entity;
|
|
316
|
+
});
|
|
317
|
+
|
|
318
|
+
// No trim: the heading line was trimmed already, and space left beside a
|
|
319
|
+
// dropped image or tag is still in the rendered text, so it is in the id.
|
|
320
|
+
return text.replaceAll(/\uE000(\d+)\uE001/g, (_, index) => literals[Number(index)]);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* Blank out a leading YAML front matter block, keeping the line count.
|
|
325
|
+
*
|
|
326
|
+
* Its `# ` lines are YAML comments, not headings.
|
|
327
|
+
*/
|
|
328
|
+
function blankFrontMatter(text) {
|
|
329
|
+
const lines = text.split('\n');
|
|
330
|
+
if (lines[0].trimEnd() !== '---') {
|
|
331
|
+
return text;
|
|
332
|
+
}
|
|
333
|
+
const end = lines.findIndex((line, index) => index > 0 && /^(?:---|\.\.\.)\s*$/.test(line));
|
|
334
|
+
if (end === -1) {
|
|
335
|
+
return text;
|
|
336
|
+
}
|
|
337
|
+
return lines.map((line, index) => (index <= end ? '' : line)).join('\n');
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* Collect the id of every heading in a Markdown file.
|
|
342
|
+
*
|
|
343
|
+
* Repeated headings are disambiguated exactly as github-slugger does: the
|
|
344
|
+
* first occurrence keeps the bare slug and each later one gets `-N` appended,
|
|
345
|
+
* counting from 1, skipping any id an earlier heading already took. A
|
|
346
|
+
* stateless slug function would collect only the first of several same-named
|
|
347
|
+
* headings and report a link to any later one as broken.
|
|
348
|
+
*
|
|
349
|
+
* Fenced code is skipped. A shell comment in a ```bash block starts with `# `
|
|
350
|
+
* like a heading, and reading the raw file counted every one of them, so a
|
|
351
|
+
* link to a comment passed as a link to a section. Front matter is skipped
|
|
352
|
+
* for the same reason. Only ATX headings are read: a setext heading (text
|
|
353
|
+
* underlined with `===` or `---`) gets no id here.
|
|
354
|
+
*
|
|
355
|
+
* @param {string} content - Raw Markdown
|
|
356
|
+
* @returns {Set<string>} Every heading id in the file
|
|
357
|
+
*/
|
|
358
|
+
function extractAnchors(content) {
|
|
359
|
+
const anchors = new Set();
|
|
360
|
+
const occurrences = new Map();
|
|
361
|
+
|
|
362
|
+
for (const line of blankFences(blankFrontMatter(content)).split('\n')) {
|
|
363
|
+
const match = line.match(ATX_HEADING);
|
|
364
|
+
if (!match) {
|
|
365
|
+
continue;
|
|
366
|
+
}
|
|
367
|
+
const base = headingToAnchor(headingText(match[1] ?? ''));
|
|
368
|
+
let id = base;
|
|
369
|
+
while (occurrences.has(id)) {
|
|
370
|
+
const count = occurrences.get(base) + 1;
|
|
371
|
+
occurrences.set(base, count);
|
|
372
|
+
id = `${base}-${count}`;
|
|
373
|
+
}
|
|
374
|
+
occurrences.set(id, 0);
|
|
375
|
+
anchors.add(id);
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
return anchors;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* Markdown files outside docs/ that the source pass reads too, relative to
|
|
383
|
+
* the project root, each read when present.
|
|
384
|
+
*
|
|
385
|
+
* GitHub is the only place they render, so no build resolves their links: a
|
|
386
|
+
* moved file or a renamed heading leaves them dead with every other check
|
|
387
|
+
* green. Their relative targets resolve from their own folder, as on GitHub.
|
|
388
|
+
*/
|
|
389
|
+
const ROOT_DOCS = ['CONTRIBUTING.md', 'README.md', 'changes/README.md'];
|
|
390
|
+
|
|
391
|
+
/**
|
|
392
|
+
* Check every relative link in the Markdown sources: the target must exist
|
|
393
|
+
* on disk, and a `#anchor` must match a heading id in its file.
|
|
394
|
+
*
|
|
395
|
+
* Any target counts, not only `.md`: a workflow file, a folder or LICENSE is
|
|
396
|
+
* as dead on GitHub when it moves. Anchors are checked on the same file and
|
|
397
|
+
* on `.md` targets; GitHub gives other files line anchors, not heading ids.
|
|
169
398
|
*
|
|
170
399
|
* Deliberately does NOT enforce a `./` prefix. The plugin accepts bare links,
|
|
171
400
|
* and GitHub renders them correctly, so requiring the prefix would be style,
|
|
172
401
|
* not correctness. What matters is that the target exists.
|
|
173
402
|
*/
|
|
174
403
|
function checkSource({ projectRoot, docsDir }, report) {
|
|
175
|
-
const files =
|
|
404
|
+
const files = [
|
|
405
|
+
...new Set([
|
|
406
|
+
...walk(docsDir, new Set(['.md'])),
|
|
407
|
+
...ROOT_DOCS.map((rel) => path.join(projectRoot, rel)).filter((file) => fs.existsSync(file)),
|
|
408
|
+
]),
|
|
409
|
+
];
|
|
410
|
+
const anchorsByFile = new Map();
|
|
411
|
+
const anchorsOf = (file) => {
|
|
412
|
+
if (!anchorsByFile.has(file)) {
|
|
413
|
+
anchorsByFile.set(file, extractAnchors(fs.readFileSync(file, 'utf8')));
|
|
414
|
+
}
|
|
415
|
+
return anchorsByFile.get(file);
|
|
416
|
+
};
|
|
176
417
|
|
|
177
418
|
for (const file of files) {
|
|
178
419
|
const rel = path.relative(projectRoot, file);
|
|
@@ -180,12 +421,17 @@ function checkSource({ projectRoot, docsDir }, report) {
|
|
|
180
421
|
const text = blankCode(fs.readFileSync(file, 'utf8'));
|
|
181
422
|
|
|
182
423
|
for (const match of text.matchAll(MD_LINK)) {
|
|
183
|
-
const
|
|
424
|
+
const href = match[1];
|
|
425
|
+
const target = pathPortion(href);
|
|
426
|
+
const anchor = fragmentOf(href);
|
|
184
427
|
|
|
185
|
-
if (
|
|
428
|
+
if (EXTERNAL.test(href)) {
|
|
186
429
|
continue;
|
|
187
430
|
}
|
|
188
|
-
if (!target
|
|
431
|
+
if (!target) {
|
|
432
|
+
if (!fragmentResolves(anchor, anchorsOf(file))) {
|
|
433
|
+
report(rel, `anchor matches no heading in this file: ${href}`);
|
|
434
|
+
}
|
|
189
435
|
continue;
|
|
190
436
|
}
|
|
191
437
|
// Root-absolute targets mean different things on the two surfaces, and
|
|
@@ -206,9 +452,13 @@ function checkSource({ projectRoot, docsDir }, report) {
|
|
|
206
452
|
report(
|
|
207
453
|
rel,
|
|
208
454
|
target.startsWith('/')
|
|
209
|
-
? `root-absolute link target does not exist at the repository root, so it is dead on GitHub: ${
|
|
210
|
-
: `link target does not exist: ${
|
|
455
|
+
? `root-absolute link target does not exist at the repository root, so it is dead on GitHub: ${href}`
|
|
456
|
+
: `link target does not exist: ${href}`,
|
|
211
457
|
);
|
|
458
|
+
continue;
|
|
459
|
+
}
|
|
460
|
+
if (target.endsWith('.md') && fs.statSync(resolved).isFile() && !fragmentResolves(anchor, anchorsOf(resolved))) {
|
|
461
|
+
report(rel, `anchor matches no heading in ${path.relative(projectRoot, resolved)}: ${href}`);
|
|
212
462
|
}
|
|
213
463
|
}
|
|
214
464
|
}
|
|
@@ -315,11 +565,24 @@ function assetUrls(html) {
|
|
|
315
565
|
* which is precisely how a browser resolves them, and precisely the step that
|
|
316
566
|
* the earlier page-relative bug failed.
|
|
317
567
|
*
|
|
568
|
+
* An href's `#fragment` must match an id on the page it lands on, the same
|
|
569
|
+
* page for a bare `#anchor`. These are the ids the site really carries, which
|
|
570
|
+
* are not always GitHub's (see `headingToAnchor`), so a link that the source
|
|
571
|
+
* pass accepts for GitHub and that misses on the site fails here.
|
|
572
|
+
*
|
|
318
573
|
* @param {string} base - Deployment base path
|
|
319
574
|
* @returns {number} Number of HTML pages checked
|
|
320
575
|
*/
|
|
321
576
|
function checkBuilt({ projectRoot, buildDir }, base, report) {
|
|
322
577
|
const pages = walk(buildDir, new Set(['.html']));
|
|
578
|
+
const idsByPage = new Map();
|
|
579
|
+
const idsOf = (page) => {
|
|
580
|
+
if (!idsByPage.has(page)) {
|
|
581
|
+
const html = fs.readFileSync(page, 'utf8');
|
|
582
|
+
idsByPage.set(page, new Set(Array.from(html.matchAll(/\sid="([^"]*)"/g), (match) => match[1])));
|
|
583
|
+
}
|
|
584
|
+
return idsByPage.get(page);
|
|
585
|
+
};
|
|
323
586
|
|
|
324
587
|
for (const page of pages) {
|
|
325
588
|
const rel = path.relative(projectRoot, page);
|
|
@@ -331,13 +594,16 @@ function checkBuilt({ projectRoot, buildDir }, base, report) {
|
|
|
331
594
|
const seen = new Set();
|
|
332
595
|
|
|
333
596
|
for (const { attr, url: href } of assetUrls(html)) {
|
|
334
|
-
if (!href ||
|
|
597
|
+
if (!href || EXTERNAL.test(href) || seen.has(href)) {
|
|
335
598
|
continue;
|
|
336
599
|
}
|
|
337
600
|
seen.add(href);
|
|
338
601
|
|
|
339
602
|
const target = pathPortion(href);
|
|
340
603
|
if (!target) {
|
|
604
|
+
if (attr === 'href' && !fragmentResolves(fragmentOf(href), idsOf(page))) {
|
|
605
|
+
report(rel, `href matches no id on this page: ${href}`);
|
|
606
|
+
}
|
|
341
607
|
continue;
|
|
342
608
|
}
|
|
343
609
|
|
|
@@ -366,6 +632,10 @@ function checkBuilt({ projectRoot, buildDir }, base, report) {
|
|
|
366
632
|
|
|
367
633
|
if (!fs.existsSync(candidate)) {
|
|
368
634
|
report(rel, `${attr} resolves to nothing: ${href} (looked for ${path.relative(buildDir, candidate)})`);
|
|
635
|
+
continue;
|
|
636
|
+
}
|
|
637
|
+
if (attr === 'href' && candidate.endsWith('.html') && !fragmentResolves(fragmentOf(href), idsOf(candidate))) {
|
|
638
|
+
report(rel, `href matches no id on ${path.relative(buildDir, candidate)}: ${href}`);
|
|
369
639
|
}
|
|
370
640
|
}
|
|
371
641
|
}
|
|
@@ -528,7 +798,7 @@ async function run(cfg, log = console.log) {
|
|
|
528
798
|
}
|
|
529
799
|
|
|
530
800
|
const sourceCount = checkSource(cfg, report);
|
|
531
|
-
log(`Source pass: ${sourceCount} markdown file(s) in docs
|
|
801
|
+
log(`Source pass: ${sourceCount} markdown file(s) in docs/, plus ${ROOT_DOCS.join(', ')} where present`);
|
|
532
802
|
|
|
533
803
|
let builtCount = 0;
|
|
534
804
|
const haveBuild = fs.existsSync(cfg.buildDir);
|
|
@@ -640,6 +910,9 @@ module.exports = {
|
|
|
640
910
|
checkBuilt,
|
|
641
911
|
resolveBase,
|
|
642
912
|
blankCode,
|
|
913
|
+
blankFences,
|
|
914
|
+
headingToAnchor,
|
|
915
|
+
extractAnchors,
|
|
643
916
|
assetUrls,
|
|
644
917
|
walk,
|
|
645
918
|
buildInputsStatus,
|