gazetta 0.7.0 → 0.8.0

package/dist/validation/scanner.js

@@ -0,0 +1,327 @@
+/**
+ * Background validation scanner — runs all background-stage validators across
+ * the site and exposes the resulting issues to the admin API + admin UI.
+ *
+ * Per design-validation.md "Background scanner (Cut 2)" + the implementation
+ * plan in design-validation-implementation.md:
+ *
+ * - Initial full-site scan on admin boot.
+ * - Incremental rescan after save: affected item + transitive dependents
+ *   (fragment edits invalidate pages via `findDependentsFromSidecars`; asset
+ *   edits invalidate referencing items via `readRefsForAsset`; template edits
+ *   trigger a full-site rescan since no `template-deps` reverse-dep relation
+ *   exists yet).
+ * - Per-item validation cache keyed by content hash (via `AdminCache`).
+ *   Same content = same issues; cache hit short-circuits the validators.
+ * - Result store keyed by item path; reads return current issues.
+ * - SSE subscribers fired when a scan pass completes (admin UI dot updates).
+ *
+ * # Multi-instance discipline
+ *
+ * The scanner is per-instance scope. Each admin instance maintains its own
+ * result store + cache; SSE invalidation isn't broadcast across instances.
+ * Acceptable because: (a) each instance scans independently from the same
+ * source-of-truth storage; (b) save-side invalidation is per-instance via
+ * the same code path that wrote the manifest; (c) external changes (git
+ * pull) flow through `gazetta dev`'s file watcher per-instance.
+ *
+ * # SOLID lenses
+ *
+ * - SRP: scanner orchestrates passes. It doesn't implement validators
+ *   (that's per-validator) and doesn't render UI (that's the admin UI).
+ * - DIP: depends on `AdminCache` interface, not `MemoryCache`; depends on
+ *   the validator registry contract, not specific validators.
+ * - OCP: adding a new background-stage validator means registering it in
+ *   `defaultValidatorRegistry()`; the scanner picks it up automatically
+ *   via `registry.forStage('background')`.
+ */
+import { createHash } from 'node:crypto';
+import { findDependentsFromSidecars } from '../publish.js';
+import { renderPageForAnalysis } from '../render-for-analysis.js';
+import { allFragmentEntries, allPageEntries, loadSite } from '../site-loader.js';
+/**
+ * Construct a scanner. The scanner doesn't kick off `scanAll()` automatically;
+ * callers (CLI boot path) call it after constructing.
+ */
+export function createValidationScanner(opts) {
+    const { storage, contentRoot, registry, cache, siteOptions } = opts;
+    const loadSiteFn = opts.loadSiteImpl ?? loadSite;
+    const issuesByItem = new Map();
+    const subscribers = new Set();
+    function setIssues(itemPath, issues) {
+        if (issues.length === 0)
+            issuesByItem.delete(itemPath);
+        else
+            issuesByItem.set(itemPath, [...issues]);
+    }
+    function totalIssues() {
+        let n = 0;
+        for (const arr of issuesByItem.values())
+            n += arr.length;
+        return n;
+    }
+    function emit(event) {
+        for (const sub of subscribers) {
+            try {
+                sub(event);
+            }
+            catch {
+                // Subscriber faults isolated; one bad subscriber doesn't block siblings.
+            }
+        }
+    }
+    async function loadFreshSite() {
+        return loadSiteFn({ contentRoot, ...siteOptions });
+    }
+    async function validateItem(site, item, manifest) {
+        const hash = hashManifestStable(manifest);
+        const key = cacheKey(item, hash);
+        const cached = await cache.get(key);
+        if (cached !== null) {
+            // Re-stamp the store from cache (cheap; covers boot warm-up too).
+            setIssues(item.itemPath, cached);
+            return cached;
+        }
+        const validators = registry.forStage('background');
+        const renderedOutput = makeRenderedOutputAccess(site);
+        const issues = [];
+        for (const v of validators) {
+            try {
+                const out = await v.validate({
+                    stage: 'background',
+                    site,
+                    contentRoot,
+                    storage,
+                    scope: { kind: 'background', item, manifest },
+                    renderedOutput,
+                });
+                issues.push(...out);
+            }
+            catch (err) {
+                // Validator threw — surface as an info issue so the scan finishes.
+                issues.push({
+                    validator: v.name,
+                    severity: 'info',
+                    message: `Validator "${v.name}" failed: ${err.message}`,
+                    itemPath: item.itemPath,
+                });
+            }
+        }
+        await cache.set(key, issues);
+        setIssues(item.itemPath, issues);
+        return issues;
+    }
+    /**
+     * Build a `RenderedOutputAccess` adapter for this scan pass. Validators
+     * that need rendered HTML (a11y, html-validity) opt in via the
+     * `renderedOutput` field of their input. Validators that don't need it
+     * (the 5 ref-existence validators, schema-conformance, altRequired) can
+     * ignore the field — they don't trigger a render.
+     *
+     * The render is itself cached via render-for-analysis's own AdminCache
+     * key (content + template + dependency hash), separate from the scanner's
+     * issues cache. Same content = same HTML across scans.
+     *
+     * Fragments aren't rendered as full pages; `htmlFor` returns null for
+     * fragment items. Validators that consume rendered output guard on null.
+     */
+    function makeRenderedOutputAccess(site) {
+        return {
+            async htmlFor(item) {
+                if (item.kind !== 'page')
+                    return null;
+                if (!siteOptions.templatesDir)
+                    return null;
+                const out = await renderPageForAnalysis(item.name, {
+                    site,
+                    cache,
+                    templatesDir: siteOptions.templatesDir,
+                });
+                return out?.html ?? null;
+            },
+        };
+    }
+    // Shared full-site walk — extracted so scanAll(), rescan({template}),
+    // and rescan({full}) share the body. Returns the loaded `site` +
+    // wall-clock + count so the caller can decide what the ScanEvent
+    // carries (e.g., template rescan adds affectedItemCount to the cause
+    // before emitting).
+    async function fullScanWalk() {
+        const start = Date.now();
+        const site = await loadFreshSite();
+        let scanned = 0;
+        const seen = new Set();
+        for (const entry of allPageEntries(site)) {
+            const item = {
+                kind: 'page',
+                name: entry.name,
+                itemPath: itemPathFor('page', entry.page.dir, entry.locale),
+            };
+            if (seen.has(item.itemPath))
+                continue;
+            seen.add(item.itemPath);
+            await validateItem(site, item, entry.page);
+            scanned++;
+        }
+        for (const entry of allFragmentEntries(site)) {
+            const item = {
+                kind: 'fragment',
+                name: entry.name,
+                itemPath: itemPathFor('fragment', entry.fragment.dir, entry.locale),
+            };
+            if (seen.has(item.itemPath))
+                continue;
+            seen.add(item.itemPath);
+            await validateItem(site, item, entry.fragment);
+            scanned++;
+        }
+        // Stale items in the store (deleted since last scan) get pruned.
+        for (const path of [...issuesByItem.keys()]) {
+            if (!seen.has(path))
+                issuesByItem.delete(path);
+        }
+        return { site, durationMs: Date.now() - start, scanned };
+    }
+    async function scanAll() {
+        const { durationMs, scanned } = await fullScanWalk();
+        emit({ durationMs, scanned, totalIssues: totalIssues() });
+    }
+    async function rescan(cause) {
+        if (cause.kind === 'template') {
+            // Template rescan = full-site walk. Compute affectedItemCount
+            // post-walk so the emitted ScanEvent (and downstream SSE
+            // template-changed event) carries the banner's "N items
+            // affected" number in one go — no double emit, no client-side
+            // re-walk. Affected = items using the template that have any
+            // issue post-scan; issuesByItem is up to date by this point.
+            const { site, durationMs, scanned } = await fullScanWalk();
+            let affectedItemCount;
+            try {
+                const { computeTemplateImpact } = await import('./template-impact.js');
+                affectedItemCount = computeTemplateImpact(site, cause.name, path => issuesByItem.get(path) ?? []).affectedItemCount;
+            }
+            catch (err) {
+                // Best-effort — banner just shows the template name without a
+                // count when this fails. The walk's per-item issues already
+                // surfaced via the regular store, which feeds dots + drawer.
+                console.warn(`  Validation scanner: template-impact count failed for "${cause.name}": ${err.message}`);
+            }
+            emit({
+                durationMs,
+                scanned,
+                totalIssues: totalIssues(),
+                cause: { ...cause, affectedItemCount },
+            });
+            return;
+        }
+        if (cause.kind === 'full') {
+            const { durationMs, scanned } = await fullScanWalk();
+            emit({ durationMs, scanned, totalIssues: totalIssues(), cause });
+            return;
+        }
+        const start = Date.now();
+        const site = await loadFreshSite();
+        let scanned = 0;
+        const targets = await targetsForCause(cause, site, contentRoot);
+        for (const target of targets) {
+            const manifest = manifestForItem(site, target);
+            if (!manifest)
+                continue; // item disappeared between save and rescan
+            await validateItem(site, target, manifest);
+            scanned++;
+        }
+        emit({ durationMs: Date.now() - start, scanned, totalIssues: totalIssues(), cause });
+    }
+    function allIssues() {
+        const out = [];
+        for (const arr of issuesByItem.values())
+            out.push(...arr);
+        return out;
+    }
+    function issuesFor(itemPath) {
+        return issuesByItem.get(itemPath) ?? [];
+    }
+    function subscribe(handler) {
+        subscribers.add(handler);
+        return () => subscribers.delete(handler);
+    }
+    return { scanAll, rescan, allIssues, issuesFor, subscribe };
+}
+// ---- helpers --------------------------------------------------------------
+function itemPathFor(kind, dir, locale) {
+    const base = kind === 'page' ? 'page' : 'fragment';
+    const ext = locale ? `${base}.${locale}.json` : `${base}.json`;
+    return `${dir}/${ext}`;
+}
+/**
+ * Stable hash of a manifest for cache keying. Crypto-grade — same content =
+ * same hash across processes. Different from the publish-time
+ * `hashManifest()` (which folds in template + fragment hashes); the scanner
+ * cares only about manifest content for invalidation purposes.
+ *
+ * Canonicalizes nested objects by recursively sorting keys before
+ * serializing. JSON.stringify's replacer-array form only filters top-level
+ * keys, which would silently miss nested mutations.
+ */
+function hashManifestStable(manifest) {
+    return createHash('sha256').update(canonicalJson(manifest)).digest('hex').slice(0, 16);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map(k => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`);
+    return `{${parts.join(',')}}`;
+}
+function cacheKey(item, contentHash) {
+    return `validation:${item.kind}:${encodePath(item.itemPath)}:${contentHash}`;
+}
+function encodePath(path) {
+    return path.replace(/[/]/g, '.').replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+async function targetsForCause(cause, site, contentRoot) {
+    if (cause.kind === 'manifest')
+        return [cause.item];
+    if (cause.kind === 'fragment') {
+        // Affected: the fragment itself + every page/fragment that references it.
+        const out = [];
+        const frag = site.fragments.get(cause.name);
+        if (frag) {
+            out.push({ kind: 'fragment', name: cause.name, itemPath: `${frag.dir}/fragment.json` });
+        }
+        const dependents = await findDependentsFromSidecars(contentRoot, { fragment: cause.name });
+        for (const pageName of dependents.pages) {
+            const page = site.pages.get(pageName);
+            if (page)
+                out.push({ kind: 'page', name: pageName, itemPath: `${page.dir}/page.json` });
+        }
+        for (const fragName of dependents.fragments) {
+            const f = site.fragments.get(fragName);
+            if (f)
+                out.push({ kind: 'fragment', name: fragName, itemPath: `${f.dir}/fragment.json` });
+        }
+        return out;
+    }
+    if (cause.kind === 'asset') {
+        // readRefsForAsset would re-introduce a coupling we don't want here;
+        // for v1, treat asset edits as full-site rescan. The cost is low at
+        // envelope (5K pages x ~10ms validate per item = 50s worst case;
+        // typical scans are <1s thanks to cache hits).
+        const out = [];
+        for (const entry of allPageEntries(site)) {
+            out.push({ kind: 'page', name: entry.name, itemPath: itemPathFor('page', entry.page.dir, entry.locale) });
+        }
+        return out;
+    }
+    // Unreachable per type guards above.
+    return [];
+}
+function manifestForItem(site, item) {
+    if (item.kind === 'page')
+        return site.pages.get(item.name) ?? null;
+    return site.fragments.get(item.name) ?? null;
+}
+//# sourceMappingURL=scanner.js.map

package/dist/validation/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../../src/validation/scanner.ts"],"names":[],"mappings":"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"}

package/dist/validation/template-impact.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Template impact analysis (Validation Cut 6).
+ *
+ * Walks the loaded site to find every page + fragment that uses a given
+ * template — top-level (manifest.template === templateName) AND nested
+ * inline components (recursively). Pairs with the scanner store's
+ * `issuesFor(itemPath)` to project the per-template impact view that
+ * the DevPlayground "Impact" tab + the toolbar banner consume.
+ *
+ * Surface shape matches what `GET /api/templates/:name/impact` returns:
+ * a flat list of items, ordered pages-first then fragments, with
+ * deduplication so a page that uses the template multiple times shows
+ * once (its issues already aggregate at the item level).
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the template→items walk. Issue lookup
+ *     stays at the scanner; rendering stays at the route.
+ *   - DIP: takes the loaded `Site` + a thin issue-lookup function.
+ *     No coupling to the scanner's internal store.
+ *   - OCP: adding a new component-nesting shape (e.g., grid columns
+ *     carrying templates) extends the recursive walk without
+ *     touching the lookup function.
+ */
+import type { Site } from '../site-loader.js';
+import type { Issue } from './types.js';
+export interface TemplateImpactItem {
+    /** Page or fragment. */
+    kind: 'page' | 'fragment';
+    /** Item name (e.g., 'home' or 'header'). */
+    name: string;
+    /** Manifest path matching the scanner's itemPath shape. */
+    itemPath: string;
+    /** Issues from the scanner store for this item. May be empty (clean). */
+    issues: readonly Issue[];
+}
+export interface TemplateImpactResult {
+    /** The template the impact view describes. */
+    template: string;
+    /** Items using the template, pages first then fragments. */
+    items: readonly TemplateImpactItem[];
+    /** Convenience: items.filter(i => i.issues.length > 0).length. */
+    affectedItemCount: number;
+}
+/**
+ * Compute the impact view for `templateName` against `site`.
+ *
+ * `issuesFor(itemPath)` is the scanner's per-item issue lookup —
+ * passed in so this module stays decoupled from the scanner.
+ */
+export declare function computeTemplateImpact(site: Site, templateName: string, issuesFor: (itemPath: string) => readonly Issue[]): TemplateImpactResult;
+//# sourceMappingURL=template-impact.d.ts.map

package/dist/validation/template-impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-impact.d.ts","sourceRoot":"","sources":["../../src/validation/template-impact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAG7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACpC,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,KAAK,EAAE,GAChD,oBAAoB,CAqBtB"}

package/dist/validation/template-impact.js

@@ -0,0 +1,53 @@
+import { manifestComponents } from './types.js';
+/**
+ * Compute the impact view for `templateName` against `site`.
+ *
+ * `issuesFor(itemPath)` is the scanner's per-item issue lookup —
+ * passed in so this module stays decoupled from the scanner.
+ */
+export function computeTemplateImpact(site, templateName, issuesFor) {
+    const items = [];
+    const seen = new Set();
+    for (const [name, page] of site.pages) {
+        if (!usesTemplate(page, templateName))
+            continue;
+        const itemPath = `${page.dir}/page.json`;
+        if (seen.has(itemPath))
+            continue;
+        seen.add(itemPath);
+        items.push({ kind: 'page', name, itemPath, issues: issuesFor(itemPath) });
+    }
+    for (const [name, fragment] of site.fragments) {
+        if (!usesTemplate(fragment, templateName))
+            continue;
+        const itemPath = `${fragment.dir}/fragment.json`;
+        if (seen.has(itemPath))
+            continue;
+        seen.add(itemPath);
+        items.push({ kind: 'fragment', name, itemPath, issues: issuesFor(itemPath) });
+    }
+    const affectedItemCount = items.reduce((n, item) => (item.issues.length > 0 ? n + 1 : n), 0);
+    return { template: templateName, items, affectedItemCount };
+}
+/**
+ * Does this manifest (or any of its nested inline components) reference
+ * `templateName`? Top-level template + recursive component walk.
+ */
+function usesTemplate(manifest, templateName) {
+    if (manifest.template === templateName)
+        return true;
+    return entriesReferenceTemplate(manifestComponents(manifest), templateName);
+}
+function entriesReferenceTemplate(entries, templateName) {
+    for (const entry of entries) {
+        if (typeof entry === 'string')
+            continue; // fragment ref — not a template ref
+        const inline = entry;
+        if (inline.template === templateName)
+            return true;
+        if (inline.components && entriesReferenceTemplate(inline.components, templateName))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=template-impact.js.map

package/dist/validation/template-impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-impact.js","sourceRoot":"","sources":["../../src/validation/template-impact.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAuB/C;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAU,EACV,YAAoB,EACpB,SAAiD;IAEjD,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAE9B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACtC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,YAAY,CAAC;YAAE,SAAQ;QAC/C,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,GAAG,YAAY,CAAA;QACxC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAQ;QAChC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IAC3E,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAC9C,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,CAAC;YAAE,SAAQ;QACnD,MAAM,QAAQ,GAAG,GAAG,QAAQ,CAAC,GAAG,gBAAgB,CAAA;QAChD,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAQ;QAChC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IAC/E,CAAC;IAED,MAAM,iBAAiB,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC5F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAA;AAC7D,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,QAAyC,EAAE,YAAoB;IACnF,IAAI,QAAQ,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO,IAAI,CAAA;IACnD,OAAO,wBAAwB,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,CAAA;AAC7E,CAAC;AAED,SAAS,wBAAwB,CAAC,OAAkC,EAAE,YAAoB;IACxF,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAQ,CAAC,oCAAoC;QAC5E,MAAM,MAAM,GAAG,KAAwB,CAAA;QACvC,IAAI,MAAM,CAAC,QAAQ,KAAK,YAAY;YAAE,OAAO,IAAI,CAAA;QACjD,IAAI,MAAM,CAAC,UAAU,IAAI,wBAAwB,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC;YAAE,OAAO,IAAI,CAAA;IACjG,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/validation/types.d.ts

@@ -0,0 +1,123 @@
+import type { ComponentEntry, PageManifest, FragmentManifest, StorageProvider } from '../types.js';
+import type { Site } from '../site-loader.js';
+import type { ContentRoot } from '../content-root.js';
+/**
+ * Lifecycle stages a validator can run at. Per design-validation.md,
+ * these correspond to the four-phase model.
+ */
+export type ValidationStage = 'save-delta' | 'background' | 'pre-publish' | 'cli';
+/**
+ * Severity of a single issue. Per stage, validators declare a default;
+ * operators can promote/demote at the publish gate (Cut 4).
+ */
+export type Severity = 'error' | 'warn' | 'info';
+/**
+ * One validation finding. Stable shape across all validators and stages.
+ */
+export interface Issue {
+    /** Stable identifier of the validator that produced this issue. */
+    validator: string;
+    severity: Severity;
+    /** Human-readable message. Author-facing. */
+    message: string;
+    /** Item path like `pages/home/page.json`. */
+    itemPath: string;
+    /** Content-tree path within the manifest, when applicable. */
+    contentPath?: string;
+    /**
+     * Optional structured suppression hint — `Issue.suppressible: true`
+     * means a future "ignore this issue" mechanism would apply.
+     */
+    suppressible?: boolean;
+}
+/**
+ * Stage-specific scope. Validators dispatch on `scope.kind` to read the right input.
+ *
+ * - `save-delta`: a single item (page or fragment) being saved, with before+after.
+ * - `background`: a single item being scanned (after the scanner has detected change).
+ * - `pre-publish`: the set of items being published, all together.
+ * - `cli`: site-wide; validator iterates everything.
+ */
+export type ValidatorScope = {
+    kind: 'save-delta';
+    item: SavedItem;
+    /** The on-disk manifest before this save (null when creating a new item). */
+    before: PageManifest | FragmentManifest | null;
+    /** The incoming manifest being saved. */
+    after: PageManifest | FragmentManifest;
+} | {
+    kind: 'background';
+    item: SavedItem;
+    /**
+     * The current manifest read by the scanner. Pre-loaded so validators
+     * stay pure functions over (manifest, site) — no per-validator storage
+     * reads.
+     */
+    manifest: PageManifest | FragmentManifest;
+} | {
+    kind: 'pre-publish';
+    items: readonly SavedItem[];
+} | {
+    kind: 'cli';
+};
+/**
+ * Identifies a page or fragment item. The validator framework treats them
+ * uniformly for stage dispatch; validators that only apply to one or the other
+ * branch on `kind`.
+ */
+export interface SavedItem {
+    kind: 'page' | 'fragment';
+    /** Logical name, e.g. `home`, `blog/[slug]`, `header`. */
+    name: string;
+    /** Filesystem path to the manifest, e.g. `pages/home/page.json`. */
+    itemPath: string;
+}
+/**
+ * Hook for cached rendered HTML output. Populated by Cut 3 (render-for-analysis);
+ * absent in Cut 1 (save-delta), so validators must guard against undefined.
+ */
+export interface RenderedOutputAccess {
+    htmlFor(item: SavedItem): Promise<string | null>;
+}
+/**
+ * Inputs every validator receives. Stage-specific data lives in `scope`;
+ * validators that don't care about a stage simply don't include it in `stages`
+ * and won't be invoked.
+ */
+export interface ValidatorInput {
+    stage: ValidationStage;
+    site: Site;
+    contentRoot: ContentRoot;
+    storage: StorageProvider;
+    scope: ValidatorScope;
+    renderedOutput?: RenderedOutputAccess;
+}
+/**
+ * The validator contract. One implementation per validation rule.
+ *
+ * - `source` — package identity for diagnostics + audit + plugin-promotion.
+ *   In-tree validators use `'gazetta'`; npm-distributed validators use their
+ *   package name (`'@example/link-checker'`); site-local factories use
+ *   `'site-local:{name}'`. Per design-plugins.md "source convention" + ADR-0009.
+ * - `name` — stable identifier referenced from issues and registry lookup.
+ * - `stages` — which lifecycle stages this validator runs at. Save-delta-only
+ *   validators (most ref-existence checks) declare `['save-delta', 'background', 'pre-publish', 'cli']`
+ *   so the same rule fires uniformly at every gate.
+ * - `defaultSeverity(stage)` — what severity issues from this validator have
+ *   at the given stage. The same rule may be `error` at save-delta but `warn`
+ *   in background to avoid false-positive blocks on accumulated debt.
+ * - `validate(input)` — run the rule. Never throws on validation failure;
+ *   throws are reserved for infrastructure errors (storage failure, etc).
+ */
+export interface Validator {
+    readonly source: string;
+    readonly name: string;
+    readonly stages: readonly ValidationStage[];
+    defaultSeverity(stage: ValidationStage): Severity;
+    validate(input: ValidatorInput): Promise<Issue[]>;
+}
+/**
+ * Helper — extract the components array from a manifest, defaulting to empty.
+ */
+export declare function manifestComponents(manifest: PageManifest | FragmentManifest | null): readonly ComponentEntry[];
+//# sourceMappingURL=types.d.ts.map

package/dist/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,GAAG,KAAK,CAAA;AAEjF;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;AAEhD;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,QAAQ,CAAA;IAClB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,YAAY,CAAA;IAClB,IAAI,EAAE,SAAS,CAAA;IACf,6EAA6E;IAC7E,MAAM,EAAE,YAAY,GAAG,gBAAgB,GAAG,IAAI,CAAA;IAC9C,yCAAyC;IACzC,KAAK,EAAE,YAAY,GAAG,gBAAgB,CAAA;CACvC,GACD;IACE,IAAI,EAAE,YAAY,CAAA;IAClB,IAAI,EAAE,SAAS,CAAA;IACf;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,gBAAgB,CAAA;CAC1C,GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAA;AAEnB;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IACzB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,eAAe,CAAA;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,WAAW,EAAE,WAAW,CAAA;IACxB,OAAO,EAAE,eAAe,CAAA;IACxB,KAAK,EAAE,cAAc,CAAA;IACrB,cAAc,CAAC,EAAE,oBAAoB,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;IAC3C,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAAA;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,gBAAgB,GAAG,IAAI,GAAG,SAAS,cAAc,EAAE,CAE9G"}

package/dist/validation/types.js

@@ -0,0 +1,7 @@
+/**
+ * Helper — extract the components array from a manifest, defaulting to empty.
+ */
+export function manifestComponents(manifest) {
+    return manifest?.components ?? [];
+}
+//# sourceMappingURL=types.js.map

package/dist/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AA8HA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgD;IACjF,OAAO,QAAQ,EAAE,UAAU,IAAI,EAAE,CAAA;AACnC,CAAC"}

package/dist/validation/validators/accessibility.d.ts

@@ -0,0 +1,3 @@
+import type { Validator } from '../types.js';
+export declare const accessibility: Validator;
+//# sourceMappingURL=accessibility.d.ts.map

package/dist/validation/validators/accessibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.d.ts","sourceRoot":"","sources":["../../../src/validation/validators/accessibility.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAS,SAAS,EAAkB,MAAM,aAAa,CAAA;AAiCnE,eAAO,MAAM,aAAa,EAAE,SAoC3B,CAAA"}