Check local links across docs pages by kiranmagic7 · Pull Request #1746 · steipete/CodexBar

kiranmagic7 · 2026-06-25T00:40:46Z

Summary

expand the documentation link checker to scan local markdown/image/html links inside docs pages, not only README and the provider index
resolve docs-page links relative to the file that contains them, so nested links such as ../claude.md are validated correctly
include the source file in future missing-target or missing-anchor errors

Why

Scripts/check-documentation-links.mjs already runs in lint-linux, but it only covered README links and the provider detail list. The docs tree has additional relative links between pages, including nested docs under docs/refactor and docs/solutions, that were not part of the guard.

Current main has no broken docs-page links; this change makes the existing lint lane catch future drift.

Validation

node --check Scripts/check-documentation-links.mjs
node Scripts/check-documentation-links.mjs -> documentation links OK: 134 local links
git diff --check
./Scripts/lint.sh lint-linux

Compatibility

No app behavior changes. The only risk is that future docs-only changes may fail lint when a local docs-page link points outside docs/, has a missing target, or references a missing markdown heading anchor.

Review focus: whether docs-page links should continue to be constrained to targets inside docs/.

clawsweeper · 2026-06-25T00:41:36Z

Codex review: needs maintainer review before merge. Reviewed June 26, 2026, 10:30 PM ET / 02:30 UTC.

Summary
The PR expands Scripts/check-documentation-links.mjs to recursively validate local Markdown, image, and HTML links in docs/**, resolve links relative to their source files, report source-labelled diagnostics, and allow selected root documentation files.

Reproducibility: not applicable. as a cleanup PR rather than a bug report. Source inspection confirms current main lacks docs-wide scanning, and the PR proof reports the expanded 134-link scan at the latest head.

Review metrics: 2 noteworthy metrics.

Changed surface: 1 script changed, +58/-13. The diff is confined to docs automation and does not touch app runtime code.
Reported real scan: 134 local links. The PR body and owner follow-up report the actual docs corpus passing under the stricter checker.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

[P1] Merging deliberately makes the existing lint-linux lane stricter for future docs changes: missing targets, missing Markdown anchors, or links outside docs/** plus the approved root documentation files will fail CI.

Maintainer options:

Accept stricter docs lint (recommended)
Maintainers can merge with the owner-approved docs link policy and treat future failures as intentional documentation drift protection.
Relax the allowlist before merge
If root-relative or broader repository documentation links should be allowed, adjust the policy in this script before landing.

Next step before merge

[P2] No repair lane is needed; the latest head resolves the earlier review feedback and leaves no concrete code defect for automation to fix.

Security
Cleared: The diff changes a local Node documentation lint script only; it adds no dependencies, downloads, secret access, or command execution paths.

Review details

Best possible solution:

Land the extended checker with the approved root allowlist and same-page anchor handling, keeping future docs lint failures intentional and source-labelled.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a cleanup PR rather than a bug report. Source inspection confirms current main lacks docs-wide scanning, and the PR proof reports the expanded 134-link scan at the latest head.

Is this the best way to solve the issue?

Yes. Extending the existing local documentation link checker is the narrow maintainable path, and the latest head also handles the owner-approved root allowlist plus same-page fragment anchors.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a064edab3e47.

Label changes

Label justifications:

P3: This is low-risk documentation automation cleanup with no app runtime behavior change.
merge-risk: 🚨 automation: The PR intentionally tightens an existing CI lint lane, so future docs changes can fail for link-policy violations.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body and owner follow-up provide after-fix command output for the 134-link scan, lint lanes, full suite, and temporary fragment-anchor fixtures.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body and owner follow-up provide after-fix command output for the 134-link scan, lint lanes, full suite, and temporary fragment-anchor fixtures.

Evidence reviewed

What I checked:

AGENTS.md policy read: The repository AGENTS.md was read fully; its guidance to keep script/docs changes scoped and validate with lint/check informed this review. (AGENTS.md:1, a064edab3e47)
Current main baseline: Current main validates README documentation links and provider detail links only, so docs-wide recursive scanning is not already implemented on main. (Scripts/check-documentation-links.mjs:16, a064edab3e47)
PR head docs recursion: The PR head gathers Markdown, image, and HTML links from every Markdown file under docs/** and validates them relative to the containing file. (Scripts/check-documentation-links.mjs:28, 8b6e02273e66)
Prior review gap fixed: The latest head accepts fragment-only links and resolves empty paths to the source Markdown file before anchor validation. (Scripts/check-documentation-links.mjs:107, 8b6e02273e66)
Lint automation surface: lint-linux runs the documentation link checker, so the PR intentionally tightens a CI lint lane rather than changing app runtime behavior. (Scripts/lint.sh:54, a064edab3e47)
Maintainer proof and policy context: The owner follow-up for exact head 8b6e0227 reports same-page anchor fixtures, the real 134-link scan, lint-linux, make check, the full 43-shard suite, and autoreview passing. (8b6e02273e66)

Likely related people:

steipete: Peter Steinberger introduced the current main checker state in the available blame, added the approved-root and same-page-anchor fixups on this branch, and provided the maintainer policy/proof comments. (role: recent area contributor and policy reviewer; confidence: high; commits: f380287041b8, d0e327f72064, 9c7c17cf7d73; files: Scripts/check-documentation-links.mjs, Scripts/lint.sh)
Yuxin-Qiao: Yuxin Qiao authored the merged docs-only CI work that added the documentation link checker and lint wiring touched by this PR. (role: adjacent automation introducer; confidence: medium; commits: 669d1e9b08ee; files: Scripts/check-documentation-links.mjs, Scripts/lint.sh, .github/workflows/ci.yml)
kiranmagic7: kiranmagic7 previously authored merged current-main documentation-link tests and authored the initial branch commit for this docs checker expansion. (role: recent documentation-link test contributor; confidence: medium; commits: e6e84a6b4bf6, 4e80c146e525; files: Tests/CodexBarTests/DocumentationLinkTests.swift, Scripts/check-documentation-links.mjs)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

steipete · 2026-06-27T01:51:15Z

@clawsweeper re-review

Exact head: d0e327f720646bd2376b15a7d3e0c733d7b40033.

Synced current main and resolved the policy question: recursive links may target docs/** plus the public root docs README.md, CHANGELOG.md, LICENSE, and VISION.md; every other repository escape remains rejected. The real 134-link scan, lint-linux, make check, the full 43-shard suite, and local autoreview pass. A temporary fixture also proved an approved root link succeeds while ../Package.swift fails.

clawsweeper · 2026-06-27T01:51:18Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d0e327f720

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-27T01:54:58Z

+  if (!parsed || parsed.protocol || parsed.host || !parsed.pathname) return false;
+  return !parsed.pathname.startsWith("#");


Validate fragment-only docs links

When a docs page uses an in-page anchor like [Usage](#usage) or <a href="#usage">, parseRelativeURL returns an empty pathname, so this filter drops the link before validateLocalDocLink can check the fragment against markdownHeadingAnchors. That leaves a common class of local documentation links unchecked, so misspelled same-page anchors will still pass lint-linux even though the new docs-wide checker is meant to catch missing anchors.

Useful? React with 👍 / 👎.

steipete · 2026-06-27T02:23:03Z

@clawsweeper re-review

Exact head: 8b6e02273e66ad53bd9a9897d42bc17d6fe24cb2.

Fragment-only Markdown and HTML links now resolve against their containing Markdown file before anchor validation. A temporary fixture proved a valid same-page anchor passes and a missing one fails with a source-labelled diagnostic; the real 134-link scan, lint-linux, make check, the full 43-shard suite, and local plus whole-branch autoreview pass.

clawsweeper · 2026-06-27T02:23:06Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Check local links across docs pages

4e80c14

steipete added 2 commits June 27, 2026 02:44

Merge branch 'main' into codex/pr-1746-fixup

3e4bc66

fix: allow approved root documentation links

d0e327f

chatgpt-codex-connector Bot reviewed Jun 27, 2026

View reviewed changes

steipete added 2 commits June 27, 2026 03:17

fix: validate same-page documentation anchors

9c7c17c

Merge remote-tracking branch 'origin/main' into codex/pr-1746-fixup

8b6e022

steipete merged commit 7971bed into steipete:main Jun 27, 2026
10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Check local links across docs pages#1746

Check local links across docs pages#1746
steipete merged 5 commits into
steipete:mainfrom
kiranmagic7:kiran/check-doc-page-links-20260625

kiranmagic7 commented Jun 25, 2026

Uh oh!

clawsweeper Bot commented Jun 25, 2026 •

edited

Loading

Uh oh!

steipete commented Jun 27, 2026

Uh oh!

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 27, 2026

Uh oh!

steipete commented Jun 27, 2026

Uh oh!

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		if (!parsed \|\| parsed.protocol \|\| parsed.host \|\| !parsed.pathname) return false;
		return !parsed.pathname.startsWith("#");

Conversation

kiranmagic7 commented Jun 25, 2026

Summary

Why

Validation

Compatibility

Uh oh!

clawsweeper Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jun 27, 2026

Uh oh!

clawsweeper Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

steipete commented Jun 27, 2026

Uh oh!

clawsweeper Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jun 25, 2026 •

edited

Loading

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading

clawsweeper Bot commented Jun 27, 2026 •

edited

Loading