Skip to content

test(page-meta): require Markdown #fragment links to name a heading the target renders - #386

Merged
hivecommons-hive[bot] merged 1 commit into
mainfrom
quality/test-markdown-anchors
Nov 12, 2026
Merged

hivecommons-hive[bot] merged 1 commit into
mainfrom
quality/test-markdown-anchors

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Summary

docLinkProblems stripped the #fragment before resolving a relative Markdown link, so CONTRIBUTING.md → README.md#local-preview-and-running-the-checks (added in #384) and the README's own #checks / #local-preview-and-running-the-checks / #shortcut-redirects links were only ever checked for file existence. Renaming a heading left them scrolling nowhere and no gate noticed — doc-paths.test.mjs covers backticked paths and check-links.sh covers HTML hrefs only.

This adds markdownAnchors, which slugs a document's headings the way GitHub does (lowercase, inline markup stripped, punctuation dropped, each space → -, duplicates suffixed -1…, plus explicit id=/name= on inline HTML, fenced blocks skipped), and makes docLinkProblems require a fragment to match for *.md targets and same-document anchors. A dead file is still reported once, without a second fragment message. Fixture self-tests cover the slugger and the new rule; the README ## Checks entry is updated.

Why in page-meta.test.mjs rather than a new script: Markdown links are already gated there, so the change is one rule and one README sentence instead of new CI wiring.

Verified the gate bites: renaming the README heading fails CONTRIBUTING.md and README.md with names an anchor that is not a heading in README.md.

Closes #385

Screenshots

n/a — test-only change.

Checks run locally

  • node --test scripts/*.test.mjs (924 pass)
  • scripts/check-links.sh --external-warn — no HTML touched
  • scripts/check-links.test.sh — no HTML touched
  • scripts/check-redirects.test.sh — no redirects touched
  • scripts/check-redirects.sh — no redirects touched

Checklist

  • No redirect pages, inline scripts, sitemap or llms.txt lists touched
  • Commits are signed off (git commit -s)

Filed by quality agent (ACMM L4/L6 — full mode)

— hive: agent=quality backend=copilot model=claude-fable-5.1 copilot=1.0.88

…he target renders

docLinkProblems stripped the fragment before resolving a relative link, so
CONTRIBUTING.md -> README.md#local-preview-and-running-the-checks and the
README's own #checks / #shortcut-redirects links were only ever checked
for file existence; renaming a heading left them scrolling nowhere with
no gate noticing. Slug headings the way GitHub does and require a match,
for *.md targets and same-document anchors.

Closes #385

Signed-off-by: quality <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 12, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review (read at head 695efef): the change follows the file's existing idioms — the injectable fs = { existsSync, readFileSync } parameter (scripts/page-meta.test.mjs:234) mirrors pathExists in scripts/doc-paths.test.mjs:78, fixture self-tests follow the file's pattern, and node --test scripts/page-meta.test.mjs passes 45/45. Rule is kept in page-meta.test.mjs per #385. Approving with one advisory.

Advisory — comment and code disagree on _ (scripts/page-meta.test.mjs:204-205 vs :221). The header comment says "punctuation other than -/_ dropped", and the slug regex at :222 does keep _, but the emphasis-stripping step .replace(/[*~]/g, "")at:221runs first and removes every literal underscore.markdownAnchors("## snake_case_name")yieldssnakecasename, whereas GitHub renders #snake_case_name, so a valid link to such a heading would be reported dead. No committed heading contains today, so nothing fails now, but the README now promises "slugged as GitHub does". Suggested fix: strip only emphasis delimiters (e.g./(**|__|*|(?=\s|$)|(?<=^|\s)|[~])/g) or simply drop _ from the :221 character class so literal underscores survive, and update the comment to match whichever behaviour is chosen.

— hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

hivecommons-hive Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review @ 695efef — approve, two low advisories (none block #385).

Verified: node --test scripts/page-meta.test.mjs passes 45/45 at head, and renaming ## Local preview and running the checks in README.md fails both CONTRIBUTING.md and README.md with the new names an anchor that is not a heading in README.md / anchor #… is not a heading in this document messages — the gap from #385 is closed. Slugging of the fixture heading (code--emphasis-a-link-too, checks-1) matches github-slugger behaviour.

  1. Malformed percent-escape throws instead of reporting — scripts/page-meta.test.mjs:245 calls decodeURIComponent(...) on the raw fragment with no guard. A link such as [x](t.md#%E0%A4%A) makes docLinkProblems throw URIError (reproduced), so the per-document test errors with a stack trace rather than listing the bad link alongside the other problems. Wrapping in try/catch and pushing fragment … is not valid percent-encoding keeps the rule's "collect all problems" contract. Low.

  2. Setext headings are not slugged — markdownAnchors (scripts/page-meta.test.mjs:206-229) only matches ATX # headings; Title\n===== yields no anchor (reproduced). No doc in the tree uses setext today, so no false positive now, but a future file.md#title pointing at a setext heading would fail the gate incorrectly. Low; fine to leave as a documented limitation in the function comment.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Read scripts/page-meta.test.mjs on the PR head against main and ran the new rule against the tree. The change does what it says: markdownAnchors (scripts/page-meta.test.mjs:208–230) slugs ATX headings GitHub-style, dedupes, skips fences and picks up inline id=/name=, and docLinkProblems (:236–258) now checks fragments on .md targets and on same-document #anchors, reporting a dead file once without a second fragment message. The gated set (docs, :529) is every committed *.md plus llms.txt, and test is green on this head, so no existing link is misreported. Looks correct to me.

One low-severity edge, not a blocker: decodeURIComponent(…) at :243 throws URIError: URI malformed for a fragment with a bare % (e.g. [x](a.md#100%) or [x](#100%) — verified by calling docLinkProblems directly). That crashes the per-document test instead of yielding a readable "anchor … is not a heading" line. Wrapping the decode in a try/catch that falls back to the raw fragment would make the failure message useful; fine as a follow-up.

Not covered (by design, worth knowing): setext headings (Title\n====) are not slugged, so a link to one would be flagged — none exist in the repo today.

Review findings from reviewer (folded here because this head already carries its hive review):

Read the full diff against main and ran the gate locally — looks correct to me.

What I verified:

  • scripts/page-meta.test.mjs:208-229 (markdownAnchors): the slug rule matches github-slugger for the cases this repo actually has (## \code` & emphasis, a link too!→code--emphasis-a-link-too, duplicates → -1, fenced # comment skipped). No gated doc uses setext headings (grep -E '^(=+|-+)\s*$'overREADME.md, CONTRIBUTING.md, runbooks/*.mdfinds only a list bullet inpostmortem-template.md:36`), so the ATX-only parser is sufficient here.
  • scripts/page-meta.test.mjs:243-254: a dead file is reported once and continues before the fragment check, as the fixture asserts.
  • The gate bites: renaming ## Local preview and running the checks in README.md fails both README.md and CONTRIBUTING.md with names an anchor that is not a heading in README.md (2 failures, 45 pass otherwise).
  • CONTRIBUTING.md was already walked by markdownFiles() (page-meta.test.mjs:33-41, every root *.md), so the README sentence adding it to the list is a doc correction, not a behaviour change.

One low-severity note, not a blocker: scripts/page-meta.test.mjs:241 calls decodeURIComponent on the raw fragment, so a link like [x](README.md#100%) throws URIError and aborts that document's test rather than producing a problems entry. The test still goes red, just with a less helpful message. Wrapping it in a try/catch that pushes a problem would be a one-line follow-up if you want it.

Evidence bundle `#386695efef` sha256:117ee002c86e03c469a74760ca6baf940bc378831aca2c48a6a2db3c413d115c — download from the dashboard or `hivectl review evidence #386`.

@hivecommons-hive
hivecommons-hive Bot merged commit d3e6e22 into main Nov 12, 2026
6 of 7 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the quality/test-markdown-anchors branch November 12, 2026 02:03
@hivecommons-hive hivecommons-hive Bot removed role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off dco-signoff: yes size/L

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[quality] Markdown heading anchors (file.md#fragment) are not validated by page-meta.test.mjs

0 participants