scan

# doc-sentinel:scan Deep scan that cross-references all documentation against the current state of the codebase. Unlike the hook (which checks only files changed in a commit), this scans everything. This skill is **read-only** — it reports drift but does not modify files. ## Phase 1: Load Configuration ```bash cat .doc-sentinel.json 2>/dev/null || echo "No config — using defaults" ``` Defaults if no config: - `docs_root`: `docs` - `watch_files`: `AGENTS.md`, `ARCHITECTURE.md`, `README.md`, `CLAUDE.md` - `ignore_sources`: `*.test.*`, `*.spec.*`, `__tests__/**` ## Phase 2: Discover Documentation Collect all doc files: ```bash # docs/ directory find docs/ -name '*.md' -type f 2>/dev/null | sort # Top-level docs for f in AGENTS.md ARCHITECTURE.md CLAUDE.md README.md CHANGELOG.md; do [ -f "$f" ] && echo "$f" done ``` Plus any `watch_files` from config. ## Phase 3: Extract References For each doc file, extract references to source code: ### 3a: File Path References Search for paths that look like source file references: ```bash # Extract paths from backticks, links, and code blocks grep -oE '`[a-zA-Z0-9_./-]+\.(ts|js|py|rb|go|rs|java|tsx|jsx)`' "$doc_file" grep -oE '\b(src|lib|app|packages)/[a-zA-Z0-9_./-]+' "$doc_file" ``` ### 3b: Command References Extract shell commands documented in the file: ```bash # Find code blocks with shell commands grep -E '^\$|^pnpm |^npm |^yarn |^cargo |^go |^bundle |^python |^make ' "$doc_file" ``` ### 3c: Port and URL References ```bash grep -oE '(localhost|127\.0\.0\.1):[0-9]+' "$doc_file" grep -oE ':[0-9]{4,5}\b' "$doc_file" ``` ### 3d: Environment Variable References ```bash grep -oE '\$\{?[A-Z_][A-Z0-9_]*\}?' "$doc_file" grep -oE '`[A-Z_][A-Z0-9_]*`' "$doc_file" ``` ## Phase 4: Validate References For each extracted reference, check if it still holds: ### 4a: File Paths — Do They Exist? ```bash # For each extracted path [ -f "$path" ] && echo "OK: $path" || echo "DRIFT: $path — file not found" ``` ### 4b: Directory References — Do They Exist? ```bash [ -d "$dir" ] && echo "OK: $dir" || echo "DRIFT: $dir — directory not found" ``` ### 4c: Commands — Do They Parse? For package.json scripts: ```bash # Check if documented npm/pnpm scripts exist jq -r '.scripts | keys[]' package.json 2>/dev/null ``` ### 4d: Ports — Are They Consistent? Cross-reference ports mentioned in docs against: - `docker-compose.yml` / `compose.yml` port mappings - `.env` / `.env.example` port variables - Other doc files (detect conflicts between docs) ### 4e: Env Vars — Are They Still Used? ```bash # Check if documented env vars appear in source grep -r "$ENV_VAR" src/ lib/ app/ --include='*.ts' --include='*.js' --include='*.py' -l 2>/dev/null ``` ### 4f: Symlink Integrity ```bash # CLAUDE.md should symlink to AGENTS.md (if using agent-ready convention) [ -L "CLAUDE.md" ] && readlink CLAUDE.md || echo "Not a symlink" ``` ## Phase 5: Freshness Analysis For each doc file, compare modification dates: ```bash # When was the doc last modified? git log -1 --format="%ai" -- "$doc_file" # When were its referenced source files last modified? git log -1 --format="%ai" -- "$source_file" ``` **Freshness scoring:** | Score | Label | Criteria | |-------|-------|----------| | 0 | Fresh | Doc modified more recently than all referenced sources | | 1 | Current | Doc modified within 7 days of source changes | | 2 | Stale | Source changed 7-30 days after doc last updated | | 3 | Very Stale | Source changed >30 days after doc last updated | ADR files are exempt from freshness scoring — they are point-in-time records. ## Phase 6: Generate Report Output a structured drift report organized by severity: ```markdown # Documentation Drift Report Generated: YYYY-MM-DD HH:MM ## Critical Drift (broken references) | Doc | Reference | Issue | |-----|-----------|-------| | ARCHITECTURE.md | `src/old-module/` | Directory not found | | AGENTS.md | `pnpm studio` | Script not in package.json | ## Stale References (code changed, doc not updated) | Doc | Source File | Doc Last Updated | Source Last Updated | Freshness | |-----|------------|------------------|---------------------|-----------| | docs/api.md | src/routes/auth.ts | 2026-01-15 | 2026-04-01 | Very Stale | ## Warnings | Doc | Issue | |-----|-------| | README.md | Port 3000 mentioned but compose.yml maps to 4000 | | AGENTS.md | Env var `OLD_VAR` not found in source | ## Summary - X critical drift(s) — broken paths, missing files - Y stale reference(s) — code changed without doc updates - Z warning(s) — potential inconsistencies - N docs scanned, M references checked ``` ## Rules - Never modify any files — this is a read-only scan - Report concrete evidence (file paths, line numbers, dates) not speculation - Skip vendored directories (node_modules, vendor, .git) - Treat CHANGELOG.md as append-only — only flag if it references non-existent versions/tags - ADRs are exempt from freshness checks - If a doc file is >500 lines, sample the first 200 and last 100 lines for references