Tag Audit

Inspect every frontmatter tag against the project vocabulary — unknowns, near-duplicates, and orphans.

What the Audit Reports

pnpm tags:audit runs the package-owned audit CLI. It walks the content directories declared by the default TagCliConfig export in src/config/tag-vocabulary.ts, collects the tags: arrays from each page's frontmatter, and reports three kinds of finding against that module's named tagVocabulary export.

• Unknown tags — the string does not exactly match a canonical id. Either add a vocabulary entry, replace it with the intended id, or remove it from the page. Under tagGovernance: "strict", unknowns fail the build.

• Near-duplicates — two distinct tags that look like variants of each other (high string similarity, or the same singular form). Pick one canonical id and update the content using the other.

• Orphan vocabulary entries — canonical ids that no page references. Remove an entry only after updating or removing every reference.

A clean run prints ✓ No tag issues found.

CLI Config and Package Script

The scaffold binds the explicit config module in package.json:

{
  "scripts": {
    "tags:audit": "tags-audit --config src/config/tag-vocabulary.ts"
  }
}

The config path is resolved from the project root. The CLI exits with a clear error if --config is missing, cannot be loaded, or does not default-export a valid TagCliConfig. Keep the named tagVocabulary export too—the generated zfb.config.ts consumes the same module, so runtime governance and CLI auditing share one source of truth.

Options can be forwarded through the package manager with --, which works consistently with pnpm and npm:

Reading the Report

The default output is colorized text grouped by category. For machine consumption, pass --json:

pnpm tags:audit -- --json > audit.json

The JSON payload is an AuditReport with unknowns, nearDuplicates, orphans, filesScanned, and an exact-id frequency map. This is what CI dashboards should consume.

CI Integration via b4push

The project's pre-push validation script (pnpm b4push) runs the audit with --ci:

pnpm tags:audit -- --ci

--ci forces a non-zero exit on any hard issue (an unknown tag) regardless of the configured tagGovernance mode. This means:

• Under tagGovernance: "warn" — pnpm build still passes with unknowns present (intentional, so migrations aren't blocked), but pnpm b4push refuses to push them.

• Under tagGovernance: "strict" — the build already fails on unknowns; --ci keeps b4push aligned when enforcement is later relaxed.

This two-layer setup — lenient build, strict push — is the sweet spot for multi-author doc bases: drafts can experiment locally without fighting Zod, but no broken tags make it onto main.

Related

• Tag governance — vocabulary file, governance modes, the faceted tag pattern.

• Tag suggestions — opt-in LLM helper for picking canonical tags on new pages.