astro-post-audit

Fast, offline post-build auditor for Astro sites — SEO signals, internal link consistency, and lightweight WCAG heuristics against your dist/ output, with 33 check modules covering structured data, performance, privacy, and more. Static analysis only: no browser, and no network calls unless opt-in external-link checking is enabled — runs in <1s on typical sites. Recent releases added per-route CSS payload analysis, static Astro/Tailwind source analysis, offline HTML5 conformance validation, and C2PA Content Credentials verification.

What's new in 0.6.0

| Area | What | Rule IDs | How to enable | |------|------|----------|---------------| | Speed mode | New mode: 'fast' \| 'full' top-level option, orthogonal to preset. 'fast' forcibly disables rules.html_validation regardless of how it's configured, for quick local/dev builds on large sites. 'full' (default) is unchanged behavior | — | mode: 'fast'. See Speed mode |

What's new in 0.5.7

| Area | What | Rule IDs | How to enable | |------|------|----------|---------------| | CSS architecture | Measures directly referenced local stylesheets and inline CSS per route, with configurable payload limits and median-based outlier detection | css-architecture/route-payload, css-architecture/route-outlier | rules.css_architecture.enabled | | Tailwind source analysis | Handles normal Astro class:list expressions, ignores build/dependency directories, distinguishes justify-* properties, and detects same-axis spacing conflicts | source-analysis/utility-conflict, inventory and complexity rules | rules.source_analysis.enabled | | Defaults and schema | Runtime, TypeScript and JSON Schema defaults are aligned and covered by regression tests | — | Automatic | | Render blocking | Removes the blanket recommendation to preload every stylesheet; sync scripts and missing third-party preconnects remain checked | render-blocking/sync-head-scripts, render-blocking/missing-preconnect | rules.render_blocking.enabled |

What's new in 0.5.5

| Area | What | Rule IDs | How to enable | |------|------|----------|---------------| | Content-style config | density_per_1000_words now matches the documented TypeScript/schema value; invalid JavaScript rule types fail early | content-style/* | Automatic | | Astro islands | Framework-generated client-island runtime styles no longer produce HTML conformance findings | html/schema.html5 | Automatic when rules.html_validation.enabled | | HTML validation docs | Clarifies body-level <style> handling and the intentional role="list" accessibility workaround | html/assertion.roles.unnecessary-list | See HTML5 conformance validation |

See C2PA provenance for the full configuration.

Earlier releases (0.3.0–0.5.4) added, among other things: C2PA Content Credentials verification (rules.c2pa), expanded offline HTML5 conformance validation (rules.html_validation), static Astro/Tailwind source analysis (rules.source_analysis, see Source analysis), font-loading and View Transitions checks, AI visibility and UX heuristics, opt-in content-style heuristics for "reads like AI" writing, redirect/robots.txt/hreflang/GDPR checks, and the default-on accessibility and image checks described in Configuration below. Full history: GitHub Releases.

Installation

npm i -D @casoon/astro-post-audit

Setup

// astro.config.mjs
import { defineConfig } from 'astro/config';
import postAudit from '@casoon/astro-post-audit';

export default defineConfig({
  site: 'https://example.com',
  integrations: [postAudit()],
});

That's it. The audit runs automatically after every astro build.

Note: If you use @astrojs/sitemap, make sure postAudit() comes after sitemap() in the integrations array. Both plugins use the astro:build:done hook and run in array order — the sitemap file needs to exist before the audit can check it.

Skipping the audit

Set the SKIP_AUDIT environment variable to skip the audit for a single build. Useful for quick dev builds when external link checking would slow things down:

SKIP_AUDIT=1 astro build

Or add a dedicated script to your package.json:

{
  "scripts": {
    "build": "astro build",
    "build:fast": "SKIP_AUDIT=1 astro build"
  }
}

Then run npm run build:fast (or pnpm build:fast) when you want to skip the audit.

You can also disable the audit permanently via config: postAudit({ disable: true }).

Presets

Use a preset to start with a predefined configuration. Individual rules override preset defaults.

postAudit({ preset: 'standard' })

// Preset + custom overrides
postAudit({
  preset: 'seo',
  rules: {
    headings: { no_skip: true },   // add a rule on top of the preset
  },
})

| Preset | What it enables | |--------|----------------| | standard | Comprehensive quality checks without aggressive extras. Canonical self-reference, heading gaps, meta description, Open Graph (title/description/image + absolute image URL + twitter card validation), a11y (skip link, img alt, button/label names, landmark structure, duplicate IDs, ARIA roles), image dimensions/lazy loading, fragment validation, sitemap, security (target-blank), hreflang, assets, JSON-LD, content quality (duplicate titles/descriptions/H1). Warnings stay warnings. | | strict | Everything in standard plus orphan detection, extended robots.txt (disallow-all, crawl-delay), inline-script warnings, Twitter Card, OG type/url requirements, structured data property completeness, i18n audit, crawl budget, render blocking, privacy/security, structured data graph. Sets strict: true (warnings become errors). | | production | Alias for strict. | | seo | SEO signals only — canonical (self-reference, clusters), html basics (lang, title, meta description, viewport, length limits), Open Graph (all four tags), JSON-LD syntax, sitemap. | | accessibility | WCAG heuristics — lang attr, title, viewport, heading hierarchy (H1 required, single, no gaps), full a11y ruleset (img alt, link/button names, form labels, generic link text, aria-hidden, skip link, landmark structure, duplicate IDs, ARIA roles), fragment validation. | | performance | Static performance signals — broken asset references, missing image dimensions (CLS), lazy loading, srcset hints, hashed filenames, render blocking scripts. | | relaxed | Core SEO and link checks only. No heading gaps, no Open Graph, no structured data, no content quality. Broken links are warnings, not errors. Good starting point for existing sites with known issues. | | editorial | Enables the content_style module with its built-in ruleset (em-dash density, contrast-formula repetition, chatbot leftovers). Doesn't touch any other check — combine with standard/seo via rules overrides. See Content style. |

Speed mode

mode is orthogonal to preset: it's a speed switch, not a rule-set choice. On large sites, rules.html_validation (full HTML5 conformance validation, opt-in) can dominate build time — it runs a RELAX NG content-model check per page and scales with page count. mode: 'fast' disables it unconditionally, even if rules.html_validation.enabled: true is set elsewhere (e.g. inherited from a preset or a shared config), which makes it a safe one-line override for local/dev builds without touching the rest of the config. mode: 'full' (the default) leaves your config untouched.

// astro.config.mjs
postAudit({
  preset: 'seo',
  mode: process.env.POST_AUDIT_FAST === '1' ? 'fast' : 'full',
  rules: {
    html_validation: { enabled: true }, // still off when mode: 'fast'
  },
})

POST_AUDIT_FAST=1 pnpm build   # fast: skips html_validation
pnpm build                     # full: runs everything as configured

Example configurations

A working reference implementation can be found in casoon/astro-v6-template.

Simple site

Minimal config for a small personal or marketing site — the relaxed preset covers core SEO with lenient settings, then we add a meta description requirement on top.

postAudit({
  preset: 'relaxed',
  failOn: 'errors',
  rules: {
    filters: { exclude: ['404.html'] },
    html_basics: { meta_description_required: true },
    sitemap: { require: true },
  },
})

Blog with Content Collections

The seo preset handles canonical, html basics, Open Graph, JSON-LD and sitemap. Source-file hints show MDX paths next to dist/ findings.

postAudit({
  preset: 'seo',
  failOn: 'errors',
  hints: { sourceFiles: true },
  rules: {
    filters: { exclude: ['404.html', 'blog/index.html'] },
    headings: { no_skip: true },
    content_quality: {
      detect_duplicate_titles: true,
      detect_duplicate_descriptions: true,
    },
  },
})

Multilingual site (hreflang)

The standard preset already includes hreflang (self-reference, x-default, reciprocal). Only exclusions and failOn need to be set.

postAudit({
  preset: 'standard',
  failOn: 'errors',
  rules: {
    filters: { exclude: ['404.html'] },
  },
})

Accessibility-focused

The accessibility preset covers the full WCAG heuristic ruleset. Add seo rules on top if needed.

postAudit({
  preset: 'accessibility',
  failOn: 'errors',
  rules: {
    filters: { exclude: ['404.html'] },
    html_basics: { meta_description_required: true },
    sitemap: { require: true },
  },
})

Strict production gate

production (= strict) enables everything. Only additional opt-in checks and output config need to be specified.

postAudit({
  preset: 'production',
  failOn: 'errors',
  maxWarnings: 0,
  hints: { sourceFiles: true },
  reports: {
    json: 'audit-report.json',
    sarif: 'audit.sarif',
  },
  rules: {
    filters: { exclude: ['404.html'] },
    external_links: { enabled: true, fail_on_broken: true },
  },
})

AI-optimised content

Enable AI visibility checks for content that should surface well in LLM-generated answers. Useful for documentation, blogs, and product pages targeting AI-assisted search.

postAudit({
  preset: 'seo',
  failOn: 'errors',
  aiVisibility: true,
  rules: {
    filters: { exclude: ['404.html'] },
    headings: { no_skip: true },
    structured_data: { check_json_ld: true },
  },
})

aiVisibility: true enables the opt-in AI visibility module, which checks LLM-readability (word count, lang attribute), citability (og:title, og:description, canonical, author schema), chunk quality (semantic sectioning, heading structure on long pages), and AI bot policy in robots.txt.

UX heuristics for marketing sites

Enable UX heuristics to catch missing calls-to-action, generic link text, and missing trust signals:

postAudit({
  preset: 'standard',
  failOn: 'errors',
  uxHeuristics: {
    maxLinksPerPage: 60,
    minCtaPerPage: 2,
  },
  rules: {
    filters: { exclude: ['404.html'] },
  },
})

Pass uxHeuristics: true to use the defaults (maxLinksPerPage: 80, minCtaPerPage: 1), or pass an object to override them.

Environment-based gate (dev / staging / prod)

Use plain JavaScript in astro.config.mjs — no profile system needed. The goLive option automatically uses Astro's site as the expected production origin so you don't have to repeat the domain.

const isProd = process.env.DEPLOY_CONTEXT === 'production'

postAudit({
  preset: isProd ? 'production' : 'relaxed',
  failOn: isProd ? 'errors' : 'never',
  maxWarnings: isProd ? 0 : undefined,
  goLive: {
    enabled: isProd,
    forbiddenDomains: ['staging.example.com', 'localhost'],
  },
})

When goLive.enabled is true, the integration verifies that the expected production origin matches:

1. goLive.expectedSite — only needed when the go-live target differs from Astro's site config
2. Astro config.site — used automatically otherwise

If neither is set and goLive.enabled is true, the audit fails with a config error.

Environment selection always belongs in astro.config.mjs via normal JavaScript — the plugin does not have a built-in profile system. If you find yourself duplicating a lot of config across environments, a profile system may be worth revisiting in a future release.

Production rollout

The new dist-only audits (i18n_audit, crawl_budget, render_blocking, privacy_security, structured_data_graph) are intentionally heuristic. They are useful in production, but best rolled out in two steps.

Step 1: Recommended baseline (warn-first)

postAudit({
  failOn: 'never',
  reports: { json: 'audit-report.json' },
  rules: {
    i18n_audit: { enabled: true },
    crawl_budget: { enabled: true },
    render_blocking: { enabled: true },
    privacy_security: { enabled: true },
    structured_data_graph: { enabled: true },
    severity: {
      'privacy-security/third-party-domains': 'info',
      'crawl-budget/noindex-with-internal-demand': 'info',
    },
  },
})

Step 2: Strict gate (after tuning)

postAudit({
  failOn: 'errors',
  maxErrors: 50,
  rules: {
    i18n_audit: { enabled: true },
    crawl_budget: { enabled: true },
    render_blocking: { enabled: true },
    privacy_security: { enabled: true },
    structured_data_graph: { enabled: true },
    severity: {
      'privacy-security/missing-sri-script': 'error',
      'privacy-security/missing-sri-stylesheet': 'error',
      'structured-data-graph/type-conflict': 'error',
      'crawl-budget/redirect-target-missing': 'error',
    },
  },
})

Configuration

All options are optional. Your editor provides autocomplete with descriptions and concrete defaults where a field has one.

postAudit({
  preset: 'standard',        // Apply a predefined config (see Presets)
  failOn: 'errors',          // Fail the build on errors (or 'warnings' / 'never')
  maxErrors: 20,             // Stop after 20 errors
  reports: {                 // Write report files (multiple formats at once)
    json: 'audit-report.json',
    markdown: 'audit-summary.md',
    sarif: 'audit.sarif',
  },
  benchmark: true,           // Print per-check timing breakdown
  pageOverview: true,        // Show page properties overview instead of checks
  rules: {
    filters: { exclude: ['404.html', 'drafts/**'] },
    canonical: { self_reference: true },
    a11y: { require_skip_link: true },
    assets: { check_broken_assets: true, check_image_dimensions: true },
    structured_data: { check_json_ld: true },
    security: { check_target_blank: true },
    content_quality: { detect_duplicate_titles: true },
    opengraph: { require_og_title: true, require_og_image: true },
    external_links: { enabled: true, timeout_ms: 5000 },
    headings: { no_skip: true },
    severity: {
      'html/title-too-long': 'off',
      'a11y/img-alt': 'error',
    },
  },
})

Top-level options reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | preset | 'standard' \| 'strict' \| 'production' \| 'seo' \| 'accessibility' \| 'performance' \| 'relaxed' \| 'editorial' | — | Apply a predefined config before your rules overrides. See Presets. | | mode | 'fast' \| 'full' | 'full' | Orthogonal to preset. 'fast' forcibly disables checks known to be expensive on large sites (currently rules.html_validation), regardless of how they're configured. See Speed mode. | | strict | boolean | false | Treat warnings as errors (exit code 1). | | throwOnError | boolean | false | Throw an error (fail the build) when the audit finds issues. Ignored when failOn is set. | | failOn | 'errors' \| 'warnings' \| 'never' | — | Fail on errors only, on warnings and errors, or never. Takes precedence over throwOnError; 'warnings' always implies strict mode. | | maxErrors | number | — | Truncate output after this many errors. | | maxWarnings | number | — | Fail the build if the warning count exceeds this number. Activates build gating unless failOn: 'never' is set. | | site | string | auto | Base URL — auto-detected from Astro's site config. | | reports | ReportsConfig | — | Write report files. See Report files. | | output | string | — | Write a JSON report to this path. Legacy alias for reports.json. | | baseline | string | — | Path to a baseline file. Only new findings since the baseline are reported. | | writeBaseline | boolean | false | Write current findings as the new baseline and exit 0. Run once to adopt the plugin on a site with existing issues. | | hints.sourceFiles | boolean | false | Show likely source file paths (e.g. src/content/blog/post.mdx) next to dist/ findings. Heuristic — may not always match. | | groups | GroupsConfig | — | Enable rule groups: seo, a11y, links, performance, privacy. true enables the group, "warn" enables but downgrades all findings to warnings. | | goLive | GoLiveConfig | — | Production readiness gate. See Go-live gate. | | pageOverview | boolean | false | Print a page properties table (title, description, canonical, OG, H1, lang, JSON-LD) instead of running checks. | | benchmark | boolean | false | Print per-check timing breakdown. | | progress | boolean | auto | Live progress bar on stderr while checks run. Auto-on in an interactive terminal, silent in CI. Set true/false to force. | | debug | boolean | false | Verbose diagnostics on stderr (resolved config, discovery stats, per-check counts/timings). Never touches the stdout report; replaces the progress bar. See Diagnostics. | | aiVisibility | boolean | false | Enable AI visibility checks (LLM-readability, citability, chunk quality). See AI visibility. | | uxHeuristics | boolean \| { maxLinksPerPage?: number, minCtaPerPage?: number } | false | Enable UX heuristic checks (CTAs, generic link text, trust signals). See UX heuristics. | | contentStyle | boolean | false | Enable content style checks (recurring "reads like AI" writing patterns). See Content style. | | disable | boolean | false | Disable the integration entirely. | | rules | RulesConfig | — | Inline check configuration — see full reference below. |

Baseline workflow

Use baseline + writeBaseline to adopt the plugin on a site that already has findings:

// Step 1: write the current state as a baseline (run once)
postAudit({ writeBaseline: true, baseline: '.audit-baseline.json' })

// Step 2: from now on, only new findings are reported
postAudit({ baseline: '.audit-baseline.json' })

Commit .audit-baseline.json to version control. Delete entries from it to re-enable specific checks.

Groups shorthand

postAudit({
  groups: {
    seo: true,           // enable all SEO rules
    a11y: 'warn',        // enable a11y rules but never block the build
    performance: true,
  },
})

Go-live gate

The goLive option adds a set of production-readiness checks that run only when enabled: true. These checks catch staging/dev leftovers before a build goes to production.

| Field | Type | Default | Description | |-------|------|---------|-------------| | goLive.enabled | boolean | false | Enable go-live checks. | | goLive.expectedSite | string | auto | Expected production origin. Defaults to Astro's site config. Only set this when the go-live target differs from Astro site. | | goLive.forbiddenDomains | string[] | [] | Domains that must not appear in canonical URLs, sitemaps, OG tags, or absolute links. |

What it checks (rule IDs prefixed with golive/):

| Rule ID | Description | |---------|-------------| | golive/noindex | Page has a noindex robots directive | | golive/canonical-origin | Canonical URL uses the wrong origin | | golive/og-origin | og:url or og:image uses the wrong origin | | golive/sitemap-origin | Sitemap entry uses the wrong origin | | golive/forbidden-domain | Absolute link, script, canonical, or sitemap entry contains a forbidden domain | | golive/robots-blocked | robots.txt globally blocks crawlers with Disallow: / | | golive/config-missing-site | goLive.enabled is true but no expected site could be resolved |

All go-live findings are errors (exit code 1). They cannot be downgraded via severity overrides — they are explicit production gates.

Full rules reference

All fields are optional — shown here with their defaults.

rules: {
  // Site settings
  site: {
    base_url: undefined,               // Auto-detected from Astro's `site` config
  },

  // File filters
  filters: {
    include: [],                        // Glob patterns to include
    exclude: [],                        // Glob patterns to exclude (e.g. ["404.html", "drafts/**"])
  },

  // URL normalization
  url_normalization: {
    trailing_slash: 'always',           // 'always' | 'never' | 'ignore'
    index_html: 'forbid',              // 'forbid' | 'allow'
  },

  // Canonical tag checks
  canonical: {
    require: true,                      // Every page must have a canonical tag
    absolute: true,                     // Canonical URL must be absolute
    same_origin: true,                  // Must point to same origin as site
    self_reference: false,              // Must be a self-referencing canonical
    detect_clusters: true,              // Warn when multiple pages share the same canonical
  },

  // Robots meta
  robots_meta: {
    allow_noindex: true,                // Don't warn on noindex pages
    fail_if_noindex: false,             // Treat noindex as error
  },

  // Internal link checks
  links: {
    check_internal: true,               // Verify internal links resolve
    fail_on_broken: true,               // Broken links are errors (not warnings)
    forbid_query_params_internal: true,  // Warn on ?query in internal links
    check_fragments: false,             // Validate #fragment targets exist
    detect_orphan_pages: false,         // Warn about pages with no incoming links
    check_mixed_content: true,          // Warn on http:// in internal links
    max_url_depth: undefined,           // Warn when URL nesting depth exceeds this (e.g. 3)
    known_routes: [],                   // Glob patterns for known SSR/dynamic routes (e.g. ['/dashboard/'])
                                         // excluded from links/broken and sitemap/entry-not-in-dist
  },

  // Sitemap cross-reference
  sitemap: {
    require: false,                     // sitemap.xml must exist
    canonical_must_be_in_sitemap: true,  // Canonical URLs should appear in sitemap
    forbid_noncanonical_in_sitemap: false, // Sitemap must not contain non-canonical URLs
    entries_must_exist_in_dist: true,    // Sitemap URLs must correspond to pages
  },

  // robots.txt
  robots_txt: {
    require: false,                     // robots.txt must exist
    require_sitemap_link: false,        // Must contain a sitemap link
    check_disallow_all: true,           // Error when User-agent: * blocks everything
    max_crawl_delay: 10,                // Warn when Crawl-delay exceeds this value (seconds)
    ai_bot_policy: false,               // Check AI bot (GPTBot, ClaudeBot, CCBot …) rules
    check_noindex_contradiction: false, // Error when a Disallow'd page also has noindex
    check_sitemap_blocked: false,       // Warn when a sitemap URL is blocked by robots.txt
  },

  // HTML basics
  html_basics: {
    lang_attr_required: true,           // <html lang="..."> required
    title_required: true,               // <title> required and non-empty
    meta_description_required: false,   // <meta name="description"> required
    viewport_required: true,            // <meta name="viewport"> required
    title_max_length: 60,               // Warn if title exceeds this length
    meta_description_max_length: 160,   // Warn if description exceeds this length
  },

  // Heading hierarchy
  headings: {
    require_h1: true,                   // Page must have at least one <h1>
    single_h1: true,                    // Only one <h1> per page
    no_skip: false,                     // No heading level gaps (h2 → h4)
  },

  // Accessibility
  a11y: {
    img_alt_required: true,             // <img> must have alt attribute
    allow_decorative_images: true,      // role="presentation" skips alt check
    a_accessible_name_required: true,   // <a> must have accessible name
    button_name_required: true,         // <button> must have accessible name
    label_for_required: true,           // Form controls need associated <label>
    warn_generic_link_text: true,       // Warn on "click here", "mehr", "weiter"
    aria_hidden_focusable_check: true,  // Warn on aria-hidden on focusable elements
    require_skip_link: false,           // Require skip navigation link
    check_landmarks: true,              // Require proper landmark structure (<main>, <nav>, …)
    check_duplicate_ids: true,          // Error on duplicate id attributes
    check_aria_roles: true,             // Validate role= values against WAI-ARIA spec
    check_alt_quality: true,            // Warn on filename/placeholder/too-short alt text
  },

  // Asset checks
  assets: {
    check_broken_assets: false,         // Verify img/script/link references
    check_image_dimensions: false,      // Warn on missing width/height (CLS)
    max_image_size_kb: undefined,       // Warn if image exceeds size in KB
    max_js_size_kb: undefined,          // Warn if JS file exceeds size in KB
    max_css_size_kb: undefined,         // Warn if CSS file exceeds size in KB
    require_hashed_filenames: false,    // Warn if filenames lack cache-busting hash
  },

  // Open Graph & Twitter Cards
  opengraph: {
    require_og_title: false,            // Require og:title
    require_og_description: false,      // Require og:description
    require_og_image: false,            // Require og:image
    require_twitter_card: false,        // Require twitter:card
    require_og_type: false,             // Require og:type
    require_og_url: false,              // Require og:url
    og_image_absolute_url: true,        // og:image must be an absolute URL
    require_twitter_image: false,       // Require twitter:image
    twitter_card_valid_values: true,    // Validate twitter:card value against the spec
    og_title_consistency: false,        // Warn when og:title and <title> differ significantly
    check_image_exists: false,          // Verify a local og:image exists in dist
    check_image_dimensions: false,      // Warn if local og:image is below 1200×630
    og_image_max_size_kb: undefined,    // Warn if local og:image exceeds this size in KB
  },

  // Structured data (JSON-LD)
  structured_data: {
    check_json_ld: false,               // Validate JSON-LD syntax and semantics
    require_json_ld: false,             // Every page must have JSON-LD
    detect_duplicate_types: false,      // Warn on duplicate @type per page
  },

  // Hreflang (multilingual sites)
  hreflang: {
    check_hreflang: false,              // Enable hreflang checks
    require_x_default: false,           // Require x-default entry
    require_self_reference: false,      // Must include self-referencing entry
    require_reciprocal: false,          // Links must be reciprocal (A→B and B→A)
    require_target_exists: false,       // Warn when an internal hreflang target is missing
  },

  // Security
  security: {
    check_target_blank: true,           // Warn on target="_blank" without rel="noopener"
    check_mixed_content: true,          // Warn on http:// resource URLs
    warn_inline_scripts: false,         // Warn on inline <script> tags
  },

  // Content quality
  content_quality: {
    detect_duplicate_titles: false,     // Warn on duplicate <title> across pages
    detect_duplicate_descriptions: false, // Warn on duplicate meta descriptions
    detect_duplicate_h1: false,         // Warn on duplicate <h1> across pages
    detect_duplicate_pages: false,      // Warn on identical page content
  },

  // External link checking (network requests)
  external_links: {
    enabled: false,                     // Enable external link checking via HEAD requests
    timeout_ms: 3000,                   // Timeout per request in milliseconds
    max_concurrent: 10,                 // Maximum concurrent requests
    fail_on_broken: false,              // Broken external links are errors (not just warnings)
    allow_domains: [],                  // Only check links to these domains (empty = all)
    block_domains: [],                  // Skip links to these domains
  },

  // Image checks (HTML attribute-level)
  images: {
    check_missing_dimensions: true,     // Error on <img> without width/height (CLS risk)
    warn_missing_lazy: true,            // Warn when images below the fold lack loading="lazy"
    info_missing_srcset: true,          // Info when <img> has no srcset (responsive images)
    format_hints: false,                // Info hint when JPEG/PNG/GIF could use a modern format
  },

  // C2PA Content Credentials — opt-in module
  c2pa: {
    enabled: false,                     // Validate embedded Content Credentials in local JPEG/PNG/WebP assets
    require_for: [],                    // Dist-relative image globs for which credentials are expected, e.g. ["blog/**/*.jpg"]
    require_trusted: false,             // Also flag Valid-but-not-Trusted manifests (e.g. self-signed certs)
  },

  // AI Visibility — opt-in module
  // Enable via top-level aiVisibility option or set enabled: true here
  ai_visibility: {
    enabled: false,                     // Enable AI visibility checks
    require_llms_txt: true,             // Require llms.txt or llms-full.txt and validate internal links
  },

  // UX Heuristics — opt-in module
  // Enable via top-level uxHeuristics option or set enabled: true here
  ux_heuristics: {
    enabled: false,                     // Enable UX heuristic checks
    max_links_per_page: 80,             // Info when a page exceeds this link count
    min_cta_per_page: 1,                // Warn when a page has fewer CTAs than this
  },

  // Content Style — opt-in module, heuristics for recurring "reads like AI" writing patterns
  // Enable via top-level contentStyle option or set enabled: true here
  content_style: {
    enabled: false,                     // Enable content style checks
    content_selector: "article, main, .prose", // Default: prefer article, then main, then .prose
    exclude: [],                        // Dist-relative globs to skip only this check, e.g. ["tags/**"]
    // rules: [...],                    // Replaces the built-in ruleset entirely when set (even to [])
    // extra_rules: [                   // Always appended to whichever ruleset is in effect
    //   { id: "custom-word", type: "presence", pattern: "unleash", level: "warning" },
    // ],
    disabled_rules: [],                 // Disable built-in/custom rules by short ID
    language_detection: {
      enabled: true,                    // Compare German/English text signals with html[lang]
      min_signal_words: 12,             // Require this many signals for the other language
      mismatch_ratio: 2,                // Other-language signals must be this many times higher
    },
  },

  // Font loading checks — opt-in
  fonts: {
    enabled: false,
    check_font_display: true,           // Warn when an @font-face block has no font-display
    require_font_preload: true,         // Info when self-hosted fonts have no preload hint
  },

  // Astro View Transitions checks — opt-in
  view_transitions: {
    enabled: false,
    check_duplicate_names: true,        // Error for duplicate transition:name values on one page
    check_external_reload: true,        // Info for external links missing data-astro-reload
  },

  // Static Astro/Tailwind source analysis — opt-in (needs project root, passed automatically)
  source_analysis: {
    enabled: false,
    extensions: [],                     // Additional source file extensions to inspect (without leading dot)
    exclude: [],                        // Additional globs; build/dependency directories are always excluded
    tailwind_inventory: true,           // Emit a compact Tailwind utility inventory
    duplicate_signatures: true,         // Report exact repeated static class signatures
    utility_conflicts: true,            // Report duplicate/mutually exclusive utility tokens
    component_complexity: true,         // Report components crossing complexity thresholds
    min_duplicate_occurrences: 3,       // Minimum occurrences before a repeated signature is reported
    max_component_lines: 300,           // Advisory source-line threshold
    max_component_props: 12,            // Advisory declared Props member threshold
    max_component_slots: 6,             // Advisory named-slot threshold
  },

  // Innovative dist-only audits
  i18n_audit: {
    enabled: false,                     // lang/hreflang/canonical consistency by locale route
  },
  crawl_budget: {
    enabled: false,                     // URL variants, duplicate clusters, indexability mismatches
  },
  render_blocking: {
    enabled: false,                     // Sync head scripts and missing preconnect hints
  },
  css_architecture: {
    enabled: false,                     // Per-route local and inline CSS payload
    max_route_kb: 50,                   // Warning threshold per route
    detect_route_outliers: true,        // Compare route payloads with the site median
    outlier_factor: 2,                  // Required multiple of the median
    min_outlier_kb: 20,                 // Ignore small absolute differences
  },
  privacy_security: {
    enabled: false,                     // Third-party domains, SRI/CSP readiness, consent indicators
    gdpr: false,                        // GDPR/DSGVO transfers: Google Fonts, YouTube, Maps, CDNs, external images
  },
  structured_data_graph: {
    enabled: false,                     // Cross-page JSON-LD entity consistency and missing internal URLs
  },

  // Static meta-refresh redirect analysis
  redirects: {
    enabled: false,                     // Links to redirect pages, redirect chains, loops
  },
  // Client-side JS bloat per route
  js_bloat: {
    enabled: false,                     // Warn when a route's total local JS is too large
    max_kb: 100,                        // Threshold in KB
  },
  // Content collection ↔ generated page sync (needs project root, passed automatically)
  content_sync: {
    enabled: false,                     // Warn about src/content items with no build page
  },
  // Native HTML5 conformance validation (offline, via html-conform, vnu-comparable)
  html_validation: {
    enabled: false,                     // Report HTML5 conformance findings
    max_per_page: 20,                   // Cap distinct findings reported per page
  },

  // Override severity per rule ID
  severity: {
    // 'rule-id': 'error' | 'warning' | 'info' | 'off'
  },
}

What it checks

• Note on signal type — Most checks are deterministic (broken links, missing tags). The five dist-only audits are heuristic by design and should be tuned via severity for your project.
• SEO — Canonical tags (including cluster detection), robots meta, URL normalization (trailing slash, index.html)
• Links — Broken internal links, query parameters, fragment validation, orphan pages, URL depth, links pointing at redirect pages
• External Links — HEAD requests to verify external URLs return 2xx, with domain filtering and concurrency control
• Sitemap — Cross-reference with canonical URLs, stale entries, missing pages
• robots.txt — Existence check, sitemap link, disallow-all detection, crawl-delay threshold, AI bot policy (GPTBot, ClaudeBot, CCBot …), noindex/Disallow contradiction, sitemap entries blocked by robots
• Redirects — Static meta-refresh redirect chains, loops, and internal links that point at redirect pages
• HTML — <html lang>, <title>, viewport, meta description, heading hierarchy, native HTML5 conformance validation (opt-in)
• Accessibility — img alt + alt-text quality heuristics, link/button names, form labels (including wrapping labels), generic link text, skip link, aria-hidden on focusable elements, landmark structure (<main>, <nav>, <header>, <footer>), duplicate IDs, WAI-ARIA role validation
• Open Graph — og:title, og:description, og:image (absolute URL + existence/dimensions/size), og:type, og:url, twitter:card (valid values), twitter:image, title consistency
• Structured Data — JSON-LD syntax, semantics, duplicate type detection, property completeness (author, datePublished, image, publisher, breadcrumb positions …)
• Images — Missing width/height attributes (CLS), missing loading="lazy", missing srcset, modern format hints
• Hreflang — Multilingual link validation, x-default, self-reference, reciprocal links, target existence
• Security — target="_blank" without noopener, mixed content, inline scripts
• Assets — Broken references, image dimensions, file size limits, cache-busting hashes
• Performance — Client-side JS and CSS payloads per route and font-loading hints (opt-in)
• Content Quality — Duplicate titles, descriptions, H1s, near-identical pages
• Content Sync (opt-in) — src/content/ collection items with no corresponding generated page
• Source Analysis (opt-in) — Static Astro/Tailwind source inventory: utility-family usage, exact duplicate class signatures, mutually exclusive utilities, and oversized components. Never executes JavaScript or guesses dynamic classes.
• I18n Audit — Consistency between localized routes, html[lang], hreflang, and canonical
• Crawl Budget — Query/variant URL dilution, duplicate canonical clusters, and indexability mismatches
• Render Blocking — Sync <head> scripts and missing preconnect hints for critical third-party resources
• Privacy/Security (Static) — Third-party domain inventory, missing SRI, CSP-readiness, consent signals, GDPR/DSGVO transfers (opt-in: Google Fonts, YouTube, Maps, public CDNs, external images)
• Structured Data Graph — Cross-page JSON-LD entity conflicts (@id, type/name/url) and missing internal entity URLs
• AI Visibility (opt-in) — LLM readability (word count, lang), citability (OG metadata, canonical, author schema), semantic structure, AI bot policy, and llms.txt / llms-full.txt link integrity
• UX Heuristics (opt-in) — Missing CTAs, generic link text ("click here", "mehr"), missing trust signals (Impressum, Datenschutz, contact), link density, interactive element density
• Content Style (opt-in) — Configurable heuristics for recurring "reads like AI" writing patterns: em-dash overuse, contrast-formula repetition ("nicht/kein X, sondern Y"), chatbot leftovers, uniform sentence rhythm
• View Transitions (opt-in) — Duplicate transition:name values and Client Router external-link reload hints
• C2PA Provenance (opt-in) — Local validation of embedded C2PA Content Credentials in JPEG, PNG, and WebP assets

HTML5 conformance validation

Enable rules.html_validation.enabled for offline content-model, parser, ARIA, attribute, and table validation. Astro's generated client-island runtime style (astro-island,astro-slot,astro-static-slot{display:contents}) is ignored automatically; other <style> elements in body content remain findings. Under the current HTML standard, <style> is metadata content and belongs in <head> (or a <noscript> in <head>), even when it is the first child of a body-level container. In Astro and MDX, use Astro's normal component-scoped <style> handling instead of emitting a raw body-level <style> tag.

html/assertion.roles.unnecessary-list reports an explicit role="list" on <ul>/<ol> as redundant according to ARIA-in-HTML. If the role is intentional to retain VoiceOver/Safari list semantics when CSS removes list markers, keep the workaround and tune only that finding:

rules: {
  html_validation: { enabled: true },
  severity: {
    "html/assertion.roles.unnecessary-list": "off",
  },
}

AI visibility

Enable via aiVisibility: true (top-level option) or rules.ai_visibility.enabled: true.

By default this also looks for dist/llms.txt or dist/llms-full.txt and validates their internal Markdown links. Set rules.ai_visibility.require_llms_txt: false to keep the other AI visibility checks without this file check.

| Rule ID | Level | Description | |---------|-------|-------------| | ai-visibility/missing-llms-txt | Info | Neither llms.txt nor llms-full.txt exists in dist/ | | ai-visibility/llms-txt-broken-link | Warning | An internal Markdown link in an LLM context file has no published target | | ai-visibility/low-word-count | Info | Page word count < 300 — may not be chunked by LLMs | | ai-visibility/lang-missing | Warning | Missing <html lang> — LLMs may not infer language | | ai-visibility/missing-og-title | Warning | No og:title — reduces citation quality | | ai-visibility/missing-og-description | Info | No og:description — reduces citation quality | | ai-visibility/missing-canonical | Warning | No canonical URL — LLMs may attribute content incorrectly | | ai-visibility/missing-author-schema | Info | No author in JSON-LD — reduces attribution quality | | ai-visibility/no-semantic-sections | Info | No <article> or <section> — poor chunk boundaries | | ai-visibility/no-subheadings | Warning | Long page with no H2/H3 — poor chunk quality | | ai-visibility/noindex-page | Info | Page is noindexed — will not be crawled by AI bots |

UX heuristics

Enable via uxHeuristics: true (top-level option) or rules.ux_heuristics.enabled: true. Pass an object to configure thresholds: uxHeuristics: { maxLinksPerPage: 60, minCtaPerPage: 2 }.

| Rule ID | Level | Description | |---------|-------|-------------| | ux/no-cta | Warning | Page has no call-to-action (links/buttons with CTA keywords) | | ux/generic-link-text | Warning | Link with generic text ("click here", "mehr", "weiter", "read more") | | ux/no-trust-signals | Warning | No links to Impressum, Datenschutz, contact, or about pages | | ux/high-link-density | Info | Link count exceeds max_links_per_page (default 80) | | ux/high-interactive-density | Info | More than 20 interactive elements on a single page |

Source analysis (Astro + Tailwind)

Enable via rules.source_analysis.enabled: true. Runs entirely offline against your Astro/Tailwind source files (needs the project root, which the integration passes automatically) and only evaluates quoted static class and class:list entries — it never executes JavaScript or guesses dynamic classes. .git, .astro, dist, node_modules, and target are always excluded; exclude adds project-specific globs. All findings are advisory info.

rules: {
  source_analysis: {
    enabled: true,
    exclude: ["src/components/generated/**"],
    min_duplicate_occurrences: 3,
    max_component_lines: 300,
  },
}

| Rule ID | Description | |---------|--------------| | source-analysis/tailwind-inventory | Utility-family inventory across quoted static class lists | | source-analysis/duplicate-signature | An exact class signature repeats at least min_duplicate_occurrences times (default 3) | | source-analysis/utility-conflict | Duplicate or mutually exclusive utilities within the same variant scope (e.g. p-2 p-4, block hidden) | | source-analysis/component-complexity | An Astro component exceeds max_component_lines (default 300), max_component_props (default 12), or max_component_slots (default 6) |

CSS architecture

Enable via rules.css_architecture.enabled: true. The check measures every route's directly referenced local stylesheets and inline <style> blocks. Repeated references to the same file on one page count once. External stylesheets and CSS loaded later by JavaScript are excluded because their size cannot be established reliably from dist/ alone.

rules: {
  css_architecture: {
    enabled: true,
    max_route_kb: 50,
    detect_route_outliers: true,
    outlier_factor: 2,
    min_outlier_kb: 20,
  },
}

| Rule ID | Level | Description | |---------|-------|-------------| | css-architecture/route-payload | Warning | Direct local and inline CSS exceeds max_route_kb | | css-architecture/route-outlier | Info | A route above min_outlier_kb exceeds the site median by outlier_factor |

Content style

Configurable heuristics for recurring "reads like AI" writing patterns. This is a stylistic signal, not a correctness check — every finding carries confidence: "low". Info-level findings do not affect --strict; the built-in chatbot-leftover rule is a warning and therefore does. Regex-based findings include a short excerpt around the first match so they can be reviewed in context.

Enable via contentStyle: true (top-level option), rules.content_style.enabled: true, or preset: 'editorial'. With the default content_selector (article, main, .prose), the audit prefers a semantic <article>, otherwise <main>, then .prose. It omits header, nav, aside and footer content as well as repeated linked card groups (three or more equal sibling cards with a link and H2/H3), so article teasers and a small related-content hub do not distort one continuous writing sample. A custom content_selector uses its outermost matches directly.

For archive or taxonomy pages whose card structure cannot be recognised reliably, use exclude with dist-relative globs. It only disables content-style checks for those pages; link, accessibility, SEO and all other checks still run. For example: exclude: ["tags/**", "serien/**"].

Tune built-in density rules without copying their regexes:

rules: {
  content_style: {
    enabled: true,
    thresholds: {
      em_dash_density: 16,
      contrast_formula_density: 6,
      contrast_formula_density_en: 6,
    },
  },
}

The built-in ruleset is kept in sync with the anti-ai-copy skill's checklist:

| Rule ID | Level | Description | |---------|-------|-------------| | content-style/em-dash-density | Info | More than 12 em-dashes (—) per 1000 words | | content-style/contrast-formula-density | Info | German: more than 4 "nicht/kein X, sondern Y" contrast constructions per 1000 words | | content-style/chatbot-leftover | Warning | German: unedited chatbot phrases ("Ich hoffe, das hilft", "Gerne!", "Lass uns eintauchen") | | content-style/contrast-formula-density-en | Info | English: more than 4 "not X, but Y" contrast constructions per 1000 words | | content-style/chatbot-leftover-en | Warning | English: unedited chatbot phrases ("I hope this helps", "Happy to help!", "Let's dive in") | | content-style/language-mismatch | Info | <html lang> conflicts with a strong German/English function-word signal |

New patterns discovered during manual review become a config entry, not a code change — the engine supports three generic rule types:

• density_per_1000_words — flags when regex matches per 1000 words exceed threshold
• presence — flags when the regex matches at all, anywhere in the content
• sentence_length_uniformity — flags when sentence word-lengths are unusually uniform (coefficient of variation below threshold); not in the default ruleset since it needs per-project tuning to avoid false positives on reference-style content

Rule types are validated at runtime as well as by TypeScript. This catches misspellings in plain astro.config.mjs files and stops the build instead of silently disabling the affected rule.

The German and English built-in rule packs are selected from the primary <html lang> value (de-AT selects German, en-US English). Language-neutral rules always run; pages without lang run both language-specific packs so a missing language signal does not hide findings. Custom rules can use languages: ["de"] or languages: ["en"] for the same behavior.

The built-in language-consistency heuristic compares common German and English function words with <html lang>. It only reports a clear mismatch (at least 12 signal words and a 2:1 advantage), always with low confidence; it does not attempt to classify other languages or mixed-language pages. Tune or disable it with language_detection.

contentStyle: true, // or, for fine-grained control:
rules: {
  content_style: {
    enabled: true,
    disabled_rules: ["em-dash-density"], // Disable a built-in rule by its short ID
    exclude: ["tags/**", "serien/**"], // Skip only content-style checks on archive hubs
    language_detection: {
      enabled: true,              // Compare German/English signal words with html[lang]
      min_signal_words: 12,
      mismatch_ratio: 2,
    },
    // Replaces the built-in defaults entirely when set (even to []):
    rules: [
      { id: "unleash", type: "presence", pattern: "(?i)entfesseln|unleash", languages: ["de", "en"], level: "warning" },
    ],
    // Or keep the defaults and just add one pattern:
    extra_rules: [
      { id: "tapestry-metaphor", type: "presence", pattern: "(?i)geflecht aus|mosaik aus", level: "info" },
    ],
  },
},

Each rule supports message/help overrides with {count}/{word_count}/{density}/{threshold}/{cv}/{sentences} placeholders, languages for language-scoping, and level: "off" to disable a rule without removing it from the list. Use disabled_rules to switch off a built-in rule without copying the default ruleset.

C2PA provenance

Enable via rules.c2pa.enabled: true. Validates embedded C2PA Content Credentials in local JPEG, PNG, and WebP assets found in dist/ — entirely offline, no remote manifest fetching.

By default, a missing manifest is silent: most images simply don't carry Content Credentials, and that's not a signal of anything. Set require_for to a list of dist-relative globs to require credentials on specific assets (e.g. AI-generated illustrations you want to keep provenance metadata on):

rules: {
  c2pa: {
    enabled: true,
    require_for: ["blog/**/*.jpg", "og/*.png"],
    require_trusted: true,
  },
}

| Rule ID | Level | Description | |---------|-------|--------------| | c2pa/invalid | Warning | An embedded manifest exists but failed validation | | c2pa/missing-required | Warning | No readable manifest found on an asset matched by require_for | | c2pa/untrusted | Warning | Manifest is cryptographically valid but its signing certificate does not chain to a trusted root (only reported when require_trusted: true) |

Missing credentials never imply that an image is AI-generated or otherwise non-compliant — they only mean no Content Credentials were embedded or none could be read.

By default, a Valid manifest passes even if it wasn't signed by a certificate chaining to a trusted root — a self-signed certificate produces Valid, never Trusted. That's fine for local testing but not sufficient as a compliance signal, since no real-world C2PA verifier (browser viewer, Adobe Content Credentials) would display it as trustworthy. Set require_trusted: true to flag Valid-but-not-Trusted manifests too. Keep it off if you intentionally sign with an in-house or test CA that isn't in the C2PA default trust list — you'd otherwise start failing your own legitimate manifests.

GDPR / DSGVO

Enable via rules.privacy_security.gdpr: true. Detects third-party transfers that send visitor IPs abroad without consent — particularly relevant in the DACH region. All findings are warnings.

| Rule ID | Description | |---------|-------------| | privacy-security/google-fonts-external | Loads fonts from fonts.googleapis.com / fonts.gstatic.com — self-host with @fontsource | | privacy-security/youtube-direct-embed | YouTube iframe uses youtube.com instead of youtube-nocookie.com / a consent wrapper | | privacy-security/google-maps-embed | Direct Google Maps iframe — use a static preview or gate behind consent | | privacy-security/cdn-resources | Scripts/styles from public CDNs (unpkg, jsDelivr, cdnjs, …) — bundle locally instead | | privacy-security/external-images | <img> from a third-party domain — host the image locally in src/assets/ |

Diagnostics

Two stderr-only diagnostics help you see what the audit is doing — neither touches the report on stdout, so JSON/SARIF output stays clean.

Progress bar

A live single-line progress bar over the check phases. Auto-enabled when stderr is an interactive terminal and silent in CI / when piped. Force it with progress: true / false.

  Auditing 770 pages…
  [███████████░░░░░░░░░░░] 17/32  crawl_budget

Debug mode

debug: true prints verbose diagnostics on stderr and replaces the progress bar:

postAudit({ debug: true })

[debug] effective config:
Config { preset: None, strict: false, ... }            ← resolved config after preset merge
[debug] discovery: 770 HTML file(s) found, 2 excluded by filters, 768 parsed into pages (180 ms)
[debug] sitemap.xml: 768 URL(s)
[debug]  1/33 seo                        12 finding(s)  40 ms
[debug]  2/33 links                       3 finding(s)  95 ms
...
[debug] 33/33 source_analysis             0 finding(s)   2 ms

Use it to confirm which config actually applies, what discovery found/filtered, and which check produces (or misses) findings and how long it takes.

Output

Text output is rendered by Runemark with semantic severity markers, grouped findings, metrics, and remedies. It uses colors in an interactive terminal and deterministic ASCII output when piped or in CI. The remedies reference Astro idioms (BaseHead, astro:assets, Content Collections, Astro.site) so fixes are actionable in context:

[FAIL] astro-post-audit

  Errors: 1   Warnings: 1   Info: 0   Files: 12

* blog/post/index.html (2)
  - Missing canonical tag [canonical/missing] at `head`
    Remedy: Set `site` in astro.config.mjs and render <link rel="canonical" ... /> in BaseHead.
  - <img> missing alt attribute [a11y/img-alt] at `img[src='/photo.jpg']`
    Remedy: Add an `alt` prop to <Image>/<Picture> or the <img> tag.

When the result set is large (20 or more findings), the report prepends a top-rule summary so you get an at-a-glance view before the per-file detail:

  Top issue rules:
       8x  html/meta-description-missing
       3x  canonical/missing
       2x  a11y/img-alt
       1x  links/broken-internal

Report files

Use reports to write one or more report files alongside the terminal output. All four formats can be active at the same time:

postAudit({
  reports: {
    json:     'audit-report.json',   // Machine-readable, one finding per entry
    markdown: 'audit-summary.md',    // Human-readable table, useful as CI artifact or PR comment
    sarif:    'audit.sarif',         // SARIF 2.1.0 — consumed by GitHub Code Scanning
    html:     'audit-report.html',   // Standalone, human-readable HTML report
  },
})

The legacy output option (JSON only) remains supported for backwards compatibility.

GitHub Code Scanning (SARIF)

Upload the SARIF file with the github/codeql-action/upload-sarif action to get inline PR annotations:

- name: Build
  run: npm run build

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: audit.sarif

Set benchmark: true to see a per-check timing breakdown — useful for identifying slow checks on large sites.

Maintainer release process

GitHub release assets are published by the tag workflow. The crates.io package and the npm package are intentionally always published manually and must never be added to CI or the release workflow.

After the GitHub release assets for the matching version are available:

cargo publish --manifest-path crates/astro-post-audit/Cargo.toml

cd packages/astro-post-audit
npm ci
npm run verify:binary
npm test
npm publish --access public

The Cargo package, npm package, lockfiles, README release heading, and vX.Y.Z tag must use the same version. The release workflow rejects mismatches before building artifacts.

License

MIT