canonical-beacon 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0 (2026-10-14)
+
+First release, by Louis Wright.
+
+- Canonical checks: missing, multiple, invalid, relative, outside `<head>`, tracking parameters/fragments, `og:url` and `Link` header mismatches.
+- Canonical targets: must exist in the build, not be an error page or meta-refresh stub, not be `noindex`, and not chain to another canonical; cross-host/protocol canonicals flagged unless allowed.
+- `noindex` + cross-page canonical conflict.
+- hreflang: code validation (ISO 639-1 / ISO 3166-1 / UN M.49 / x-default), self-reference, reciprocal return links, duplicate codes, relative hrefs, missing/noindex/non-canonical alternates, hreflang on non-canonical pages, x-default and `<html lang>` agreement.
+- Text/JSON/SARIF/Markdown output, `--fail-on`, exit codes 0/1/2, allowlist with expiry, severity overrides.
+- Composite GitHub Action with job summary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis Wright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
+# canonical-beacon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Check canonical tags and hreflang clusters in your built static site: one canonical per page, pointing at a real, indexable, final URL, and hreflang clusters that are valid, self-referencing and reciprocal.
+
+Canonical and hreflang mistakes are silent. A template ships two canonicals, a page canonicalises to a URL that was renamed, a translated page points hreflang at an English page that never links back, or a region is written `en-UK`. Search engines then ignore the hints, index the wrong URL or show the wrong language. `canonical-beacon` reads the built HTML (plus `Link` headers from `_headers`/`vercel.json`) and checks every canonical and hreflang annotation against the other pages in the build. Each finding has the file, line, severity and a **concrete fix**.
+
+CLI, library and GitHub Action. Node.js 18+, **zero runtime dependencies**. Works on any static build output (Astro, Next.js `output: 'export'`, Eleventy, Hugo, Jekyll, Docusaurus, VitePress, plain HTML) and runs offline: point it at the folder your build writes. By Louis Wright.
+
+## Features
+
+- **Canonical tags:** missing, more than one, empty or invalid, relative, outside `<head>`, tracking parameters or `#fragment`, `og:url` and `Link` header disagreements.
+- **Canonical targets:** the target page must exist in the build, must not be a 404 page or meta-refresh stub, must not be `noindex`, and must not canonicalise somewhere else again (chains). Cross-host and http/https canonicals are flagged unless you allow cross-domain canonicals.
+- **Mixed signals:** a `noindex` page that also canonicalises to another URL.
+- **hreflang codes:** ISO 639-1 language with optional script and ISO 3166-1 / UN M.49 region (`en-GB`, `zh-Hant-TW`, `es-419`) or `x-default`; catches `en-UK`, `en_GB` and region-only codes.
+- **hreflang clusters:** self-reference, return links (reciprocity), duplicate codes, relative hrefs, alternates that are missing, `noindex` or non-canonical, hreflang on non-canonical pages, `x-default` presence, and `<html lang>` agreeing with the page’s own code.
+- Text/JSON/SARIF/Markdown output, `--fail-on`, exit codes 0/1/2, allowlist with expiry, severity overrides, GitHub Action with job summary.
+
+### Scope
+
+canonical-beacon does not crawl the live site, follow HTTP redirects or check broken links; use redirect-sentinel and static-link-sentinel for those. Alternates on other domains are accepted but cannot be verified offline.
+
+## Rules
+
+| Rule | Default severity | What it means |
+|---|---|---|
+| `canonical-missing` | medium | Page has no rel=canonical |
+| `canonical-multiple` | high | Page declares more than one different canonical URL |
+| `canonical-invalid` | high | Canonical href is empty, unparsable or not http(s) |
+| `canonical-relative` | low | Canonical href is relative (absolute URLs are recommended) |
+| `canonical-in-body` | high | rel=canonical is outside <head>, so search engines ignore it |
+| `canonical-other-host` | medium | Canonical points to another host or protocol |
+| `canonical-target-missing` | high | Canonical target has no page in the build |
+| `canonical-target-not-final` | high | Canonical target is an error page or meta-refresh stub |
+| `canonical-target-noindex` | high | Canonical target is noindex |
+| `canonical-chain` | medium | Canonical target itself canonicalises somewhere else |
+| `canonical-noindex-conflict` | medium | Page is noindex and also canonicalises to another URL (mixed signals) |
+| `canonical-has-query-or-fragment` | low | Canonical URL contains a #fragment or tracking query parameters |
+| `canonical-og-url-mismatch` | low | og:url differs from the canonical URL |
+| `canonical-header-mismatch` | medium | Link: rel=canonical header disagrees with the HTML canonical |
+| `hreflang-invalid-code` | high | hreflang value is not a valid language(-region) code or x-default |
+| `hreflang-duplicate-code` | high | Same hreflang code points to different URLs |
+| `hreflang-no-self` | medium | hreflang cluster does not include the page itself |
+| `hreflang-no-return` | high | Alternate page does not link back (non-reciprocal hreflang) |
+| `hreflang-target-missing` | high | hreflang alternate has no page in the build |
+| `hreflang-target-non-canonical` | high | hreflang alternate is noindex or canonicalises elsewhere |
+| `hreflang-on-non-canonical` | medium | Page with hreflang canonicalises elsewhere |
+| `hreflang-relative` | medium | hreflang href is relative (must be fully-qualified) |
+| `hreflang-no-x-default` | info | hreflang cluster has no x-default |
+| `hreflang-lang-mismatch` | low | Page <html lang> does not match its own hreflang code |
+| `hreflang-in-body` | high | hreflang link is outside <head> |
+| `allowlist-expired` | medium | An allowlist entry is past its `expires` date |
+| `allowlist-unused` | info | An allowlist entry matched nothing |
+
+## Install and run
+
+```bash
+npx canonical-beacon dist
+npx canonical-beacon dist --base-url https://example.com --fail-on medium
+npx canonical-beacon out --clean-urls --exclude "/drafts/**"
+npx canonical-beacon public --allow-cross-domain --format sarif > canonical.sarif
+```
+
+Pages are mapped to URLs the way static hosts serve them: `index.html` → `/`, `blog/index.html` → `/blog/`, `about.html` → `/about.html` (or `/about` with `--clean-urls`). Pass `--base-url` with your public URL, or let it be inferred from canonical / `og:url` tags. Meta-refresh redirect stubs and `404.html` are skipped. `X-Robots-Tag` and `Link` headers are read from Netlify/Cloudflare `_headers` and `vercel.json`.
+
+### Sample output
+
+```text
+canonical-beacon — https://example.com
+11 page(s); 9 with canonical, 2 with hreflang at https://example.com
+
+HIGH     a.html:1 /a.html declares 2 canonicals: https://example.com/a.html, https://example.com/b.html [canonical-multiple]
+         ↳ fix: Keep exactly one rel=canonical; search engines may ignore all of them otherwise.
+HIGH     c.html:1 Canonical https://example.com/d.html is noindex [canonical-target-noindex]
+         ↳ fix: Canonicalise to an indexable page, or remove noindex from the target.
+HIGH     e.html:1 /e.html declares 2 canonicals: https://example.com/gone.html, https://example.com/e.html [canonical-multiple]
+         ↳ fix: Keep exactly one rel=canonical; search engines may ignore all of them otherwise.
+HIGH     e.html:1 rel=canonical on line 1 is outside <head> [canonical-in-body]
+         ↳ fix: Move it into <head>.
+HIGH     e.html:1 Canonical https://example.com/gone.html has no page in the build [canonical-target-missing]
+```
+
+## Options
+
+```text
+canonical-beacon 1.0.0 — check canonical tags and hreflang clusters in your built static site
+
+Usage: canonical-beacon [site-dir] [options]
+
+Site
+      --base-url <url>        Public URL of the site, e.g. https://example.com (default: inferred from canonical/og:url)
+      --include <globs>       Only check these pages (file or URL path globs, comma-separated)
+      --exclude <globs>       Skip these pages
+      --clean-urls            Pages are served without .html (about.html -> /about)
+Checks
+      --no-require-canonical   Do not report pages without rel=canonical
+      --allow-cross-domain     Accept canonicals that point to another host
+
+Common
+  -c, --config <file>     JSON config (default: .canonical-beacon.json or "canonicalBeacon" in package.json)
+  -f, --format <fmt>      text (default) | json | sarif | markdown
+      --json <file>       Also write a JSON report
+      --sarif <file>      Also write SARIF 2.1.0
+      --markdown <file>   Also write Markdown (e.g. for a job summary)
+      --fail-on <sev>     critical | high | medium | low | info | none (default: high)
+      --list-rules        Print rules and default severities
+      --no-fixes          Hide fix suggestions in text output
+      --no-color          Disable colours
+  -v, --version / -h, --help
+
+Exit codes: 0 = passed, 1 = findings at or above --fail-on, 2 = usage, config or read error.
+```
+
+## Configuration and allowlist
+
+Options can live in `.canonical-beacon.json` (or a `"canonicalBeacon"` key in `package.json`, or `--config <file>`):
+
+```json
+{
+  "failOn": "medium",
+  "severity": {
+    "canonical-missing": "low"
+  },
+  "allowlist": [
+    {
+      "rule": "canonical-missing",
+      "subject": "/legacy/*",
+      "reason": "Legacy pages are being migrated",
+      "expires": "2027-03-31"
+    }
+  ],
+  "requireCanonical": true,
+  "allowCrossDomain": false,
+  "xDefaultOptional": false
+}
+```
+
+- **`severity`** changes a rule's severity, or turns it `"off"`.
+- **`allowlist`** entries suppress matching findings. Each needs a `reason` and matches on any combination of `rule`, `file`, `subject` (globs with `*`) and `match` (a substring of the message). Add `expires` (`YYYY-MM-DD`) so the exception is time-boxed: once it lapses the finding comes back along with an `allowlist-expired` finding (medium). Entries that no longer match anything are reported as `allowlist-unused` (info).
+
+Config can also set `baseUrl`, `include`, `exclude` and `cleanUrls`. The config file is looked up in the site directory first, then in the current directory, so `.canonical-beacon.json` can live at your repository root. Other keys: `requireCanonical` (default true), `allowCrossDomain` (default false) and `xDefaultOptional` (default false; set true to silence `hreflang-no-x-default`).
+
+## Output and exit codes
+
+- `--format text` (default), `json`, `sarif` (SARIF 2.1.0 for GitHub code scanning) or `markdown` (for job summaries and PR comments). `--json`, `--sarif` and `--markdown` write extra report files in the same run.
+- `--fail-on <severity>` sets the threshold (`critical`, `high`, `medium`, `low`, `info`, `none`; default `high`).
+- Exit codes: **0** passed, **1** findings at or above `--fail-on`, **2** usage, config or read error.
+
+## GitHub Action
+
+```yaml
+permissions:
+  contents: read
+  security-events: write   # only needed for the SARIF upload
+jobs:
+  canonical-beacon:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with: { persist-credentials: false }
+      - run: npm ci && npm run build   # produce the static site first
+      - uses: MrLouisWright/canonical-beacon@v1
+        with:
+          path: dist
+          fail-on: high
+          sarif: canonical-beacon.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with: { sarif_file: canonical-beacon.sarif }
+```
+
+| Input | Description | Default |
+|---|---|---|
+| `path` | Built site directory (e.g. dist, public, _site) | `.` |
+| `base-url` | Public URL of the site, e.g. https://example.com | |
+| `fail-on` | Failure threshold | `high` |
+| `config` | Config file path | |
+| `sarif` / `json` | Write SARIF / JSON report to this path | |
+| `job-summary` | Add the Markdown report to the job summary | `true` |
+| `args` | Extra CLI arguments | |
+
+The action runs the bundled CLI with Node 20; it has no dependencies to install. Pin it to a commit SHA if your policy requires it.
+
+## Library
+
+```js
+import { check, validHreflang } from "canonical-beacon";
+const report = check("dist", { baseUrl: "https://example.com" });
+console.log(report.counts, report.findings[0]);
+validHreflang("en-UK"); // { ok: false, reason: ... }
+```
+
+Types are included.
+
+## Requirements
+
+Node.js 18 or newer. Zero runtime dependencies.
+
+## Licence
+
+MIT © Louis Wright. See [LICENSE](LICENSE).

package/action.yml

@@ -0,0 +1,47 @@
+name: 'canonical-beacon'
+description: 'Check canonical tags and hreflang clusters in your built static site'
+author: 'Louis Wright'
+branding: { icon: 'link', color: 'blue' }
+inputs:
+  path: { description: 'Built site directory (e.g. dist, public, _site)', default: '.' }
+  base-url: { description: 'Public URL of the site, e.g. https://example.com', default: '' }
+  fail-on: { description: 'critical | high | medium | low | info | none', default: 'high' }
+  config: { description: 'Path to JSON config file', default: '' }
+  sarif: { description: 'Write SARIF to this path', default: '' }
+  json: { description: 'Write JSON report to this path', default: '' }
+  job-summary: { description: 'Write the Markdown report to the job summary (true/false)', default: 'true' }
+  args: { description: 'Extra CLI arguments', default: '' }
+outputs:
+  markdown-file: { description: 'Path of the Markdown report', value: '${{ steps.run.outputs.markdown-file }}' }
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with: { node-version: '20' }
+    - id: run
+      shell: bash
+      env:
+        XB_PATH: ${{ inputs.path }}
+        XB_BASE_URL: ${{ inputs.base-url }}
+        XB_FAIL_ON: ${{ inputs.fail-on }}
+        XB_CONFIG: ${{ inputs.config }}
+        XB_SARIF: ${{ inputs.sarif }}
+        XB_JSON: ${{ inputs.json }}
+        XB_SUMMARY: ${{ inputs.job-summary }}
+        XB_ARGS: ${{ inputs.args }}
+        XB_BIN: ${{ github.action_path }}/bin/canonical-beacon.js
+      run: |
+        md="$RUNNER_TEMP/canonical-beacon.md"
+        args=("$XB_PATH" --fail-on "$XB_FAIL_ON" --markdown "$md")
+        [ -n "$XB_BASE_URL" ] && args+=(--base-url "$XB_BASE_URL")
+        [ -n "$XB_CONFIG" ] && args+=(--config "$XB_CONFIG")
+        [ -n "$XB_SARIF" ] && args+=(--sarif "$XB_SARIF")
+        [ -n "$XB_JSON" ] && args+=(--json "$XB_JSON")
+        set +e
+        # shellcheck disable=SC2086
+        node "$XB_BIN" "${args[@]}" $XB_ARGS
+        code=$?
+        set -e
+        echo "markdown-file=$md" >> "$GITHUB_OUTPUT"
+        if [ "$XB_SUMMARY" = "true" ] && [ -f "$md" ]; then cat "$md" >> "$GITHUB_STEP_SUMMARY"; fi
+        exit $code

package/bin/canonical-beacon.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { mainCli, check, RULES, SITE_OPTIONS, SITE_HELP } from '../src/index.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+mainCli({
+  name: 'canonical-beacon', version: pkg.version, configKey: 'canonicalBeacon', rules: RULES,
+  tagline: 'check canonical tags and hreflang clusters in your built static site',
+  usage: 'Usage: canonical-beacon [site-dir] [options]',
+  help: `${SITE_HELP}Checks
+      --no-require-canonical   Do not report pages without rel=canonical
+      --allow-cross-domain     Accept canonicals that point to another host
+`,
+  options: { ...SITE_OPTIONS, 'no-require-canonical': { type: 'boolean' }, 'allow-cross-domain': { type: 'boolean' } },
+  run: async ({ dir, values: o, config, configFile }) => check(dir, { cli: o, requireCanonical: o['no-require-canonical'] ? false : undefined, allowCrossDomain: o['allow-cross-domain'] || undefined, toolVersion: pkg.version }, config, configFile),
+});

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "canonical-beacon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Check canonical tags and hreflang clusters in your built static site: missing, multiple, relative or in-body canonicals, targets that are missing, noindex or chained, and hreflang codes, self-references, return links and x-default. Text/JSON/SARIF/Markdown, allowlist with expiry, GitHub Action. Zero deps.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": { ".": { "types": "./src/index.d.ts", "default": "./src/index.js" }, "./package.json": "./package.json" },
+  "bin": { "canonical-beacon": "bin/canonical-beacon.js" },
+  "files": ["src", "bin", "action.yml", "README.md", "CHANGELOG.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test test/*.test.js" },
+  "keywords": ["canonical", "rel-canonical", "hreflang", "international-seo", "duplicate-content", "seo", "static-site", "html", "sarif", "github-action"],
+  "author": "Louis Wright <hello@louiswright.co.uk> (https://github.com/MrLouisWright)",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/MrLouisWright/canonical-beacon.git" },
+  "bugs": { "url": "https://github.com/MrLouisWright/canonical-beacon/issues" },
+  "homepage": "https://github.com/MrLouisWright/canonical-beacon#readme"
+}

package/src/core.d.ts

@@ -0,0 +1,16 @@
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export interface Finding { rule: string; severity: Severity; message: string; fix?: string; file?: string; line?: number; subject?: string; [k: string]: unknown }
+export interface AllowlistEntry { rule?: string; file?: string; subject?: string; match?: string; reason: string; expires?: string }
+export interface Config { failOn?: Severity | 'none'; allowlist?: AllowlistEntry[]; severity?: Record<string, Severity | 'off'>; [k: string]: unknown }
+export interface Rule { severity: Severity; title: string }
+export interface Report { tool: { name: string; version: string; rules: Record<string, Rule> }; target: string; summaryLine?: string; counts: Record<Severity, number>; findings: Finding[]; suppressed: (Finding & { reason: string; expires: string | null })[]; [k: string]: unknown }
+export const SEVERITIES: Severity[];
+export const POLICY_RULES: Record<string, Rule>;
+export class UsageError extends Error {}
+export function applyPolicy(raw: Finding[], config?: Config, opts?: { now?: Date; configFile?: string }): { findings: Finding[]; suppressed: Report['suppressed'] };
+export function validateConfig(config: unknown): Config;
+export function exceeds(report: Report, failOn: Severity | 'none'): boolean;
+export function formatText(report: Report, opts?: { color?: boolean; failOn?: string; fixes?: boolean }): string;
+export function formatJson(report: Report): string;
+export function formatSarif(report: Report): string;
+export function formatMarkdown(report: Report, opts?: { failOn?: string }): string;

package/src/core.js

@@ -0,0 +1,176 @@
+// Shared reporting / policy / CLI core. Zero dependencies. Louis Wright, MIT.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+export const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+export const sevRank = (s) => { const i = SEVERITIES.indexOf(s); return i === -1 ? 99 : i; };
+export class UsageError extends Error {}
+
+export const POLICY_RULES = {
+  'allowlist-expired': { severity: 'medium', title: 'Allowlist entry has expired' },
+  'allowlist-unused': { severity: 'info', title: 'Allowlist entry matched nothing' },
+};
+
+function globRe(p) { return new RegExp('^' + String(p).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i'); }
+
+/** Does an allowlist entry ({rule, file, match, subject}) cover a finding? */
+export function entryMatches(e, f) {
+  if (e.rule && !globRe(e.rule).test(f.rule)) return false;
+  if (e.file && !globRe(e.file).test(f.file || '')) return false;
+  if (e.subject && !globRe(e.subject).test(f.subject || '')) return false;
+  if (e.match && !String(f.message).toLowerCase().includes(String(e.match).toLowerCase())) return false;
+  return !!(e.rule || e.file || e.subject || e.match);
+}
+
+export function validateConfig(config) {
+  if (config == null || typeof config !== 'object' || Array.isArray(config)) throw new UsageError('config must be a JSON object');
+  if (config.allowlist != null && !Array.isArray(config.allowlist)) throw new UsageError('"allowlist" must be an array');
+  for (const [i, e] of (config.allowlist || []).entries()) {
+    if (!e || typeof e !== 'object') throw new UsageError(`allowlist[${i}] must be an object`);
+    if (!e.rule && !e.file && !e.subject && !e.match) throw new UsageError(`allowlist[${i}] needs at least one of rule, file, subject, match`);
+    if (!e.reason) throw new UsageError(`allowlist[${i}] needs a "reason"`);
+    if (e.expires != null && (!/^\d{4}-\d{2}-\d{2}$/.test(e.expires) || Number.isNaN(Date.parse(e.expires)))) throw new UsageError(`allowlist[${i}].expires must be YYYY-MM-DD`);
+  }
+  for (const [k, v] of Object.entries(config.severity || {})) if (v !== 'off' && !SEVERITIES.includes(v)) throw new UsageError(`severity.${k} must be one of ${SEVERITIES.join(', ')}, off`);
+  return config;
+}
+
+/** Apply severity overrides and the allowlist. Returns { findings, suppressed }. */
+export function applyPolicy(raw, config = {}, { now = new Date(), configFile = 'config' } = {}) {
+  const today = now.toISOString().slice(0, 10);
+  const sev = config.severity || {};
+  const list = (config.allowlist || []).map((e, i) => ({ ...e, index: i, used: 0, expired: !!(e.expires && e.expires < today) }));
+  const findings = []; const suppressed = [];
+  for (const f0 of raw) {
+    const o = sev[f0.rule];
+    if (o === 'off') continue;
+    const f = o ? { ...f0, severity: o } : f0;
+    const hit = list.find((e) => entryMatches(e, f));
+    if (hit) { hit.used++; if (!hit.expired) { suppressed.push({ ...f, reason: hit.reason, expires: hit.expires || null }); continue; } }
+    findings.push(f);
+  }
+  for (const e of list) {
+    const label = [e.rule, e.file, e.subject, e.match].filter(Boolean).join(' / ');
+    if (e.expired && sev['allowlist-expired'] !== 'off') findings.push({ rule: 'allowlist-expired', severity: sev['allowlist-expired'] || 'medium', file: configFile, message: `Allowlist entry #${e.index + 1} (${label}) expired on ${e.expires}`, fix: 'Fix the underlying finding, or renew the entry with a new "expires" date and reason.' });
+    else if (!e.used && sev['allowlist-unused'] !== 'off') findings.push({ rule: 'allowlist-unused', severity: sev['allowlist-unused'] || 'info', file: configFile, message: `Allowlist entry #${e.index + 1} (${label}) matched no finding`, fix: 'Remove the stale entry.' });
+  }
+  findings.sort((a, b) => sevRank(a.severity) - sevRank(b.severity) || String(a.file || '').localeCompare(String(b.file || '')) || (a.line || 0) - (b.line || 0));
+  return { findings, suppressed };
+}
+
+export function countBy(findings) { const c = {}; for (const s of SEVERITIES) c[s] = 0; for (const f of findings) c[f.severity] = (c[f.severity] || 0) + 1; return c; }
+export const exceeds = (r, failOn) => !!failOn && failOn !== 'none' && r.findings.some((f) => sevRank(f.severity) <= sevRank(failOn));
+
+const C = { critical: '\x1b[35;1m', high: '\x1b[31;1m', medium: '\x1b[33m', low: '\x1b[36m', info: '\x1b[2m', dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m', red: '\x1b[31m', green: '\x1b[32m' };
+const sumText = (counts) => SEVERITIES.filter((k) => counts[k]).map((k) => `${counts[k]} ${k}`).join(', ') || 'no findings';
+const loc = (f) => (f.file ? `${f.file}${f.line ? ':' + f.line : ''}` : '');
+
+export function formatText(r, { color = false, failOn, fixes = true } = {}) {
+  const c = (k, s) => (color ? `${C[k]}${s}${C.reset}` : s);
+  const l = [c('bold', `${r.tool.name} — ${r.target}`)];
+  if (r.summaryLine) l.push(c('dim', r.summaryLine));
+  l.push('');
+  for (const f of r.findings) {
+    l.push(`${c(f.severity, f.severity.toUpperCase().padEnd(8))} ${loc(f) ? c('dim', loc(f) + ' ') : ''}${f.message} [${f.rule}]`);
+    if (fixes && f.fix) l.push(c('dim', `         ↳ fix: ${f.fix}`));
+  }
+  if (r.findings.length) l.push('');
+  if (r.suppressed.length) l.push(c('dim', `${r.suppressed.length} finding(s) covered by the allowlist`));
+  l.push(sumText(r.counts));
+  if (failOn) l.push(exceeds(r, failOn) ? c('red', `✖ Failing (fail-on: ${failOn}).`) : c('green', `✔ Passing (fail-on: ${failOn}).`));
+  return l.join('\n') + '\n';
+}
+
+export const formatJson = (r) => JSON.stringify(r, null, 2) + '\n';
+
+const LEVEL = { critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'note' };
+const SCORE = { critical: '9.0', high: '7.5', medium: '5.0', low: '3.0', info: '1.0' };
+export function formatSarif(r) {
+  const rules = { ...r.tool.rules, ...POLICY_RULES };
+  const ids = Object.keys(rules);
+  const repo = `https://github.com/MrLouisWright/${r.tool.name}`;
+  return JSON.stringify({
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json', version: '2.1.0',
+    runs: [{
+      tool: { driver: { name: r.tool.name, version: r.tool.version, informationUri: repo, rules: ids.map((id) => ({ id, name: id.replace(/(^|-)(\w)/g, (_, __, ch) => ch.toUpperCase()), shortDescription: { text: rules[id].title }, helpUri: `${repo}#rules`, defaultConfiguration: { level: LEVEL[rules[id].severity] }, properties: { 'security-severity': SCORE[rules[id].severity] } })) } },
+      results: r.findings.map((f) => ({ ruleId: f.rule, ruleIndex: ids.indexOf(f.rule), level: LEVEL[f.severity], message: { text: f.fix ? `${f.message}. Fix: ${f.fix}` : f.message }, locations: [{ physicalLocation: { artifactLocation: { uri: f.file || r.tool.defaultFile || '.' }, region: { startLine: f.line || 1 } } }], partialFingerprints: { ruleSubject: `${f.rule}:${f.file || ''}:${f.subject || f.message}` }, properties: { severity: f.severity } })),
+    }],
+  }, null, 2) + '\n';
+}
+
+const esc = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+export function formatMarkdown(r, { failOn } = {}) {
+  const l = [`## ${r.tool.emoji || '📏'} ${r.tool.name}`, '', `**${esc(r.target)}**: ${r.summaryLine ? esc(r.summaryLine) + '; ' : ''}${sumText(r.counts)}.`];
+  if (failOn) l.push('', exceeds(r, failOn) ? `❌ Failing at \`--fail-on ${failOn}\`.` : `✅ Passing at \`--fail-on ${failOn}\`.`);
+  if (r.findings.length) {
+    l.push('', '| Severity | Location | Rule | Finding | Fix |', '|---|---|---|---|---|');
+    for (const f of r.findings) l.push(`| ${f.severity} | ${loc(f) ? '`' + esc(loc(f)) + '`' : ''} | \`${f.rule}\` | ${esc(f.message)} | ${esc(f.fix)} |`);
+  }
+  if (r.suppressed.length) l.push('', `_${r.suppressed.length} finding(s) covered by the allowlist._`);
+  return l.join('\n') + '\n';
+}
+
+/** Build a report object from raw findings. */
+export function buildReport(tool, target, raw, config, extra = {}) {
+  const { findings, suppressed } = applyPolicy(raw, config, { now: extra.now, configFile: extra.configFile });
+  const { now, configFile, ...rest } = extra;
+  return { tool: { name: tool.name, version: tool.version, rules: tool.rules, emoji: tool.emoji, defaultFile: tool.defaultFile }, target, ...rest, counts: countBy(findings), findings, suppressed };
+}
+
+export function loadConfig(dir, name, key, explicit) {
+  const file = explicit ? resolve(explicit) : join(dir, `.${name}.json`);
+  if (explicit || existsSync(file)) {
+    let c; try { c = JSON.parse(readFileSync(file, 'utf8')); } catch (e) { throw new UsageError(`Cannot read config ${file}: ${e.message}`); }
+    return { config: validateConfig(c), configFile: explicit || `.${name}.json` };
+  }
+  for (const d of [dir, process.cwd()]) {
+    if (d !== dir && existsSync(join(d, `.${name}.json`))) return loadConfig(d, name, key, join(d, `.${name}.json`));
+    try { const pj = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')); if (pj[key]) return { config: validateConfig(pj[key]), configFile: 'package.json' }; } catch (e) { if (e instanceof UsageError) throw e; }
+  }
+  return { config: {}, configFile: null };
+}
+
+const list = (v) => (v || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
+export { list as splitList };
+
+/**
+ * Generic CLI. spec = { name, version, configKey, rules, help (tool-specific options text), options (parseArgs), defaultFailOn,
+ *   run: async ({ dir, positionals, values, config, configFile, stdin }) => report }
+ */
+export async function runCli(spec, argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  const usage = (m) => { io.stderr.write(`${spec.name}: ${m}\nRun with --help for usage.\n`); return 2; };
+  let a;
+  try {
+    a = parseArgs({ args: argv, allowPositionals: true, options: { ...spec.options, config: { type: 'string', short: 'c' }, format: { type: 'string', short: 'f' }, json: { type: 'string' }, sarif: { type: 'string' }, markdown: { type: 'string' }, 'fail-on': { type: 'string' }, 'no-color': { type: 'boolean' }, 'no-fixes': { type: 'boolean' }, 'list-rules': { type: 'boolean' }, version: { type: 'boolean', short: 'v' }, help: { type: 'boolean', short: 'h' } } });
+  } catch (e) { return usage(e.message); }
+  const { values: o, positionals } = a;
+  const all = { ...spec.rules, ...POLICY_RULES };
+  if (o.help) { io.stdout.write(`${spec.name} ${spec.version} — ${spec.tagline}\n\n${spec.usage}\n\n${spec.help}\nCommon\n  -c, --config <file>     JSON config (default: .${spec.name}.json or "${spec.configKey}" in package.json)\n  -f, --format <fmt>      text (default) | json | sarif | markdown\n      --json <file>       Also write a JSON report\n      --sarif <file>      Also write SARIF 2.1.0\n      --markdown <file>   Also write Markdown (e.g. for a job summary)\n      --fail-on <sev>     critical | high | medium | low | info | none (default: ${spec.defaultFailOn || 'high'})\n      --list-rules        Print rules and default severities\n      --no-fixes          Hide fix suggestions in text output\n      --no-color          Disable colours\n  -v, --version / -h, --help\n\nExit codes: 0 = passed, 1 = findings at or above --fail-on, 2 = usage, config or read error.\n`); return 0; }
+  if (o.version) { io.stdout.write(spec.version + '\n'); return 0; }
+  if (o['list-rules']) { for (const [id, r] of Object.entries(all)) io.stdout.write(`${id.padEnd(28)} ${r.severity.padEnd(9)} ${r.title}\n`); return 0; }
+  const format = o.format || 'text';
+  if (!['text', 'json', 'sarif', 'markdown'].includes(format)) return usage(`Invalid --format: ${format}`);
+  let report; let failOn;
+  try {
+    const dir = resolve(spec.dirFrom ? spec.dirFrom(o, positionals) : (positionals[0] || '.'));
+    if (!existsSync(dir)) return usage(`No such directory: ${dir}`);
+    const { config, configFile } = loadConfig(dir, spec.name, spec.configKey, o.config);
+    failOn = o['fail-on'] || config.failOn || spec.defaultFailOn || 'high';
+    if (failOn !== 'none' && !SEVERITIES.includes(failOn)) return usage(`Invalid --fail-on: ${failOn}`);
+    report = await spec.run({ dir, positionals, values: o, config, configFile: configFile || `.${spec.name}.json` });
+  } catch (e) { if (e instanceof UsageError || e.code === 'ENOENT' || e.code === 'EACCES') return usage(e.message); throw e; }
+  const color = !o['no-color'] && io.stdout.isTTY && !process.env.NO_COLOR;
+  const out = { text: () => formatText(report, { color, failOn, fixes: !o['no-fixes'] }), json: () => formatJson(report), sarif: () => formatSarif(report), markdown: () => formatMarkdown(report, { failOn }) };
+  io.stdout.write(out[format]());
+  try {
+    if (o.json) writeFileSync(o.json, formatJson(report));
+    if (o.sarif) writeFileSync(o.sarif, formatSarif(report));
+    if (o.markdown) writeFileSync(o.markdown, formatMarkdown(report, { failOn }));
+  } catch (e) { return usage(`Cannot write output: ${e.message}`); }
+  return exceeds(report, failOn) ? 1 : 0;
+}
+
+export function mainCli(spec) {
+  runCli(spec).then((c) => { process.exitCode = c; }, (e) => { process.stderr.write(`${spec.name}: ${e.stack || e}\n`); process.exitCode = 2; });
+}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+import type { Report, Rule } from './core.js';
+export * from './core.js';
+export interface CanonicalOptions {
+  /** Public URL of the site, e.g. "https://example.com". Inferred from canonical/og:url when omitted. */
+  baseUrl?: string; include?: string[]; exclude?: string[]; cleanUrls?: boolean;
+  /** Report pages without rel=canonical (default true). */
+  requireCanonical?: boolean;
+  /** Accept canonicals that point to another host. */
+  allowCrossDomain?: boolean;
+  now?: Date; toolVersion?: string; [option: string]: unknown;
+}
+export declare const RULES: Record<string, Rule>;
+export declare const SITE_OPTIONS: Record<string, { type: 'string' | 'boolean'; multiple?: boolean }>;
+export declare const SITE_HELP: string;
+export declare function check(dir: string, opts?: CanonicalOptions, config?: Record<string, unknown>, configFile?: string): Report;
+export declare function analyze(site: unknown, opts?: CanonicalOptions, config?: Record<string, unknown>): { findings: Report['findings']; info: Record<string, unknown>; summary: string };
+export declare function validHreflang(value: string): { ok: boolean; xDefault?: boolean; lang?: string; region?: string | null; reason?: string };

package/src/index.js

@@ -0,0 +1,133 @@
+// canonical-beacon: canonical tag and hreflang cluster checks for built static sites. Louis Wright, MIT.
+import { contentPages, runBeacon, finder, SITE_OPTIONS, SITE_HELP, siteOptions, robotsDirectives, isNoindex, canonicalOf, isRedirectStub, isErrorPage } from './site.js';
+import { buildReport, UsageError } from './core.js';
+
+export * from './core.js';
+export { SITE_OPTIONS, SITE_HELP, siteOptions };
+
+export const RULES = {
+  'canonical-missing': { severity: 'medium', title: 'Page has no rel=canonical' },
+  'canonical-multiple': { severity: 'high', title: 'Page declares more than one different canonical URL' },
+  'canonical-invalid': { severity: 'high', title: 'Canonical href is empty, unparsable or not http(s)' },
+  'canonical-relative': { severity: 'low', title: 'Canonical href is relative (absolute URLs are recommended)' },
+  'canonical-in-body': { severity: 'high', title: 'rel=canonical is outside <head>, so search engines ignore it' },
+  'canonical-other-host': { severity: 'medium', title: 'Canonical points to another host or protocol' },
+  'canonical-target-missing': { severity: 'high', title: 'Canonical target has no page in the build' },
+  'canonical-target-not-final': { severity: 'high', title: 'Canonical target is an error page or meta-refresh stub' },
+  'canonical-target-noindex': { severity: 'high', title: 'Canonical target is noindex' },
+  'canonical-chain': { severity: 'medium', title: 'Canonical target itself canonicalises somewhere else' },
+  'canonical-noindex-conflict': { severity: 'medium', title: 'Page is noindex and also canonicalises to another URL (mixed signals)' },
+  'canonical-has-query-or-fragment': { severity: 'low', title: 'Canonical URL contains a #fragment or tracking query parameters' },
+  'canonical-og-url-mismatch': { severity: 'low', title: 'og:url differs from the canonical URL' },
+  'canonical-header-mismatch': { severity: 'medium', title: 'Link: rel=canonical header disagrees with the HTML canonical' },
+  'hreflang-invalid-code': { severity: 'high', title: 'hreflang value is not a valid language(-region) code or x-default' },
+  'hreflang-duplicate-code': { severity: 'high', title: 'Same hreflang code points to different URLs' },
+  'hreflang-no-self': { severity: 'medium', title: 'hreflang cluster does not include the page itself' },
+  'hreflang-no-return': { severity: 'high', title: 'Alternate page does not link back (non-reciprocal hreflang)' },
+  'hreflang-target-missing': { severity: 'high', title: 'hreflang alternate has no page in the build' },
+  'hreflang-target-non-canonical': { severity: 'high', title: 'hreflang alternate is noindex or canonicalises elsewhere' },
+  'hreflang-on-non-canonical': { severity: 'medium', title: 'Page with hreflang canonicalises elsewhere' },
+  'hreflang-relative': { severity: 'medium', title: 'hreflang href is relative (must be fully-qualified)' },
+  'hreflang-no-x-default': { severity: 'info', title: 'hreflang cluster has no x-default' },
+  'hreflang-lang-mismatch': { severity: 'low', title: 'Page <html lang> does not match its own hreflang code' },
+  'hreflang-in-body': { severity: 'high', title: 'hreflang link is outside <head>' },
+};
+
+const REGIONS_ODD = new Set(['uk', 'eu']);
+/** Validate an hreflang value: ISO 639-1 language, optional script, optional ISO 3166-1 alpha-2 region (or 3-digit UN M.49), or x-default. */
+export function validHreflang(v) {
+  const s = String(v || '').trim();
+  if (/^x-default$/i.test(s)) return { ok: true, xDefault: true };
+  const m = /^([a-z]{2,3})(?:-([a-z]{4}))?(?:-([a-z]{2}|\d{3}))?$/i.exec(s);
+  if (!m) return { ok: false, reason: `"${s}" is not language[-Script][-REGION]` };
+  if (m[3] && REGIONS_ODD.has(m[3].toLowerCase())) return { ok: false, reason: `"${m[3]}" is not an ISO 3166-1 region (use ${m[3].toLowerCase() === 'uk' ? 'GB' : 'a country code'})` };
+  if (!m[2] && !m[3] && m[1].length === 2 && /^(gb|us|uk)$/i.test(m[1])) return { ok: false, reason: `"${s}" is a region, not a language (e.g. en-${m[1].toUpperCase() === 'UK' ? 'GB' : m[1].toUpperCase()})` };
+  return { ok: true, lang: m[1].toLowerCase(), region: m[3]?.toUpperCase() || null };
+}
+const TRACK = /^(utm_[a-z]+|gclid|fbclid|msclkid|mc_[a-z]+|ref|sessionid|sid)$/i;
+const strip = (u) => u.href.replace(/#.*$/, '');
+
+export function analyze(site, opts = {}, config = {}) {
+  const { findings, add } = finder(RULES);
+  const requireCanonical = opts.requireCanonical ?? config.requireCanonical ?? true;
+  const pages = contentPages(site);
+  const canon = new Map();
+  const canonOf = (pg) => { if (!canon.has(pg)) canon.set(pg, canonicalOf(site, pg)); return canon.get(pg); };
+  const urlOf = (pg) => new URL((site.origin || 'http://site.invalid') + (site.basePath || '') + pg.path);
+  let withCanon = 0; let clusters = 0;
+  for (const pg of pages) {
+    const at = (l) => ({ file: pg.file, line: l?.line });
+    const c = canonOf(pg); const self = urlOf(pg);
+    const noindex = isNoindex(robotsDirectives(site, pg));
+    const hrefs = [...new Set(c.tags.map((t) => String(t.href).trim()))];
+    if (!c.tags.length && !c.header.length) { if (requireCanonical && !noindex) add('canonical-missing', pg.path, `${pg.path} has no rel=canonical`, `Add <link rel="canonical" href="${site.origin ? site.urlOf(pg) : 'https://example.com' + pg.path}"> to <head>.`, { file: pg.file }); }
+    else {
+      withCanon++;
+      const resolved = new Set(c.tags.map((t) => site.resolve(pg, t.href)).filter(Boolean).map(strip));
+      if (resolved.size > 1 || (hrefs.length > 1 && resolved.size === 0)) add('canonical-multiple', pg.path, `${pg.path} declares ${hrefs.length} canonicals: ${hrefs.join(', ')}`, 'Keep exactly one rel=canonical; search engines may ignore all of them otherwise.', at(c.tags[1]));
+      for (const t of c.tags) if (!t.inHead) add('canonical-in-body', pg.path, `rel=canonical on line ${t.line} is outside <head>`, 'Move it into <head>.', at(t));
+      const t0 = c.tags.find((t) => t.inHead) || c.tags[0];
+      if (t0) {
+        const h = String(t0.href).trim();
+        if (!h || !c.url || !/^https?:$/.test(c.url.protocol)) { add('canonical-invalid', pg.path, `Canonical href "${h}" is not a valid http(s) URL`, 'Use the absolute URL of the preferred page.', at(t0)); continue; }
+        if (!/^https?:\/\//i.test(h)) add('canonical-relative', pg.path, `Canonical "${h}" is relative`, `Use the absolute URL (${c.url.href}).`, at(t0));
+      }
+      if (c.header.length && t0 && c.url) { const hu = site.resolve(pg, c.header[0]); if (hu && strip(hu) !== strip(c.url)) add('canonical-header-mismatch', pg.path, `Link header canonical ${hu.href} differs from HTML canonical ${c.url.href}`, 'Make both point to the same URL, or remove one.', { file: pg.file }); }
+      const cu = c.url;
+      if (cu) {
+        if (cu.hash || [...cu.searchParams.keys()].some((k) => TRACK.test(k))) add('canonical-has-query-or-fragment', pg.path, `Canonical ${cu.href} contains ${cu.hash ? 'a #fragment' : 'tracking parameters'}`, 'Canonicalise to the clean URL.', at(t0));
+        const og = pg.doc.metaContent('og:url');
+        if (og) { const ou = site.resolve(pg, og); if (ou && strip(ou).replace(/\/$/, '') !== strip(cu).replace(/\/$/, '')) add('canonical-og-url-mismatch', pg.path, `og:url ${ou.href} differs from canonical ${cu.href}`, 'Set og:url to the canonical URL.', { file: pg.file }); }
+        if (site.origin && cu.origin !== site.origin) {
+          let sameHost = false; try { sameHost = new URL(site.origin).hostname === cu.hostname; } catch { /* */ }
+          if (!(config.allowCrossDomain ?? opts.allowCrossDomain)) add('canonical-other-host', pg.path, `${pg.path} canonicalises to ${cu.href}${sameHost ? ' (protocol differs)' : ' on another host'}`, sameHost ? `Use ${site.origin}.` : 'If this is a deliberate cross-domain canonical, set "allowCrossDomain": true or allowlist it.', at(t0));
+        } else {
+          const tp = site.find(cu);
+          const isSelf = tp === pg || strip(cu) === strip(self);
+          if (!tp && !isSelf) add('canonical-target-missing', pg.path, `Canonical ${cu.href} has no page in the build`, 'Point the canonical at a page that exists (check trailing slash and .html).', at(t0));
+          else if (tp && !isSelf) {
+            if (isErrorPage(tp) || isRedirectStub(tp)) add('canonical-target-not-final', pg.path, `Canonical ${cu.href} is ${isErrorPage(tp) ? 'an error page' : 'a meta-refresh stub'} (${tp.file})`, 'Canonicalise to the final destination page.', at(t0));
+            else if (isNoindex(robotsDirectives(site, tp))) add('canonical-target-noindex', pg.path, `Canonical ${cu.href} is noindex`, 'Canonicalise to an indexable page, or remove noindex from the target.', at(t0));
+            else { const tc = canonOf(tp).url; const tt = tc && site.find(tc); if (tc && tt !== tp && strip(tc) !== strip(cu)) add('canonical-chain', pg.path, `Canonical ${cu.href} itself canonicalises to ${tc.href}`, `Point ${pg.path} directly at ${tc.href}.`, at(t0)); }
+            if (noindex) add('canonical-noindex-conflict', pg.path, `${pg.path} is noindex and canonicalises to ${cu.href}`, 'Use one signal: either canonical (to consolidate) or noindex (to drop).', at(t0));
+          }
+        }
+      }
+    }
+    // hreflang
+    const alts = pg.doc.links.filter((l) => l.rel.includes('alternate') && l.hreflang != null);
+    if (!alts.length) continue;
+    clusters++;
+    const codes = new Map(); let hasSelf = false; let hasX = false; let selfCode = null;
+    const cu = c.url; const nonCanon = cu && strip(cu) !== strip(self) && site.find(cu) !== pg;
+    if (nonCanon) add('hreflang-on-non-canonical', pg.path, `${pg.path} has hreflang but canonicalises to ${cu.href}`, 'Put hreflang only on canonical pages, pointing at canonical URLs.', at(alts[0]));
+    for (const a of alts) {
+      if (!a.inHead) add('hreflang-in-body', pg.path, `hreflang="${a.hreflang}" link is outside <head>`, 'Move it into <head>.', at(a));
+      const v = validHreflang(a.hreflang);
+      if (!v.ok) { add('hreflang-invalid-code', pg.path, `hreflang ${v.reason}`, 'Use ISO 639-1 language with optional ISO 3166-1 region, e.g. en, en-GB, pt-BR, or x-default.', at(a)); continue; }
+      if (v.xDefault) hasX = true;
+      const key = String(a.hreflang).toLowerCase(); const u = site.resolve(pg, a.href);
+      if (!u) { add('hreflang-target-missing', pg.path, `hreflang="${a.hreflang}" href "${a.href}" is invalid`, 'Use an absolute URL.', at(a)); continue; }
+      if (!/^https?:\/\//i.test(String(a.href).trim())) add('hreflang-relative', pg.path, `hreflang="${a.hreflang}" href "${a.href}" is relative`, `Use the absolute URL (${u.href}).`, at(a));
+      if (codes.has(key) && codes.get(key) !== strip(u)) add('hreflang-duplicate-code', pg.path, `hreflang="${a.hreflang}" points to both ${codes.get(key)} and ${strip(u)}`, 'Each code may map to one URL only.', at(a));
+      codes.set(key, strip(u));
+      const tp = site.origin && u.origin !== site.origin ? undefined : site.find(u);
+      if (tp === pg || strip(u) === strip(self)) { hasSelf = true; if (!v.xDefault) selfCode = v; continue; }
+      if (site.origin && u.origin !== site.origin) continue; // cross-domain alternates cannot be verified offline
+      if (!tp) { add('hreflang-target-missing', pg.path, `hreflang="${a.hreflang}" ${u.href} has no page in the build`, 'Fix the URL or remove the alternate from every page in the cluster.', at(a)); continue; }
+      const tc = canonOf(tp).url;
+      if (isNoindex(robotsDirectives(site, tp)) || (tc && site.find(tc) !== tp && strip(tc) !== strip(u))) { add('hreflang-target-non-canonical', pg.path, `hreflang="${a.hreflang}" ${u.href} is ${isNoindex(robotsDirectives(site, tp)) ? 'noindex' : 'canonicalised to ' + tc.href}`, 'Point hreflang at the canonical, indexable version.', at(a)); continue; }
+      const back = tp.doc.links.filter((l) => l.rel.includes('alternate') && l.hreflang != null).some((l) => { const bu = site.resolve(tp, l.href); return bu && (site.find(bu) === pg || strip(bu) === strip(self)); });
+      if (!back) add('hreflang-no-return', pg.path, `${tp.path} (hreflang="${a.hreflang}") does not link back to ${pg.path}`, `Add <link rel="alternate" hreflang="…" href="${site.urlOf(pg)}"> to ${tp.file}.`, at(a));
+    }
+    if (!hasSelf && !nonCanon) add('hreflang-no-self', pg.path, `${pg.path} has hreflang alternates but none for itself`, 'Include a self-referencing hreflang link for the page’s own language.', at(alts[0]));
+    if (!hasX && !(config.xDefaultOptional ?? false)) add('hreflang-no-x-default', pg.path, `${pg.path} hreflang cluster has no x-default`, 'Add hreflang="x-default" pointing at the language selector or default version.', at(alts[0]));
+    if (selfCode && pg.doc.lang) { const l = validHreflang(pg.doc.lang); if (l.ok && l.lang !== selfCode.lang) add('hreflang-lang-mismatch', pg.path, `<html lang="${pg.doc.lang}"> but the page’s own hreflang is ${selfCode.lang}${selfCode.region ? '-' + selfCode.region : ''}`, 'Make the html lang attribute and hreflang agree.', { file: pg.file }); }
+  }
+  return { findings, info: { canonicals: withCanon, hreflangPages: clusters }, summary: `${pages.length} page(s); ${withCanon} with canonical, ${clusters} with hreflang${site.baseUrl ? ` at ${site.baseUrl}` : ''}` };
+}
+
+export function check(dir, opts = {}, config = {}, configFile) {
+  const tool = { name: 'canonical-beacon', version: opts.toolVersion || '1.0.0', rules: RULES, emoji: '🔗', defaultFile: 'index.html' };
+  return runBeacon(tool, dir, { ...opts, UsageError }, config, configFile, analyze, buildReport);
+}

package/src/site.js

@@ -0,0 +1,326 @@
+// Shared static-site reader for the *-beacon packages: a small, forgiving HTML parser,
+// a build-output walker that maps files to URLs, and _headers / vercel.json header rules.
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const RAW = new Set(['script', 'style', 'textarea', 'title', 'xmp', 'noscript', 'template']);
+const HEADISH = new Set(['html', 'head', 'meta', 'link', 'title', 'base', 'script', 'style', 'noscript', 'template']);
+const BLOCK = new Set(['address', 'article', 'aside', 'blockquote', 'br', 'dd', 'details', 'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'li', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'summary', 'table', 'td', 'th', 'tr', 'ul', 'option', 'caption']);
+const CLOSES_P = new Set(['address', 'article', 'aside', 'blockquote', 'details', 'div', 'dl', 'fieldset', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'table', 'ul']);
+const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: '\u00a0', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”', copy: '©', reg: '®', trade: '™', laquo: '«', raquo: '»', middot: '·', bull: '•', times: '×', eacute: 'é', egrave: 'è', aacute: 'á', uuml: 'ü', ouml: 'ö', auml: 'ä', szlig: 'ß', ccedil: 'ç', ntilde: 'ñ', euro: '€', pound: '£', yen: '¥', deg: '°', shy: '' };
+export const decode = (s) => String(s).replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*);?/gi, (m, e) => { if (e[0] === '#') { const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10); try { return String.fromCodePoint(n); } catch { return m; } } const v = ENT[e.toLowerCase()]; return v ?? m; });
+export const squash = (s) => String(s).replace(/[\s\u00a0]+/g, ' ').trim();
+
+function parseAttrs(src) {
+  const attrs = {};
+  for (const m of src.matchAll(/([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g)) { const k = m[1].toLowerCase(); if (!(k in attrs)) attrs[k] = decode(m[2] ?? m[3] ?? m[4] ?? ''); }
+  return attrs;
+}
+
+/** Parse HTML into a light tree. Elements: { tag, attrs, line, children, parent, inHead }. Text nodes: { text }. */
+export function parseHtml(html) {
+  html = String(html).replace(/^\uFEFF/, '');
+  const root = { tag: '#document', attrs: {}, children: [], line: 1, parent: null };
+  const all = []; let cur = root; let bodyStarted = false; let i = 0; let line = 1;
+  const lineAt = (to) => { for (let k = i; k < to; k++) if (html.charCodeAt(k) === 10) line++; i = to; };
+  const inHeadEl = () => { for (let n = cur; n; n = n.parent) if (n.tag === 'head') return true; return false; };
+  const close = (tag) => { for (let n = cur; n && n !== root; n = n.parent) if (n.tag === tag) { cur = n.parent; return true; } return false; };
+  const open = (tag, attrs, ln, selfClose) => {
+    if (tag === 'body') bodyStarted = true;
+    else if (!HEADISH.has(tag) && !inHeadEl()) bodyStarted = true;
+    if (cur.tag === 'head' && !HEADISH.has(tag)) cur = cur.parent; // implicit </head>
+    if (CLOSES_P.has(tag)) { for (let n = cur; n && n !== root && !['div', 'section', 'article', 'main', 'body', 'td', 'li', 'blockquote'].includes(n.tag) || n === cur; n = n.parent) { if (n === root) break; if (n.tag === 'p') { cur = n.parent; break; } if (n !== cur) break; } }
+    if (tag === 'li') { for (let n = cur; n && n !== root; n = n.parent) { if (n.tag === 'li') { cur = n.parent; break; } if (n.tag === 'ul' || n.tag === 'ol') break; } }
+    if (tag === 'dt' || tag === 'dd') { for (let n = cur; n && n !== root; n = n.parent) { if (n.tag === 'dt' || n.tag === 'dd') { cur = n.parent; break; } if (n.tag === 'dl') break; } }
+    if (tag === 'option' && cur.tag === 'option') cur = cur.parent;
+    if ((tag === 'tr' || tag === 'td' || tag === 'th') && (cur.tag === 'td' || cur.tag === 'th')) cur = cur.parent;
+    if (tag === 'tr' && cur.tag === 'tr') cur = cur.parent;
+    const el = { tag, attrs, line: ln, children: [], parent: cur, inHead: !bodyStarted || inHeadEl() };
+    cur.children.push(el); all.push(el);
+    if (!VOID.has(tag) && !selfClose) cur = el;
+    return el;
+  };
+  while (i < html.length) {
+    const lt = html.indexOf('<', i);
+    if (lt === -1) { const t = html.slice(i); if (t.trim() && !inHeadEl()) bodyStarted = true; cur.children.push({ text: decode(t) }); lineAt(html.length); break; }
+    if (lt > i) { const t = html.slice(i, lt); if (t.trim()) { if (!inHeadEl() && cur.tag !== 'html' || cur.tag === 'html' || cur === root) { if (!inHeadEl()) bodyStarted = true; } } cur.children.push({ text: decode(t) }); lineAt(lt); }
+    if (html.startsWith('<!--', lt)) { const e = html.indexOf('-->', lt + 4); lineAt(e === -1 ? html.length : e + 3); continue; }
+    if (html[lt + 1] === '!' || html[lt + 1] === '?') { const e = html.indexOf('>', lt); lineAt(e === -1 ? html.length : e + 1); continue; }
+    const m = /^<(\/?)([a-zA-Z][a-zA-Z0-9:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/.exec(html.slice(lt, lt + 20000));
+    if (!m) { cur.children.push({ text: '<' }); lineAt(lt + 1); continue; }
+    const tag = m[2].toLowerCase(); const ln = line;
+    lineAt(lt + m[0].length);
+    if (m[1]) { if (tag === 'p' && !close('p')) { /* stray </p> */ } else if (tag !== 'p') close(tag); continue; }
+    const el = open(tag, parseAttrs(m[3]), ln, /\/\s*$/.test(m[3]));
+    if (RAW.has(tag) && !/\/\s*$/.test(m[3])) {
+      const re = new RegExp(`</${tag}\\s*>`, 'i'); re.lastIndex = 0; const rest = html.slice(i); const em = re.exec(rest);
+      const end = em ? i + em.index : html.length; const raw = html.slice(i, end);
+      if (tag === 'noscript' || tag === 'template') { const inner = parseHtml(raw); for (const c of inner.root.children) { c.parent = el; el.children.push(c); } for (const c of inner.all) { c.line += ln - 1; c.inHead = el.inHead; all.push(c); } }
+      else el.children.push({ text: tag === 'script' || tag === 'style' ? raw : decode(raw), raw: true });
+      el.rawText = raw;
+      lineAt(end); if (em) lineAt(end + em[0].length);
+      cur = el.parent;
+    }
+  }
+  return makeDoc(root, all);
+}
+
+/** Visible text of an element (skips script/style/template, adds spaces at block boundaries). opts.alt includes img alt text. */
+export function textOf(node, opts = {}) {
+  const out = [];
+  const walk = (n) => {
+    if (n.text != null) { if (!n.raw || (n.parent?.tag !== 'script' && n.parent?.tag !== 'style')) out.push(n.text); return; }
+    if (n.tag === 'script' || n.tag === 'style' || n.tag === 'template' || (n.tag === 'noscript' && !opts.noscript)) return;
+    if (opts.skip && opts.skip.has(n.tag)) return;
+    if (n.attrs?.hidden != null || n.attrs?.['aria-hidden'] === 'true' && opts.skipHidden) return;
+    if (n.tag === 'img' && opts.alt) out.push(` ${n.attrs.alt || ''} `);
+    if (BLOCK.has(n.tag)) out.push(' ');
+    for (const c of n.children || []) walk(c);
+    if (BLOCK.has(n.tag)) out.push(' ');
+  };
+  if (node.text != null) return squash(node.text);
+  for (const c of node.children || []) walk(c);
+  return squash(out.join(''));
+}
+const has = (el, tag) => { for (let n = el.parent; n; n = n.parent) if (n.tag === tag) return true; return false; };
+export const ancestor = (el, pred) => { for (let n = el.parent; n; n = n.parent) if (n.tag && pred(n)) return n; return null; };
+
+function makeDoc(root, all) {
+  const doc = { root, all };
+  const by = (t) => all.filter((e) => e.tag === t);
+  doc.find = (t) => by(t);
+  const html = all.find((e) => e.tag === 'html');
+  doc.lang = html?.attrs.lang ?? null;
+  doc.titles = by('title').filter((e) => !has(e, 'svg')).map((e) => ({ text: squash(decode(e.rawText ?? textOf(e))), line: e.line, inHead: e.inHead, el: e }));
+  doc.title = doc.titles.find((t) => t.inHead)?.text ?? doc.titles[0]?.text ?? null;
+  doc.metas = by('meta').map((e) => ({ name: (e.attrs.name || '').toLowerCase() || null, property: (e.attrs.property || '').toLowerCase() || null, httpEquiv: (e.attrs['http-equiv'] || '').toLowerCase() || null, content: e.attrs.content ?? null, charset: e.attrs.charset ?? null, itemprop: e.attrs.itemprop ?? null, line: e.line, inHead: e.inHead, el: e }));
+  doc.meta = (key) => { key = key.toLowerCase(); return doc.metas.filter((m) => m.name === key || m.property === key); };
+  doc.metaContent = (key) => { const m = doc.meta(key).find((x) => x.inHead) || doc.meta(key)[0]; return m ? (m.content ?? '') : null; };
+  doc.links = by('link').map((e) => ({ rel: (e.attrs.rel || '').toLowerCase().split(/\s+/).filter(Boolean), href: e.attrs.href ?? null, hreflang: e.attrs.hreflang ?? null, type: e.attrs.type ?? null, line: e.line, inHead: e.inHead, el: e }));
+  doc.base = by('base').find((e) => e.attrs.href)?.attrs.href ?? null;
+  doc.anchors = by('a').filter((e) => e.attrs.href != null).map((e) => ({ href: e.attrs.href, rel: (e.attrs.rel || '').toLowerCase().split(/\s+/).filter(Boolean), text: textOf(e, { alt: true }), line: e.line, el: e }));
+  doc.headings = [];
+  for (const e of all) {
+    let level = /^h([1-6])$/.exec(e.tag)?.[1];
+    if (!level && e.attrs.role === 'heading') level = e.attrs['aria-level'] || '2';
+    if (level && !has(e, 'svg') && !has(e, 'template')) doc.headings.push({ level: +level, text: textOf(e, { alt: true }), line: e.line, el: e, hidden: e.attrs.hidden != null || !!ancestor(e, (n) => n.attrs?.hidden != null) });
+  }
+  doc.jsonld = by('script').filter((e) => /^application\/ld\+json$/i.test((e.attrs.type || '').trim())).map((e) => { const raw = e.rawText ?? ''; try { return { raw, line: e.line, data: JSON.parse(raw.trim().replace(/^<!--|-->$/g, '')) }; } catch (err) { return { raw, line: e.line, error: err.message }; } });
+  const body = by('body')[0] || root;
+  let _text; let _main;
+  Object.defineProperty(doc, 'text', { get: () => (_text ??= textOf(body)) });
+  Object.defineProperty(doc, 'mainText', { get: () => {
+    if (_main != null) return _main;
+    const mains = all.filter((e) => e.tag === 'main' || e.attrs.role === 'main');
+    const arts = mains.length ? mains : all.filter((e) => e.tag === 'article' && !has(e, 'article'));
+    _main = arts.length ? squash(arts.map((e) => textOf(e, { skip: new Set(['nav', 'aside']) })).join(' ')) : textOf(body, { skip: new Set(['nav', 'header', 'footer', 'aside']) });
+    return _main;
+  } });
+  doc.words = (s) => (s ?? doc.mainText).split(/[^\p{L}\p{N}'’-]+/u).filter((w) => /[\p{L}\p{N}]/u.test(w));
+  doc.robots = (bots = ['robots']) => doc.metas.filter((m) => m.name && bots.includes(m.name)).map((m) => ({ ...m, directives: String(m.content || '').toLowerCase().split(',').map((d) => d.trim()).filter(Boolean) }));
+  return doc;
+}
+
+// ---------------------------------------------------------------------------------------------- site
+export function globToRe(g) {
+  let s = ''; g = String(g);
+  for (let k = 0; k < g.length; k++) {
+    const c = g[k];
+    if (c === '*') { if (g[k + 1] === '*') { s += '.*'; k++; if (g[k + 1] === '/') k++; } else s += '[^/]*'; }
+    else if (c === '?') s += '[^/]';
+    else s += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${s}$`);
+}
+export const matchAny = (globs, s) => (globs || []).some((g) => globToRe(g).test(s));
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.svn', '.hg']);
+function walk(dir, base = dir, out = []) {
+  let ents; try { ents = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of ents) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, base, out);
+    else if (e.isFile()) out.push(relative(base, p).split(sep).join('/'));
+  }
+  return out;
+}
+
+/** URL path for a built file: index.html -> "/", a/index.html -> "/a/", a.html -> "/a.html" (or "/a" with cleanUrls). */
+export function pathForFile(file, { cleanUrls = false } = {}) {
+  if (/(^|\/)index\.html?$/i.test(file)) return '/' + file.replace(/index\.html?$/i, '');
+  return '/' + (cleanUrls ? file.replace(/\.html?$/i, '') : file);
+}
+export function normPath(p) {
+  let s = String(p || '/').split('#')[0].split('?')[0];
+  try { s = decodeURI(s); } catch { /* keep */ }
+  if (!s.startsWith('/')) s = '/' + s;
+  return s.replace(/\/{2,}/g, '/');
+}
+
+/**
+ * Load a built static site. opts: { baseUrl, include, exclude, cleanUrls }.
+ * Returns { dir, files, pages, baseUrl, origin, find(urlOrPath), resolve(page, href), isInternal(url), headersFor(path), read(rel) }.
+ */
+export function loadSite(dir, opts = {}) {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw Object.assign(new Error(`No such directory: ${dir}`), { code: 'ENOENT' });
+  const files = walk(dir).sort();
+  const htmlFiles = files.filter((f) => /\.html?$/i.test(f) && !matchAny(opts.exclude, f) && !matchAny(opts.exclude, pathForFile(f, opts)) && (!opts.include?.length || matchAny(opts.include, f) || matchAny(opts.include, pathForFile(f, opts))));
+  const cache = new Map();
+  const pages = htmlFiles.map((file) => {
+    const page = { file, path: pathForFile(file, opts) };
+    Object.defineProperty(page, 'html', { get: () => readFileSync(join(dir, file), 'utf8') });
+    Object.defineProperty(page, 'doc', { get: () => { if (!cache.has(file)) cache.set(file, parseHtml(readFileSync(join(dir, file), 'utf8'))); return cache.get(file); }, enumerable: false });
+    return page;
+  });
+  const index = new Map();
+  const keyVariants = (path) => { const p = normPath(path).toLowerCase(); const out = [p]; if (p.endsWith('/')) { out.push(p + 'index.html', p + 'index.htm'); if (p !== '/') out.push(p.slice(0, -1)); } else if (/\.html?$/.test(p)) { out.push(p.replace(/\.html?$/, '')); if (/\/index\.html?$/.test(p)) out.push(p.replace(/index\.html?$/, '')); } else out.push(p + '/', p + '.html'); return out; };
+  for (const pg of pages) for (const k of keyVariants('/' + pg.file).concat(keyVariants(pg.path))) if (!index.has(k)) index.set(k, pg);
+
+  let baseUrl = opts.baseUrl ? String(opts.baseUrl).replace(/\/+$/, '') : null;
+  if (!baseUrl) {
+    const counts = new Map();
+    for (const pg of pages.slice(0, 60)) { const d = pg.doc; for (const v of [d.links.find((l) => l.rel.includes('canonical'))?.href, d.metaContent('og:url')]) { try { const u = new URL(v); if (/^https?:$/.test(u.protocol)) counts.set(u.origin, (counts.get(u.origin) || 0) + 1); } catch { /* relative */ } } }
+    baseUrl = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+  }
+  let origin = null; let basePath = '';
+  if (baseUrl) { try { const u = new URL(baseUrl); origin = u.origin; basePath = u.pathname.replace(/\/+$/, ''); } catch { throw Object.assign(new Error(`Invalid base URL: ${baseUrl}`), { code: 'EINVAL', usage: true }); } }
+  const site = { dir, files, pages, baseUrl, origin, basePath, inferredBase: !opts.baseUrl && !!baseUrl };
+  site.urlOf = (pg) => (origin ? origin + basePath + pg.path : pg.path);
+  /** Absolute URL object for href as seen from page (honours <base href>). */
+  site.resolve = (pg, href) => {
+    if (href == null) return null; href = String(href).trim();
+    if (!href || /^(javascript|mailto|tel|data|sms|ftp|blob):/i.test(href)) return null;
+    const pageUrl = (origin || 'http://site.invalid') + basePath + pg.path;
+    try { const b = pg.doc?.base ? new URL(pg.doc.base, pageUrl).href : pageUrl; return new URL(href, b); } catch { return null; }
+  };
+  site.isInternal = (u) => { if (!u) return false; const o = origin || 'http://site.invalid'; if (u.origin === o) return true; if (origin) { try { const a = new URL(o); return u.hostname.replace(/^www\./, '') === a.hostname.replace(/^www\./, '') && false; } catch { return false; } } return false; };
+  /** Find the page for a URL / path / URL object. Returns undefined for external or unknown. */
+  site.find = (x) => {
+    let path;
+    if (x instanceof URL) { if (!(x.origin === (origin || 'http://site.invalid'))) return undefined; path = x.pathname; }
+    else { const s = String(x); if (/^[a-z][a-z0-9+.-]*:/i.test(s)) { try { const u = new URL(s); if (u.origin !== (origin || 'http://site.invalid')) return undefined; path = u.pathname; } catch { return undefined; } } else path = s; }
+    if (basePath && path.startsWith(basePath)) path = path.slice(basePath.length) || '/';
+    for (const k of keyVariants(path)) { const pg = index.get(k); if (pg) return pg; }
+    return undefined;
+  };
+  site.read = (rel) => { try { return readFileSync(join(dir, rel), 'utf8'); } catch { return null; } };
+  site.exists = (rel) => existsSync(join(dir, rel));
+  const rules = loadHeaderRules(dir);
+  site.headerRules = rules;
+  site.headersFor = (path) => { const out = {}; for (const r of rules) if (r.re.test(path) || r.re.test(path.replace(/\/$/, '')) ) for (const [k, v] of r.headers) (out[k] ||= []).push({ value: v, source: r.source, line: r.line }); return out; };
+  return site;
+}
+
+/** Header rules from Netlify / Cloudflare Pages `_headers` and `vercel.json`. */
+export function loadHeaderRules(dir) {
+  const rules = [];
+  const hf = join(dir, '_headers');
+  if (existsSync(hf)) {
+    let cur = null;
+    readFileSync(hf, 'utf8').split(/\r?\n/).forEach((l, i) => {
+      if (!l.trim() || l.trim().startsWith('#')) return;
+      if (!/^\s/.test(l)) { const pat = l.trim(); cur = { source: '_headers', line: i + 1, pattern: pat, re: pathPatternRe(pat), headers: [] }; rules.push(cur); }
+      else if (cur) { const m = /^\s+([^:]+):\s*(.*)$/.exec(l); if (m) cur.headers.push([m[1].trim().toLowerCase(), m[2].trim()]); }
+    });
+  }
+  for (const f of ['vercel.json', '../vercel.json']) {
+    const vf = join(dir, f); if (!existsSync(vf)) continue;
+    try { const j = JSON.parse(readFileSync(vf, 'utf8')); const text = readFileSync(vf, 'utf8').split('\n'); for (const h of j.headers || []) { const ln = text.findIndex((l) => l.includes(JSON.stringify(h.source))) + 1 || undefined; rules.push({ source: f.replace('../', ''), line: ln, pattern: h.source, re: pathPatternRe(h.source), headers: (h.headers || []).map((x) => [String(x.key).toLowerCase(), String(x.value)]) }); } } catch { /* ignore */ }
+    break;
+  }
+  return rules;
+}
+function pathPatternRe(p) {
+  try { if (/^https?:\/\//.test(p)) p = new URL(p).pathname; } catch { /* keep */ }
+  if (/\(.*\)/.test(p) && !/:\w/.test(p.replace(/\(.*\)/g, ''))) { try { return new RegExp('^' + p.replace(/\//g, '\\/') + '$'); } catch { /* fall through */ } }
+  let s = '';
+  for (let k = 0; k < p.length; k++) {
+    const c = p[k];
+    if (c === '*') s += '.*';
+    else if (c === ':' && /\w/.test(p[k + 1] || '')) { const m = /^:(\w+)(\*|\+|\?)?(\([^)]*\))?/.exec(p.slice(k)); k += m[0].length - 1; s += m[2] === '*' || m[2] === '+' ? '.*' : m[3] ? m[3] : '[^/]+'; }
+    else s += c.replace(/[.+^${}()|[\]\\?]/g, '\\$&');
+  }
+  return new RegExp(`^${s}$`);
+}
+
+/** Robots directives that apply to a page from meta tags and X-Robots-Tag headers. bots: lowercased names. */
+export function robotsDirectives(site, pg, bots = ['robots', 'googlebot']) {
+  const out = [];
+  for (const m of pg.doc.robots(bots)) out.push({ bot: m.name, directives: m.directives, source: 'meta', file: pg.file, line: m.line, inHead: m.inHead, raw: m.content });
+  for (const h of site.headersFor(pg.path)['x-robots-tag'] || []) {
+    const v = h.value; const mm = /^([a-z0-9_-]+)\s*:\s*(.*)$/i.exec(v);
+    const bot = mm && !/^(noindex|nofollow|none|all|index|follow|noarchive|nosnippet|unavailable_after|max-snippet|max-image-preview|max-video-preview|noimageindex|notranslate|indexifembedded)$/i.test(mm[1]) ? mm[1].toLowerCase() : 'robots';
+    const body = bot === 'robots' ? v : mm[2];
+    if (bot === 'robots' || bots.includes(bot)) out.push({ bot, directives: body.toLowerCase().split(',').map((d) => d.trim()).filter(Boolean), source: 'header', file: h.source, line: h.line, raw: v });
+  }
+  return out;
+}
+export const isNoindex = (dirs) => dirs.some((d) => d.directives.some((x) => x === 'noindex' || x === 'none'));
+
+/** Page-level helpers shared across beacons. */
+export function canonicalOf(site, pg) {
+  const c = pg.doc.links.filter((l) => l.rel.includes('canonical') && l.href != null);
+  const hdr = (site.headersFor(pg.path).link || []).map((h) => /<([^>]+)>\s*;\s*rel="?canonical"?/i.exec(h.value)?.[1]).filter(Boolean);
+  const href = c.find((l) => l.inHead)?.href ?? c[0]?.href ?? hdr[0] ?? null;
+  return { href, url: href != null ? site.resolve(pg, href) : null, tags: c, header: hdr };
+}
+
+/** Very small JSON-LD helpers. */
+export function jsonldNodes(doc) {
+  const out = [];
+  const visit = (n, block, depth = 0) => {
+    if (Array.isArray(n)) { n.forEach((x) => visit(x, block, depth)); return; }
+    if (!n || typeof n !== 'object') return;
+    if (n['@graph']) visit(n['@graph'], block, depth);
+    if (n['@type']) out.push({ node: n, types: [].concat(n['@type']).map(String), line: block.line, depth });
+    for (const [k, v] of Object.entries(n)) if (k !== '@graph' && k !== '@context' && v && typeof v === 'object') visit(v, block, depth + 1);
+  };
+  for (const b of doc.jsonld) if (b.data) visit(b.data, b);
+  return out;
+}
+export const typeName = (t) => String(t).replace(/^https?:\/\/schema\.org\//, '').replace(/^schema:/, '');
+
+// ---------------------------------------------------------------------------------------------- CLI glue
+export const SITE_OPTIONS = { 'base-url': { type: 'string' }, include: { type: 'string', multiple: true }, exclude: { type: 'string', multiple: true }, 'clean-urls': { type: 'boolean' } };
+export const SITE_HELP = `Site
+      --base-url <url>        Public URL of the site, e.g. https://example.com (default: inferred from canonical/og:url)
+      --include <globs>       Only check these pages (file or URL path globs, comma-separated)
+      --exclude <globs>       Skip these pages
+      --clean-urls            Pages are served without .html (about.html -> /about)
+`;
+const list = (v) => (v || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
+export function siteOptions(o = {}, config = {}) {
+  return { baseUrl: o['base-url'] ?? config.baseUrl, include: [...list(config.include), ...list(o.include)], exclude: [...list(config.exclude), ...list(o.exclude)], cleanUrls: o['clean-urls'] ?? config.cleanUrls ?? false };
+}
+/** Run a beacon: loads the site, calls analyze(site, opts) -> { findings, info, summary }, returns a report via buildReport. */
+export function runBeacon(tool, dir, opts, config, configFile, analyze, buildReport) {
+  let site;
+  try { site = loadSite(dir, siteOptions(opts.cli || {}, { ...config, ...pick(opts, ['baseUrl', 'include', 'exclude', 'cleanUrls']) })); }
+  catch (e) { if (e.usage || e.code === 'ENOENT') { const U = opts.UsageError || Error; throw new U(e.message); } throw e; }
+  const { findings, info = {}, summary } = analyze(site, opts, config);
+  const line = summary ?? `${site.pages.length} page(s)${site.baseUrl ? ` at ${site.baseUrl}${site.inferredBase ? ' (inferred)' : ''}` : ' (no base URL; pass --base-url)'}`;
+  return buildReport(tool, site.baseUrl || dir, findings, config, { now: opts.now, configFile, summaryLine: line, info: { pages: site.pages.length, baseUrl: site.baseUrl, ...info } });
+}
+function pick(o, keys) { const r = {}; for (const k of keys) if (o[k] !== undefined && !(Array.isArray(o[k]) && !o[k].length)) r[k] = o[k]; return r; }
+/** Finding factory bound to a rule table. */
+export function finder(RULES, findings = []) {
+  const add = (rule, subject, message, fix, loc = {}) => { if (!RULES[rule]) throw new Error(`unknown rule ${rule}`); findings.push({ rule, severity: loc.severity || RULES[rule].severity, subject, file: loc.file, line: loc.line, message, fix }); };
+  return { findings, add };
+}
+/** Redirect stubs (meta refresh) and error pages are skipped by most checks. */
+export const isRedirectStub = (pg) => pg.doc.metas.some((m) => m.httpEquiv === 'refresh');
+export const isErrorPage = (pg) => /(^|\/)(404|500|50x|error)(\/index)?\.html?$/i.test(pg.file);
+export const contentPages = (site) => site.pages.filter((p) => !isRedirectStub(p) && !isErrorPage(p));
+/** Published / modified dates a page declares (JSON-LD, Open Graph article tags, <time itemprop>, meta). Values are Date or null. */
+export function pageDates(doc) {
+  const pick = (vals) => { for (const v of vals) { if (!v) continue; const d = new Date(String(v).trim()); if (!Number.isNaN(d.getTime())) return d; } return null; };
+  const ld = jsonldNodes(doc).map((n) => n.node);
+  const ldv = (k) => ld.map((n) => [].concat(n[k] ?? [])[0]).filter(Boolean);
+  const timeProp = (k) => doc.all.filter((e) => e.attrs.itemprop === k).map((e) => e.attrs.datetime || e.attrs.content);
+  return {
+    published: pick([...ldv('datePublished'), doc.metaContent('article:published_time'), ...timeProp('datePublished'), doc.metaContent('date'), doc.metaContent('dc.date'), doc.metaContent('pubdate')]),
+    modified: pick([...ldv('dateModified'), doc.metaContent('article:modified_time'), doc.metaContent('og:updated_time'), ...timeProp('dateModified'), doc.metaContent('last-modified')]),
+  };
+}