fix(scripts): detect stale contributor doc references

[FelixTJDietrich]

Description

Contributor docs can keep naming deleted repository paths or removed npm dependencies because inline code still renders normally. This extends the existing check:instructions gate to validate path- and package-shaped inline code in docs/contributor/**/*.{md,mdx} and root-level *.md against the working tree and workspace manifests.

Note

Bare npm names are indistinguishable from ordinary identifiers without context, so the gate checks scoped names and recognizable package-shaped names rather than treating every inline-code word as a dependency.

Fixes #1499

How to test

pnpm run check:instructions
pnpm run check

Manual smoke test:

1. Add `scripts/does-not-exist.ts` to a contributor document.
2. Run pnpm run check:instructions and verify the error identifies both the document and missing path.
3. Move the reference into a fenced code block and verify the focused check passes.

Summary by CodeRabbit

• New Features

  • Added validation for stale contributor documentation, including undeclared packages and unresolved repository paths.
  • Improved Markdown and MDX parsing, including inline code spans and fenced content.
  • Added checks for package manifest fields and malformed package files.

• Bug Fixes

  • Improved path matching and supported-document scope validation.
  • Updated security-scan validation to recognize an additional approved reference location.

• Tests

  • Expanded coverage for documentation references, path boundaries, package claims, and malformed configuration files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d5c716b8-b780-4573-aaf0-23db9c1d925c

📥 Commits

Reviewing files that changed from the base of the PR and between 742fadf and d764eeb.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• .github/workflows/ci-security-scan.yml
• package.json
• scripts/check-agent-instructions.test.ts
• scripts/check-agent-instructions.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The instruction checker extracts CommonMark and MDX code spans, validates contributor-document path and package claims, and builds repository snapshots through an exported scan function. The CLI and tests use the new APIs.

Changes

Contributor claim validation

Layer / File(s)	Summary
Markdown span extraction scripts/check-agent-instructions.ts, scripts/check-agent-instructions.test.ts	The checker normalizes visible Markdown, handles fenced code blocks, and exports codeSpans for CommonMark and MDX inline code extraction.
Contributor claim validation scripts/check-agent-instructions.ts, scripts/check-agent-instructions.test.ts	Contributor documents are checked for unresolved repository paths and undeclared npm packages. Tests cover document scopes, path boundaries, exceptions, package manifest fields, malformed manifests, and parser behavior.
Repository scan and reporting scripts/check-agent-instructions.ts, scripts/check-agent-instructions.test.ts, package.json, .github/workflows/ci-security-scan.yml	The exported scan function builds repository snapshots. analyse, the CLI, and repository validation tests use the snapshot. The security scan permits the checker reference, and parser packages are declared as development dependencies.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to d764e

The change extends contributor-document checks to catch stale path and package references; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant scan
  participant analyse
  participant ContributorDocs
  participant RepositorySnapshot
  CLI->>scan: scan repository root
  scan->>ContributorDocs: read contributor Markdown and MDX
  scan-->>CLI: return Snapshot
  CLI->>analyse: validate Snapshot
  analyse->>RepositorySnapshot: resolve paths and packages
  RepositorySnapshot-->>analyse: return stale claims
  analyse-->>CLI: report validation results

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 2 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes extend the existing instructions gate, validate contributor-document paths and npm packages, reuse Markdown parsing, ignore fenced code, add parsing and rule tests, and update the required…
Out of Scope Changes check	✅ Passed	The reviewed changes are within scope. The tests, dependency additions, scanner updates, and CI allowlist change directly support the contributor-document reference validation objectives.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: detecting stale references in contributor documentation.

Full details: Linked Issues check

Explanation

The changes extend the existing instructions gate, validate contributor-document paths and npm packages, reuse Markdown parsing, ignore fenced code, add parsing and rule tests, and update the required dependencies. The implementation matches the requirements in issue #1499.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 2 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 1499-extend-instructions-gate

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📚 Documentation Preview

Preview has been removed (PR closed)