test(docs): check that doc links, commands and flags exist

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: micro — tests only; 2 new test files; no blast-radius path; the tests are the deterministic check.

• Problem: the docs are about to get much more traffic (linked from Vapi's docs), and the last few PRs moved a lot of them. Nothing stopped a broken relative link, a stale anchor, or a command that no longer exists (npm run <script>, --flag) from shipping.
• Who it affects: new users following the README and guides, and coding agents that run the commands the docs show.
• What changes:
  • tests/docs-links.test.ts: every relative link and #anchor in the root *.md, docs/** and examples/** must resolve, ignoring code blocks.
  • tests/docs-commands.test.ts: every npm run <x> in the docs must be a package.json script, and every --flag shown with a command must exist in src/. improvements.md is excluded because it records historical behavior; --allow-unrelated-histories is allowed as a git flag.

Evidence of value

Mutation	Result
Rename a heading that a link targets	links test fails, naming the file and anchor
Rename a package.json script	commands test fails, naming the doc and script
Rename a CLI flag in src/	commands test fails, naming the doc and flag
Current docs	both pass (more than 20 files checked)

Testing plan

• npm test (505 tests at this commit) and npx tsc --noEmit pass.
• Not tested: external https:// links, which would make the suite network-dependent.

Refs TEST-141

🤖 Generated with Claude Code

[scott-lowe-vapi]

• feat: identify every gitops API request with a User-Agent #78
• feat(validate): catch broken references and show findings on the PR #77
• ci: validate every org's resources on every pull request #76
• ci: lint workflows and test the PR check's key-sharing decision #75
• test(docs): check that doc links, commands and flags exist #74 👈 (View in Graphite)
• fix(cleanup): never delete resources matched by .vapi-ignore #73
• docs(agents): one compact guide for Claude, Codex and Cursor #72
• docs: edit the guides for new readers and fix inaccuracies #71
• docs: restructure the README into a short landing page and topic guides #70
• docs: prepare for public release: scrub internal names, fix examples, add community files #69
• feat(promotion): gate promotion out of an org on a passing check #66
• fix(promotion): commit the files of transitions that applied when a later one fails #65
• test(promotion): pin the exact files promoting an assistant writes to the target #68
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[chris-garber-vapi]

Huh, these tests probably work -- part of me wonders if there isn't some existing library that would do the doc link checks for us and potentially handle more edge cases, did we look at https://www.npmjs.com/package/markdown-link-check?

[scott-lowe-vapi]

@chris-garber-vapi I did consider markdown-link-check. It mostly checks HTTP links, which makes the suite network-dependent and flaky in CI, and it's another dependency. These tests check relative links and anchors offline, and also that every npm run <script> and --flag in the docs exists, which no link checker does. So I'm keeping them as they are for now.

🤖 Generated with Claude Code

[scott-lowe-vapi]

Merge activity

• Oct 7, 5:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Oct 7, 6:03 PM UTC: Graphite rebased this pull request as part of a merge.
• Oct 7, 6:03 PM UTC: @scott-lowe-vapi merged this pull request with Graphite.