Audit CLI & CI/CD
unschema-graph includes a dedicated command-line audit tool to verify your static build output directory (e.g. dist/ or build/) before deploying to production.
1. Running the Audit
Section titled “1. Running the Audit”After running your production build, execute the audit CLI:
pnpm
pnpm exec unschema-graph audit distnpm / npx
npx @unschema-graph/core audit distyarn
yarn unschema-graph audit distbun
bunx @unschema-graph/core audit distYou can specify any target output folder:
npx @unschema-graph/core audit ./buildUse the same sequence everywhere:
- Local check: build the site, then audit its output directory.
- Production build: run the audit immediately after the build, before deployment.
- CI: keep build and audit as separate steps so a failure is easy to locate.
Useful options:
# Treat duplicate-ID warnings as failuresnpx @unschema-graph/core audit dist --strict
# Emit a stable machine-readable reportnpx @unschema-graph/core audit dist --format jsonIn the unschema-graph repository, the root scripts deliberately separate the two modes:
pnpm run auditis the convenient local-development check; it reports warnings without failing.pnpm run audit:strictis used by CI andpnpm run release:check; warnings and errors both fail the gate.
2. What the Audit Validates
Section titled “2. What the Audit Validates”The audit engine performs structural and graph-level verification across all compiled output:
- HTML File Discovery: Recursively scans directories to discover every
.htmlfile. - Script Block Extraction: Detects
<script type="application/ld+json">blocks across discovered HTML files. - JSON Syntax Validation: Confirms that each block is well-formed JSON without truncation or syntax errors.
- Root Context Presence: Checks the presence of the required
@contextproperty. - Entity Node Type Presence: Verifies that root entities and
@graphnodes declare a@typeproperty. - Graph Structure Integrity: Detects malformed graph payloads (such as non-array
@graphproperties). - Local Reference Resolution: Detects broken provably-local references (
#idor same-document URIs). - Identity and Conflict Detection: Identifies duplicate
@iddeclarations and conflicting values for identical IDs. - Deterministic Reporting: Emits structured diagnostics with exact file paths, codes, and severity levels.
- Strict Enforcement: Supports a strict warnings-as-errors mode (
--strict) for release gates and CI.
Explicit Non-Goals
Section titled “Explicit Non-Goals”The audit focuses strictly on JSON-LD structure and internal graph integrity. As detailed in Known Limitations, the audit does not provide:
- Full Schema.org vocabulary or property-range semantic validation.
- Verification of HTML syntax conformance or full DOM parsing.
- Google Rich Result eligibility or search display guarantees.
- External URL reachability or network-level checks.
3. Exit Codes
Section titled “3. Exit Codes”0(Success): No error was found; warnings are allowed unless--strictis set.1(Audit failure): Invalid JSON-LD, a broken reference, an ID conflict, no HTML/JSON-LD, or a warning under--strict.2(Usage failure): Unknown option, invalid format, or extra positional argument.
Expected output
Section titled “Expected output”A successful run ends with a summary of the scanned HTML files, JSON-LD blocks and entities, followed by a success message. The exact counts depend on the site:
✓ 24 HTML files scanned✓ 18 JSON-LD blocks parsed✓ 7 local graph references resolved✓ 42 Schema.org entities foundOn failure, the report names the affected file and explains the malformed block or graph. Treat the exit code—not the example wording above—as the stable contract for scripts and CI.
4. Continuous Integration (CI/CD)
Section titled “4. Continuous Integration (CI/CD)”In package.json
Section titled “In package.json”Add a post-build check that runs automatically during every build:
{ "scripts": { "build": "astro build", "postbuild": "unschema-graph audit dist" }}GitHub Actions Workflow
Section titled “GitHub Actions Workflow”Add an automated check in your GitHub Actions pipeline:
name: CI & Schema Audit
on: push: branches: [main] pull_request: branches: [main]
jobs: build-and-audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - uses: actions/setup-node@v4 with: node-version: 22 cache: 'pnpm'
- run: pnpm install --frozen-lockfile - run: pnpm run build - name: Audit Schema.org JSON-LD run: npx @unschema-graph/core audit dist --strict