audit_doc_coverage

Overview ¶

Package main: catalog walker.

loadCatalog builds the canonical action catalog using the same options that the production server uses for the self-managed-enterprise tier, then snapshots every action's IndividualTool.Name, owning group, tier, and destructive flag into a flat lookup table for the auditor's main comparison loop.

Package main: per-doc parser.

Each docs/tools/<doc>.md file references its individual tools through one of three Markdown patterns:

• `### \`gitlab_<name>\“ heading with backticks (branches.md, tags.md, etc.)
• `### gitlab_<name>` heading without backticks (geo-model-registry.md)
• `| \`gitlab_<name>\` | ... |` row in a pipe table (analytics-compliance.md, enterprise-attestations.md)

parseDocTools returns the union of all `gitlab_*` names that appear in any of these positions within the file. Tier badge parsing is best-effort and looks for the canonical "Premium"/"Ultimate" tokens near each heading.

Package main implements the audit_doc_coverage command.

audit_doc_coverage reports per-doc-file gaps between docs/reference/tools/<doc>.md and the canonical action catalog. It produces plan/docs-tools-backlog.json (gitignored) listing, per file:

• missing: catalog tools expected in the doc but not documented
• orphan: tool headings/rows in the doc that do not belong there
• tier_mismatch: best-effort detection of catalog tier vs doc tier badge
• count_doc vs count_catalog vs readme_count for triple-cross-check

The auditor exits non-zero under -check when any file has missing, orphan, or tier_mismatch findings, providing a CI gate that mirrors audit-discovery-check / audit-action-spec-coverage.

Usage:

go run ./cmd/audit_doc_coverage/                     # full report to stdout
go run ./cmd/audit_doc_coverage/ -gaps-only          # only files with findings
go run ./cmd/audit_doc_coverage/ -output plan/docs-tools-backlog.json
go run ./cmd/audit_doc_coverage/ -check              # CI gate

Package main: README "Domains" table parser + group→doc mapping.

The mapping is derived from docs/reference/tools/README.md. Most rows list one or more gitlab_* meta-tool names that map directly to catalog groups; a handful of rows use "various" or include routed tools that must be split off their owning group. Both cases are enumerated explicitly here so the auditor's main logic stays table-driven and the special cases are reviewable in one place.