feat: validate-docmap subcommand — CI hard-fail if source directories lack docmap coverage #141

New Issue

2026-05-15T04:43:21Z

rodin commented

2026-05-15 04:43:21 +00:00

Summary

CI needs a way to verify that a doc-map.yml is correctly configured: every changed file is covered by at least one docmap paths: glob, and every docs: entry actually exists on disk.

This is a pure static check — no AI, no external API calls.

Feature Request

Add a review-bot validate-docmap subcommand that CI jobs call with the list of changed files.

Invocation

# Typical CI usage
git diff --name-only origin/main HEAD | \
  review-bot validate-docmap \
    --docmap .review-bot/doc-map.yml \
    --repo-root .

Changed files are read from stdin (one per line). Returns exit 0 on clean, non-zero on any failure.

Checks

1. Coverage check (hard fail)

For each changed file read from stdin, verify at least one paths: glob in the docmap matches it.

ERROR: changed files with no docmap coverage:
  lib/gargoyle/new_module/foo.ex
  lib/gargoyle/another_module/bar.ex

2. Stale-docs check (hard fail)

For each docs: entry in the docmap, verify the referenced path exists on disk relative to --repo-root.

ERROR: stale docmap docs: entries (paths do not exist):
  docs/old-design.md
  docs/deleted-module/

Flags

Flag	Required	Default	Description
`--docmap`	Yes	—	Path to doc-map YAML file
`--repo-root`	No	`.` (cwd)	Root for resolving `docs:` paths

Context

Docmap parsing + glob matching lives in review/docmap.go — ParseDocMapConfig, MatchDocs, DocMapConfig, globMatch
globMatch/mappingMatches are unexported — need to either export them or add a thin exported helper
The validate-url subcommand (cmd/review-bot/validateurl.go) is the pattern for standalone subcommands
Dispatched in main.go via os.Args[1] switch before flag parsing

Acceptance Criteria

review-bot validate-docmap subcommand dispatched from main.go
Reads changed files from stdin (one per line); empty stdin = no coverage failures
--docmap flag (required)
--repo-root flag (optional, default cwd)
Coverage check: fails if any stdin file is not matched by any paths: glob
Stale-docs check: fails if any docs: entry does not exist on disk under --repo-root
Both checks run always — all failures reported, not just the first
Clear error output listing all uncovered/stale paths
Exit 0 on clean, exit 1 on any failure, exit 2 on usage/parse error
Unit tests: clean pass, uncovered file, stale doc, both failures, empty stdin
README updated with usage example

## Summary CI needs a way to verify that a `doc-map.yml` is correctly configured: every changed file is covered by at least one docmap `paths:` glob, and every `docs:` entry actually exists on disk. This is a **pure static check** — no AI, no external API calls. ## Feature Request Add a `review-bot validate-docmap` subcommand that CI jobs call with the list of changed files. ## Invocation ```sh # Typical CI usage git diff --name-only origin/main HEAD | \ review-bot validate-docmap \ --docmap .review-bot/doc-map.yml \ --repo-root . ``` Changed files are read from **stdin** (one per line). Returns exit 0 on clean, non-zero on any failure. ## Checks ### 1. Coverage check (hard fail) For each changed file read from stdin, verify at least one `paths:` glob in the docmap matches it. ``` ERROR: changed files with no docmap coverage: lib/gargoyle/new_module/foo.ex lib/gargoyle/another_module/bar.ex ``` ### 2. Stale-docs check (hard fail) For each `docs:` entry in the docmap, verify the referenced path exists on disk relative to `--repo-root`. ``` ERROR: stale docmap docs: entries (paths do not exist): docs/old-design.md docs/deleted-module/ ``` ## Flags | Flag | Required | Default | Description | |------|----------|---------|-------------| | `--docmap` | Yes | — | Path to doc-map YAML file | | `--repo-root` | No | `.` (cwd) | Root for resolving `docs:` paths | ## Context - Docmap parsing + glob matching lives in `review/docmap.go` — `ParseDocMapConfig`, `MatchDocs`, `DocMapConfig`, `globMatch` - `globMatch`/`mappingMatches` are unexported — need to either export them or add a thin exported helper - The `validate-url` subcommand (`cmd/review-bot/validateurl.go`) is the pattern for standalone subcommands - Dispatched in `main.go` via `os.Args[1]` switch before flag parsing ## Acceptance Criteria - [ ] `review-bot validate-docmap` subcommand dispatched from `main.go` - [ ] Reads changed files from stdin (one per line); empty stdin = no coverage failures - [ ] `--docmap` flag (required) - [ ] `--repo-root` flag (optional, default cwd) - [ ] Coverage check: fails if any stdin file is not matched by any `paths:` glob - [ ] Stale-docs check: fails if any `docs:` entry does not exist on disk under `--repo-root` - [ ] Both checks run always — all failures reported, not just the first - [ ] Clear error output listing all uncovered/stale paths - [ ] Exit 0 on clean, exit 1 on any failure, exit 2 on usage/parse error - [ ] Unit tests: clean pass, uncovered file, stale doc, both failures, empty stdin - [ ] README updated with usage example

rodin referenced this issue from a commit

2026-05-15 04:48:37 +00:00

feat(#141): export FileCoveredByDocMap helper in review/docmap.go

rodin referenced this issue from a commit

2026-05-15 04:48:37 +00:00

feat(#141): add validate-docmap subcommand

rodin referenced this issue from a commit

2026-05-15 04:48:37 +00:00

docs(#141): add validate-docmap subcommand to README

rodin referenced a pull request that will close this issue

2026-05-15 04:49:00 +00:00

feat(#141): validate-docmap subcommand — CI hard-fail on missing docmap coverage #142