feat(docs): lint npm-run script references in docs against package.json#616
Merged
Conversation
Tier D. check-docs-links.mjs validates file PATHS in docs but nothing checks the hundreds of `npm run <script>` references, so a renamed/removed script leaves stale instructions the agents then follow. - scripts/check-docs-script-refs.mjs: scans inline code spans + fenced blocks in README/AGENTS/docs (excluding archive/audit/dated) for `npm run <script>` and validates each against package.json's scripts. Prose is ignored (code-only scan); placeholders and an allowlist are skipped. Pure parse/extract/validate exported. - docs:check-scripts npm script (advisory, like docs:check-links — not in CI so historical docs cannot block unrelated PRs). - tests/docs-script-refs.test.ts: 7 tests. On first run it caught a real stale ref (`test:e2e:advisory`, renamed to test:e2e:regression) in the branch-review-ledger; allowlisted with a note since it is a historical "Checks" record. 262 live references now resolve. Verified: 7/7 vitest, real-docs run passes, eslint, tsc (own files clean), prettier. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
BigSimmo
enabled auto-merge (squash)
July 13, 2026 17:51
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
Contributor
📝 WalkthroughWalkthroughAdds a ChangesDocumentation script validation
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant Developer
participant NpmScript
participant DocumentationChecker
participant PackageJson
participant MarkdownFiles
Developer->>NpmScript: run docs:check-scripts
NpmScript->>DocumentationChecker: invoke checker
DocumentationChecker->>PackageJson: load package scripts
DocumentationChecker->>MarkdownFiles: scan selected Markdown files
MarkdownFiles-->>DocumentationChecker: return script references
DocumentationChecker-->>Developer: report stale references and exit status
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/check-docs-script-refs.mjs`:
- Around line 34-39: Update the ALLOWLIST handling in the documentation
reference checker so test:e2e:advisory is ignored only when scanning
docs/branch-review-ledger.md, while placeholder tokens remain globally allowed.
Add a regression test proving active-document references to the retired script
still fail validation outside that historical ledger.
- Around line 59-60: Update the script-name pattern in the region reference
scanning loop to include dots in matched npm, pnpm, and yarn script names,
preserving the existing allowed characters. Add a regression test covering a
dotted script name such as lint.fix and verify it is detected in documentation
references.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 80cf961e-fa4f-4cac-b736-ed4ba83a0f91
📒 Files selected for processing (3)
package.jsonscripts/check-docs-script-refs.mjstests/docs-script-refs.test.ts
Comment on lines
+34
to
+39
| const ALLOWLIST = new Set([ | ||
| "<script>", | ||
| "<name>", | ||
| "your-script", | ||
| "test:e2e:advisory", // renamed to test:e2e:regression (2026-07); kept for historical ledger accuracy | ||
| ]); |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Scope the retired-script exception to its historical record.
Line 38 suppresses test:e2e:advisory in every scanned file, so a newly added active-doc reference to that removed script passes validation. Keep placeholder tokens global, but apply this exception only to docs/branch-review-ledger.md (or exclude that record separately) and add a regression test.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/check-docs-script-refs.mjs` around lines 34 - 39, Update the
ALLOWLIST handling in the documentation reference checker so test:e2e:advisory
is ignored only when scanning docs/branch-review-ledger.md, while placeholder
tokens remain globally allowed. Add a regression test proving active-document
references to the retired script still fail validation outside that historical
ledger.
Comment on lines
+59
to
+60
| for (const m of region.matchAll(/\b(?:npm|pnpm|yarn)\s+run\s+([A-Za-z0-9][A-Za-z0-9:_-]*)/g)) { | ||
| names.add(m[1]); |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## scripts/check-docs-script-refs.mjs\n'
ast-grep outline scripts/check-docs-script-refs.mjs --view expanded || true
printf '\n## relevant lines\n'
nl -ba scripts/check-docs-script-refs.mjs | sed -n '1,180p'
printf '\n## search for parsePackageScripts and related tests\n'
rg -n "parsePackageScripts|check-docs-script-refs|lint\.fix|npm\\s+run|pnpm\\s+run|yarn\\s+run" -S .Repository: BigSimmo/Database
Length of output: 898
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## scripts/check-docs-script-refs.mjs (relevant section)\n'
sed -n '40,80p' scripts/check-docs-script-refs.mjs
printf '\n## tests and references\n'
rg -n "extractScriptRefs|parsePackageScripts|findStaleRefs|lint\\.fix|npm\\s+run|pnpm\\s+run|yarn\\s+run" -S . --glob '!**/node_modules/**'Repository: BigSimmo/Database
Length of output: 50376
Allow dotted npm script names in docs refs. scripts/check-docs-script-refs.mjs:59-60 skips names like lint.fix, so stale references to valid package scripts are missed. Add . to the token class and cover it with a regression test.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/check-docs-script-refs.mjs` around lines 59 - 60, Update the
script-name pattern in the region reference scanning loop to include dots in
matched npm, pnpm, and yarn script names, preserving the existing allowed
characters. Add a regression test covering a dotted script name such as lint.fix
and verify it is detected in documentation references.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Tier D.
check-docs-links.mjsvalidates file paths in docs, but nothing checks the hundreds ofnpm run <script>references — so a renamed/removed script leaves stale instructions the agents (Codex/Claude/Cursor) then follow.scripts/check-docs-script-refs.mjs— scans inline code spans + fenced blocks in README/AGENTS/docs (excluding archive/audit/dated) fornpm run <script>and validates each againstpackage.jsonscripts. Prose is ignored (code-only scan); placeholders and an allowlist are skipped. PureparsePackageScripts/extractScriptRefs/findStaleRefsexported and tested.docs:check-scriptsnpm script — advisory, likedocs:check-links(not in CI, so historical docs can't block unrelated PRs).tests/docs-script-refs.test.ts— 7 tests.It caught real drift on the first run
docs/branch-review-ledger.mdreferencednpm run test:e2e:advisory, which main renamed totest:e2e:regression. Since that's a historical "Checks" record, I allowlisted the old name (with a note) rather than falsify the record. 262 live references now resolve.Verification
7/7 vitest, real-docs run passes, eslint,
tsc(own files clean), prettier.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Tests