ci(docs): add documentation drift detection to CI pipeline

[jaymoneymanxl]

Closes #786

Problem

Documentation in the docs/ directory can become stale or broken over time:

• File paths referenced in markdown links may point to deleted or renamed files.
• npm run commands embedded in code blocks may reference scripts that no longer exist in package.json.
• Generated API documentation (docs/api/generated/) may be empty if generation failed or was skipped.
• Internal markdown links may point to non-existent files after reorganisation.

Without automated checking, these issues go unnoticed until a reader or downstream tool encounters a 404.

Changes

scripts/validate-docs-drift.mjs (new)

A Node.js script that performs four categories of validation:

1. File path resolution (getFilePaths() → validateFileRefs())

   • Scans every .md file under docs/ for patterns like `path/to/file` and markdown links [text](path).
   • Resolves relative paths against the containing file's directory.
   • Reports an error if the resolved path does not exist on disk.
   • Ignores external URLs (http://, https://), anchor links (#heading), template variables ({{...}}), mailto links, and common binary/image extensions (.png, .jpg, .svg, .woff2, etc.).

2. npm script validation (getReferencedScripts() → validateScriptRefs())

   • Extracts npm run <name> commands from code blocks (bash/sh/shell/console/terminal).
   • Looks up each <name> in the scripts field of package.json.
   • Reports an error if a referenced script does not exist.

3. Generated API doc validation (validateGeneratedDocs())

   • Checks that docs/api/generated/ exists and contains at least one file.
   • Issues a warning if the directory is empty, prompting the maintainer to run npm run docs:api:generate.

4. Internal link integrity (validateInternalLinks())

   • Parses every markdown link [text](href) across all docs/**/*.md files.
   • For non-external, non-anchor links, resolves the href against the source file's directory.
   • Reports an error if the resolved path does not exist.
   • Falls back to check .mdx variants if the .md path does not exist.

package.json

• Added "docs:validate-drift": "node scripts/validate-docs-drift.mjs" script.

.github/workflows/docs.yml

• Added validate-docs-drift job that runs the new script on every push/PR touching docs/ or src/lib/ paths.
• Runs on ubuntu-latest with Node.js 20 and cached npm dependencies.
• Fails the job (exit code 1) if any drift is detected.

Verification

• Run npm run docs:validate-drift locally on a clean tree → exits 0 with no errors.
• Add a broken link to a .md file → script reports the exact file and line.
• Reference a non-existent npm run script in a code block → script reports the missing script name and the file that references it.
• Empty the docs/api/generated/ directory → script warns about missing generated docs.

[vercel]

@jaymoneymanxl is attempting to deploy a commit to the nanle-code's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@jaymoneymanxl Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits