chore(docs): tooling to keep hand-written docs in sync with implementation#1906
Merged
Conversation
…ation Stands up recurring implementation-accuracy verification for the 128 hand-written docs as the platform evolves, layered cheapest-and-earliest first: 1. scripts/docs-audit/affected-docs.mjs — maps packages/** changes to the hand-written docs that reference the affected packages (by npm name / repo path), so an audit can be scoped to what actually changed instead of re-auditing everything. Supports --all and --json. 2. .github/workflows/docs-drift-check.yml — advisory CI gate: on PRs touching packages/**, posts a sticky PR comment listing the docs that reference the changed code. Flags drift at the source; never fails the build. 3. .claude/workflows/docs-accuracy-audit.js — the reusable multi-agent audit (audit + adversarial verifier per doc), parameterized by args.docs; defaults to all hand-written docs. Same pipeline that produced #1866 and #1904. 4. scripts/docs-audit/README.md — how the four parts fit together, including the scheduled-routine backstop. References (content/docs/references/, generated from packages/spec) are out of scope and handled by a separate regenerate pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| const sinceRef = args.find((a) => !a.startsWith('--')) || 'origin/main'; | ||
|
|
||
| function sh(cmd) { | ||
| return execSync(cmd, { cwd: repoRoot, stdio: ['ignore', 'pipe', 'ignore'] }).toString(); |
| // docs that describe a package without naming it. | ||
|
|
||
| import { execSync } from 'node:child_process'; | ||
| import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'; |
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
2 participants
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.
Follow-up to #1904. Stands up recurring implementation-accuracy verification for the 128 hand-written docs as the platform evolves, so drift gets caught continuously instead of in one-off audits. Layered cheapest-and-earliest-first:
1.
scripts/docs-audit/affected-docs.mjs— change → docs mappingMaps
packages/**changes to the hand-written docs that reference the affected packages (by npm name / repo path), so an audit can be scoped to what actually changed instead of re-auditing all 128 docs. Supports--alland--json.2.
.github/workflows/docs-drift-check.yml— advisory CI gateOn PRs touching
packages/**, posts a sticky PR comment listing the docs that reference the changed code. Flags drift at the source, before it lands onmain. Never fails the build.3.
.claude/workflows/docs-accuracy-audit.js— reusable multi-agent auditThe same audit + adversarial verifier pipeline that produced #1866 and #1904, now parameterized by
args.docs(defaults to all hand-written docs). Run scoped to the CI-flagged files, or full.4. Scheduled routine — periodic backstop
A cron routine (monthly / per-release) computes the change-scoped doc list, runs the audit workflow, builds, and opens a PR when there are fixes. Set up separately via the schedule tooling; documented in the README.
Scope: hand-written docs only (
content/docs/**minusreferences/). Generated references are produced frompackages/specand handled by a separate regenerate pass.Tested:
affected-docs.mjs --all→ 128 docs; change-scoping against a 40-commit range → 44 packages → 109 docs; workflow body syntax-valid in the harness context.🤖 Generated with Claude Code