@pseolint/core 0.4.3 → 0.5.4

package/README.md

@@ -1,170 +1,265 @@
-# @pseolint/core
-
-> Programmatic SEO audit engine for SpamBrain-risk detection across large template-generated sites.
-
-The core engine behind [pseolint](https://www.npmjs.com/package/pseolint). Use this package to embed pSEO auditing into your own tools, CI pipelines, or SaaS products.
-
-## Install
-
-```bash
-npm install @pseolint/core
-```
-
-## Usage
-
-```ts
-import { auditSource } from "@pseolint/core";
-
-const summary = await auditSource("./out");
-console.log(`Score: ${summary.score}/100`);
-console.log(`Findings: ${summary.findings.length}`);
-```
-
-`auditSource` accepts a local directory, a single HTML file, a page URL, or a sitemap URL.
-
-## What It Checks
-
-32 rules grouped into 4 scoring super-categories (v0.4): **Integrity** (spam + content + cannibal, weight 0.50), **Discoverability** (links + tech, 0.20), **Citation** (aeo + schema, 0.25), **Data** (0.05). Source-tree namespaces remain `spam/*`, `aeo/*`, etc. for stable rule IDs.
-
-- **Spam / SpamBrain risk** (8) — near-duplicate (SimHash), entity-swap doorways, thin content, boilerplate ratio, template diversity, template coverage, publication velocity, doorway pattern
-- **Technical SEO** (8) — canonical consistency, canonical/noindex and robots/noindex conflicts, sitemap completeness, robots compliance, redirect chains, soft 404s, Open Graph, hreflang
-- **AEO / AI Overview citability** (9, v0.3.0–v0.3.1) — `llms.txt` presence, AI-crawler access in robots.txt, freshness signals, FAQ coverage, answer-first opener, citable-fact density, non-replicable value, content modularity, **summary-bait** (pages optimized for summarization over retention)
-- **Content** (5) — unique value, heading / meta uniqueness, author attribution, E-E-A-T signals
-- **Internal linking** (5) — orphan pages, dead ends, cluster connectivity, hub pages, link depth
-- **Structured data** (3) — JSON-LD validity, required fields, cross-page schema consistency
-- **Cannibalization** (3) — title overlap, keyword collision, URL pattern conflicts
-- **Data binding** (2) — verify rendered pages expose values from a source dataset (missing or identical-across-pages bindings)
-
-## API
-
-### `auditSource(source, options?)`
-
-Returns an `AuditSummary` with composite score, category scores, enriched findings, and optional cache / state / AI-triage metadata.
-
-Selected options (see `AuditOptions` in `types.ts` for the full surface):
-
-```ts
-await auditSource("https://example.com/sitemap.xml", {
-  concurrency: 5,
-  timeout: 30_000,
-  sampleSize: 200,
-  samplingStrategy: "stratified",        // or "random"
-  ignore: ["**/api/**"],
-  maxFetchBytes: 52_428_800,             // 50 MB hard cap per run
-  cache: { dir: ".pseolint/cache", ttlMs: 7 * 24 * 60 * 60 * 1000 },
-  state: { path: ".pseolint/state.json", since: true, exitOnRegression: true },
-  pageGroups: {
-    blog:     { match: "**/blog/**", rules: ["content/*", "spam/*"] },
-    products: { match: "**/p/**",    overrides: { "spam/thin-content": { thinContentMinWords: 200 } } },
-  },
-  dataSource: { records: [{ url: "/p/*", data: { price: "$19", stock: 12 } }] },
-  entityPatterns: [{ placeholder: "[CITY]", pattern: "\\b(NYC|LA|SF)\\b", flags: "gi" }],
-  ai: { enabled: true, provider: "anthropic", model: "claude-haiku-4-5-20251001", maxCostUsd: 0.1 },
-  telemetry: { enabled: true, path: ".pseolint/telemetry.jsonl" },
-  // Safety (v0.3.2–v0.3.3)
-  safeMode: "saas",                       // "saas" | "cli" — flips guardSsrf + caps
-  guardSsrf: true,                        // DNS-validated SSRF check on every URL
-  respectRobotsTxt: true,                 // skip sitemap URLs Disallow'd by target robots.txt
-  followRedirects: true,
-  maxCrawlDiscovered: 2000,               // hard ceiling on link-discovery fan-out
-  signal: controller.signal,              // AbortSignal — ctrl-C / quota-exhausted cancels cleanly
-  rules: {
-    nearDuplicateThreshold: 0.85,
-    thinContentMinWords: 300,
-    titleOverlapThreshold: 0.8,
-    // ...
-  },
-});
-```
-
-### Safety primitives (SSRF, abort, crawl-ceiling)
-
-`@pseolint/core` ships a few primitives for hosts that run audits against
-user-submitted URLs. All are opt-in; local CLI use doesn't change.
-
-```ts
-import {
-  safeFetch,             // SSRF-safe fetch for non-audit use cases
-  validateTargetHost,    // throws SSRFError on private-range / DNS-rebinding targets
-  isPrivateOrReservedHost,
-  SSRFError,
-  DnsResolutionError,
-} from "@pseolint/core";
-
-// Validate a user-submitted URL before enqueuing:
-await validateTargetHost(new URL(userUrl).hostname);
-
-// Fetch with SSRF guard baked in:
-const res = await safeFetch(userUrl, { timeoutMs: 10_000, followRedirects: false });
-```
-
-The full audit picks up the same guard via `auditSource(url, { safeMode: "saas" })`
-or via the individual `guardSsrf` / `respectRobotsTxt` / `followRedirects` flags.
-
-### Render-mode analytics blocking
-
-Rendered audits (`options.render = {...}`) block known analytics endpoints
-by default so the audit doesn't inject fake sessions into the site owner's
-GA / Plausible / PostHog / Mixpanel / Hotjar / Sentry dashboards.
-
-```ts
-await auditSource(url, {
-  render: {
-    analyticsMode: "block",               // default — blocks ~40 analytics hosts
-    // "allow-first-party" — block third-party only
-    // "allow" — don't intercept anything
-    extraBlockedHosts: ["my-internal-metrics.corp"],
-  },
-});
-```
-
-### Formatters
-
-```ts
-import { formatConsole, formatJson, formatMarkdown, formatHtml } from "@pseolint/core";
-
-const out = formatConsole(summary);
-const json = formatJson(summary);
-const md   = formatMarkdown(summary);
-const html = formatHtml(summary);
-```
-
-### AI triage
-
-When `ai.enabled` is set, findings are clustered into root-causes by an LLM. Providers are loaded lazily from optional peer deps — install only the one you need:
-
-```bash
-npm install @ai-sdk/anthropic   # or @ai-sdk/openai, @ai-sdk/google, @ai-sdk/mistral,
-                                #    @ai-sdk/groq, @ai-sdk/xai, @ai-sdk/cohere,
-                                #    ollama-ai-provider-v2
-```
-
-```ts
-import { triageFindings, createLanguageModel, estimateCostUsd } from "@pseolint/core";
-```
-
-Cost and daily-budget caps are enforced pre-flight; results are cached on disk by default.
-
-### Delta runs & regression gating
-
-Pass `state.since: true` to audit only URLs whose content hash changed since the last run, and `state.exitOnRegression: true` to flag a run where a new rule ID fires on any previously clean URL (`summary.hasRegression`).
-
-### Caching
-
-Setting `cache` enables an ETag/Last-Modified-aware disk cache for HTTP fetches. `summary.cacheStats` reports `{ hits, total, bytesSavedEstimate }`.
-
-### Page groups
-
-Classify pages by glob and apply different rule subsets or threshold overrides per group. Results are surfaced in `summary.groupScores` / `summary.groupPageCounts`.
-
-### Rendering
-
-For client-rendered pages, install `playwright-core` and pass `render: { browserWsEndpoint }` to connect to an existing browser endpoint.
-
-## Peer dependencies
-
-All AI providers and `playwright-core` are optional peers — you only install the ones you actually use.
-
-## License
-
+# @pseolint/core
+
+> Programmatic SEO audit engine for SpamBrain-risk detection across large template-generated sites.
+
+The core engine behind [pseolint](https://www.npmjs.com/package/pseolint). Use this package to embed pSEO auditing into your own tools, CI pipelines, or SaaS products.
+
+## Install
+
+```bash
+npm install @pseolint/core
+```
+
+## Usage
+
+```ts
+import { auditSource } from "@pseolint/core";
+
+const summary = await auditSource("./out");
+console.log(`Score: ${summary.score}/100`);
+console.log(`Findings: ${summary.findings.length}`);
+```
+
+`auditSource` accepts a local directory, a single HTML file, a page URL, or a sitemap URL.
+
+## What It Checks
+
+45 rules grouped into 4 scoring super-categories (v0.4): **Integrity** (spam + content + cannibal, weight 0.50), **Discoverability** (links + tech, 0.20), **Citation** (aeo + schema, 0.25), **Data** (0.05). Source-tree namespaces remain `spam/*`, `aeo/*`, etc. for stable rule IDs.
+
+- **Spam / SpamBrain risk** (8) — near-duplicate (SimHash), entity-swap doorways, thin content, boilerplate ratio, template diversity, template coverage, publication velocity, doorway pattern (cluster-collapsed since v0.5.2)
+- **Technical SEO** (9) — canonical consistency, canonical/noindex and robots/noindex conflicts, sitemap completeness, robots compliance, redirect chains, soft 404s, hreflang reciprocity, robots-sitemap presence, **og-completeness** (v0.5.2)
+- **AEO / AI Overview citability** (8, v0.3.0–v0.3.1) — `llms.txt` presence, AI-crawler access in robots.txt, freshness signals, FAQ coverage, answer-first opener, citable-fact density, content modularity, **summary-bait** (pages optimized for summarization over retention)
+- **Content** (7) — unique value, meta uniqueness, author attribution, E-E-A-T signals, plus **title-uniqueness**, **heading-structure**, **image-alt-text** (all v0.5.2)
+- **Internal linking** (6) — orphan pages, dead ends, cluster connectivity, link depth, unreachable-from-root (sample-aware), **host-section-divergence** (v0.5.1, site-reputation-abuse detector)
+- **Structured data** (3) — JSON-LD validity, required fields, cross-page schema consistency
+- **Cannibalization** (1) — URL pattern conflicts (`title-overlap` and `keyword-collision` were dropped in v0.4 due to high false-positive rates)
+- **Data binding** (2) — verify rendered pages expose values from a source dataset (missing or identical-across-pages bindings)
+
+## What's new in v0.5.2 — credibility layer
+
+- **4 new content-quality rules** addressing the v0.5.1 blind-spot audit's tier-1 gaps: `content/title-uniqueness` (raw, not entity-masked — catalog templates with per-record entity values still pass), `content/heading-structure` (H1 presence, single-H1, hierarchy), `content/image-alt-text` (skips `role="presentation"` / `aria-hidden="true"` / explicit `alt=""`), `tech/og-completeness` (the README-promised rule that finally ships).
+- **`AuditOptions.authorityScore`** (0-100) — bring-your-own-DA. ≥80 shifts the verdict ladder one tier lenient (established brand can absorb shapes a newer site can't). ≤30 shifts one tier stricter (newer/lower-authority operator). Raw `risk` number unchanged so CI gates stay stable. The engine itself remains authority-blind by design — no Moz/Ahrefs/Semrush dependency.
+- **`AuditOptions.sampleSeed`** — deterministic `mulberry32` PRNG plumbed through the stratified sampler. Repeated audits with the same seed pick the same pages and produce reproducible verdicts.
+- **`spam/doorway-pattern` cluster collapse** — emits in the same `pageUrl` + `relatedUrls[0]` shape as `spam/near-duplicate` and is registered in `CLUSTERABLE_RULES`. C(N,2) per-pair findings on entity-swap-heavy catalogs collapse into one cluster finding per template-tied group.
+- **Per-bucket info-severity cap** — a flood of info findings can't fill a category bucket on its own (capped at 50 separately from the 100 cap on warning+ findings).
+- **`summary.appliedSeverityDemotions: string[]`** — engine emits the list of rule IDs whose severity was overridden by the active scoring profile so consumers (formatters, CI) can show *which* rules got demoted and *why*. Pass `--strict` to disable demotions entirely.
+- **Sample-aware rules** — `links/unreachable-from-root` skips on partial-sample audits (it can't distinguish real graph isolation from sample-shape).
+- **Markdown formatter** collapses informational findings under `<details>` so PR comments don't drown actionable items in 100+ info bullets.
+
+The full per-round iteration story (9 calibration rounds against a curated reputable-pSEO corpus) and the trade-offs we accepted are at [`docs/superpowers/specs/2026-05-03-calibration-against-reputable-pseo.md`](../../docs/superpowers/specs/2026-05-03-calibration-against-reputable-pseo.md). The honest blind-spot audit (what we still don't detect, including the domain-authority gap that motivated `--authority-score`) is at [`docs/superpowers/specs/2026-05-03-pseolint-blind-spots.md`](../../docs/superpowers/specs/2026-05-03-pseolint-blind-spots.md). The dated user-facing methodology summary is at [pseolint.dev/methodology](https://pseolint.dev/methodology).
+
+## API
+
+### `auditSource(source, options?)`
+
+Returns an `AuditSummary` with composite score, category scores, enriched findings, and optional cache / state / AI-triage metadata.
+
+Selected options (see `AuditOptions` in `types.ts` for the full surface):
+
+```ts
+await auditSource("https://example.com/sitemap.xml", {
+  concurrency: 5,
+  timeout: 30_000,
+  sampleSize: 200,
+  samplingStrategy: "stratified",        // or "random"
+  ignore: ["**/api/**"],
+  maxFetchBytes: 52_428_800,             // 50 MB hard cap per run
+  cache: { dir: ".pseolint/cache", ttlMs: 7 * 24 * 60 * 60 * 1000 },
+  state: {
+    path: ".pseolint/state.json",
+    mode: "monitoring",       // v0.5+: pre-fetch decision matrix; "fresh" forces full re-audit.
+                              // Omit to auto-monitor when prior state exists.
+    ageFloorDays: 7,          // v0.5+: forces refetch on URLs older than N days
+    exitOnRegression: true,
+    since: true,              // v0.5+ alias for mode: "monitoring" (back-compat)
+  },
+  pageGroups: {
+    blog:     { match: "**/blog/**", rules: ["content/*", "spam/*"] },
+    products: { match: "**/p/**",    overrides: { "spam/thin-content": { thinContentMinWords: 200 } } },
+  },
+  dataSource: { records: [{ url: "/p/*", data: { price: "$19", stock: 12 } }] },
+  entityPatterns: [{ placeholder: "[CITY]", pattern: "\\b(NYC|LA|SF)\\b", flags: "gi" }],
+  ai: { enabled: true, provider: "anthropic", model: "claude-haiku-4-5-20251001", maxCostUsd: 0.1 },
+  telemetry: { enabled: true, path: ".pseolint/telemetry.jsonl" },
+  // Safety (v0.3.2–v0.3.3)
+  safeMode: "saas",                       // "saas" | "cli" — flips guardSsrf + caps
+  guardSsrf: true,                        // DNS-validated SSRF check on every URL
+  respectRobotsTxt: true,                 // skip sitemap URLs Disallow'd by target robots.txt
+  followRedirects: true,
+  maxCrawlDiscovered: 2000,               // hard ceiling on link-discovery fan-out
+  signal: controller.signal,              // AbortSignal — ctrl-C / quota-exhausted cancels cleanly
+  rules: {
+    nearDuplicateThreshold: 0.85,
+    thinContentMinWords: 300,
+    titleOverlapThreshold: 0.8,
+    // ...
+  },
+});
+```
+
+### Safety primitives (SSRF, abort, crawl-ceiling)
+
+`@pseolint/core` ships a few primitives for hosts that run audits against
+user-submitted URLs. All are opt-in; local CLI use doesn't change.
+
+```ts
+import {
+  safeFetch,             // SSRF-safe fetch for non-audit use cases
+  validateTargetHost,    // throws SSRFError on private-range / DNS-rebinding targets
+  isPrivateOrReservedHost,
+  SSRFError,
+  DnsResolutionError,
+} from "@pseolint/core";
+
+// Validate a user-submitted URL before enqueuing:
+await validateTargetHost(new URL(userUrl).hostname);
+
+// Fetch with SSRF guard baked in:
+const res = await safeFetch(userUrl, { timeoutMs: 10_000, followRedirects: false });
+```
+
+The full audit picks up the same guard via `auditSource(url, { safeMode: "saas" })`
+or via the individual `guardSsrf` / `respectRobotsTxt` / `followRedirects` flags.
+
+### Render-mode analytics blocking
+
+Rendered audits (`options.render = {...}`) block known analytics endpoints
+by default so the audit doesn't inject fake sessions into the site owner's
+GA / Plausible / PostHog / Mixpanel / Hotjar / Sentry dashboards.
+
+```ts
+await auditSource(url, {
+  render: {
+    analyticsMode: "block",               // default — blocks ~40 analytics hosts
+    // "allow-first-party" — block third-party only
+    // "allow" — don't intercept anything
+    extraBlockedHosts: ["my-internal-metrics.corp"],
+  },
+});
+```
+
+### Formatters
+
+```ts
+import { formatConsole, formatJson, formatMarkdown, formatHtml } from "@pseolint/core";
+
+const out = formatConsole(summary);
+const json = formatJson(summary);
+const md   = formatMarkdown(summary);
+const html = formatHtml(summary);
+```
+
+### AI triage
+
+When `ai.enabled` is set, findings are clustered into root-causes by an LLM. Providers are loaded lazily from optional peer deps — install only the one you need:
+
+```bash
+npm install @ai-sdk/anthropic   # or @ai-sdk/openai, @ai-sdk/google, @ai-sdk/mistral,
+                                #    @ai-sdk/groq, @ai-sdk/xai, @ai-sdk/cohere,
+                                #    ollama-ai-provider-v2
+```
+
+```ts
+import { triageFindings, createLanguageModel, estimateCostUsd } from "@pseolint/core";
+```
+
+Cost and daily-budget caps are enforced pre-flight; results are cached on disk by default.
+
+### AI orchestrator (v0.5)
+
+Net-new in v0.5. `orchestrate()` drives an LLM through 25 deterministic tools (sitemap fetch, template clustering, per-page rule checks, AEO probes against live answer engines, SerpAPI) and produces a **fix manifest** of concrete patches — not just a list of findings.
+
+```ts
+import { orchestrate } from "@pseolint/core";
+
+const { session, manifest, validation, diff } = await orchestrate({
+  domain: "https://example.com",
+  userId: "demo",
+  budget: { maxSessionUsd: 3 },         // optional; default $5
+  onEvent: (e) => console.log(e),       // optional; SSE-friendly callback
+});
+
+if (session.reason === "completed") {
+  console.log(`Verdict: ${manifest!.verdict}`);
+  console.log(`${validation!.validPatches}/${validation!.totalPatches} patches valid`);
+}
+```
+
+**What you get:**
+- `manifest` — `FixManifest` with verdict, category grades, page/template/domain patches (replace_h1, rewrite_meta, add_jsonld, add_faq_block, rewrite_intro, add_internal_link, remove_thin_block, robots_txt, sitemap_xml, canonical_strategy)
+- `validation` — patch-by-patch `ManifestValidationReport`. Failed patches are dropped from the manifest before it returns; `failures` carries the location + reason.
+- `diff` — `ManifestDiff` of structured `PatchDiff` objects (5 kinds — text_replace, html_insert, html_remove, file_replace, guidance) suitable for direct UI rendering.
+
+**Architecture**: rules become tools the LLM calls. The LLM picks order. Budget caps (LLM tokens + external probe USD, pre-flight + reactive) bound spend. Watchdog injects a convergence reminder every N tool calls. AsyncLocalStorage-backed page cache means HTML never travels in conversation history — token cost stays bounded as audits scale.
+
+**Lower-level exports** for callers who want individual pieces:
+
+```ts
+import {
+  runOrchestrator,           // direct runner — bring your own LanguageModel
+  orchestratorTools,         // the 25-tool registry
+  defineTool,                // helper to add custom tools
+  validateManifest,          // walk a manifest, return per-failure report
+  diffManifest,              // produce a structured-diff projection
+  manifestSchema,            // Zod schema for FixManifest
+  buildSystemPrompt,         // canonical orchestrator system prompt
+  DEFAULT_BUDGET,            // BudgetCaps defaults
+} from "@pseolint/core";
+```
+
+External probes (`query_serp`, `ask_ai_engine`) read API keys from the call's `apiKey` arg or `SERPAPI_API_KEY` / `ANTHROPIC_API_KEY` / `PERPLEXITY_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY` env vars.
+
+### Change-driven monitoring (v0.5)
+
+When prior state exists, `auditSource` defaults to **monitoring mode**: the decision matrix decides which URLs to fetch BEFORE the network round-trip. URLs without change signals are skipped entirely; their findings are carried forward from prior state with `carriedForward: true` and `lastVerifiedAt` markers.
+
+```ts
+import { planScrapeStrategy, CORE_RULESET_VERSION, DEFAULT_AGE_FLOOR_DAYS } from "@pseolint/core";
+
+// The decision matrix is also exposed as a pure function for callers that
+// want to plan their own fetches:
+const plan = planScrapeStrategy({
+  candidateUrls,
+  priorState,
+  sitemapLastmodByUrl,        // Map<url, ISO-string>
+  currentRulesetVersion: CORE_RULESET_VERSION,
+  ageFloorDays: DEFAULT_AGE_FLOOR_DAYS,
+  now: new Date(),
+  // Optional Pro-only inputs:
+  // gscDeltasByUrl, gscThresholds
+});
+// plan.refetch: Map<url, RefetchReason>
+// plan.skip:    Map<url, "unchanged">
+```
+
+**Reasons** (first match wins): `new` → `age` → `ruleset` → `recheck` (warning/error/critical only — info findings carry forward) → `lastmod` → `gsc` → `no-signal` → else `unchanged`.
+
+`AuditSummary.scrapePlan` reports `{ fetched, intended, carriedForward, reasonCounts, rulesetVersion, lastFullAuditAt }` — populated only on monitoring runs.
+
+**Bump `CORE_RULESET_VERSION`** when shipping a new rule or materially changing rule logic so monitoring runs re-evaluate previously-skipped URLs against the new ruleset.
+
+**Regression gating.** `state.exitOnRegression: true` flags a run where a new rule ID fires on any previously clean URL (`summary.hasRegression`). Carried-forward findings are excluded from the regression baseline so a regression on a skipped URL isn't masked by stale findings.
+
+### State schema v2
+
+`UrlStateEntry` v2 stores full finding records (not just IDs) so future runs can carry them forward. Persists `lastModified`, `etag`, `sitemapLastmodAtAudit`, `rulesetVersion` per URL. `RunState` adds `lastFullAuditAt` and `rulesetVersion`. Existing v1 state files (v0.4) are discarded on read with a warning, triggering one baseline re-audit.
+
+### Caching
+
+Setting `cache` enables an ETag/Last-Modified-aware disk cache for HTTP fetches. `summary.cacheStats` reports `{ hits, total, bytesSavedEstimate }`.
+
+### Page groups
+
+Classify pages by glob and apply different rule subsets or threshold overrides per group. Results are surfaced in `summary.groupScores` / `summary.groupPageCounts`.
+
+### Rendering
+
+For client-rendered pages, install `playwright-core` and pass `render: { browserWsEndpoint }` to connect to an existing browser endpoint.
+
+## Peer dependencies
+
+All AI providers and `playwright-core` are optional peers — you only install the ones you actually use.
+
+## License
+
 MIT

package/dist/ai/manifest/diff.d.ts

@@ -0,0 +1,78 @@
+import type { FixManifest } from "../orchestrator/finish-tool.js";
+type PageChange = FixManifest["pages"][number]["changes"][number];
+type DomainPatch = FixManifest["domainLevel"][number];
+/**
+ * Structured patch diff. Each manifest change maps to one of these,
+ * which downstream consumers (web UI, CLI, GitHub-PR generator) render
+ * differently:
+ *   - text_replace → before/after blocks side-by-side, copy-paste UI
+ *   - html_insert  → HTML snippet to paste into the named region
+ *   - html_remove  → CSS selector to delete
+ *   - file_replace → full-file diff (robots.txt / sitemap.xml)
+ *   - guidance     → freeform prose (canonical_strategy)
+ *
+ * Kept deliberately narrow — not a unified-diff library. The manifest
+ * patches are paste-into-CMS-friendly outputs, not source-level diffs.
+ */
+export type PatchDiff = {
+    kind: "text_replace";
+    field: "h1" | "title" | "meta_description" | "intro";
+    before: string;
+    after: string;
+    reason: string;
+} | {
+    kind: "html_insert";
+    target: "head" | "body" | "after_h1";
+    description: string;
+    html: string;
+    reason: string;
+} | {
+    kind: "html_remove";
+    selector: string;
+    reason: string;
+} | {
+    kind: "file_replace";
+    path: string;
+    before: string | null;
+    after: string;
+    reason: string;
+} | {
+    kind: "guidance";
+    topic: "canonical_strategy";
+    text: string;
+    reason: string;
+};
+/**
+ * Convert a single page-change into a `PatchDiff`. Pure transformation —
+ * does not validate (use `validatePageChange` for that). The two should
+ * be called in sequence at manifest finalization: validate first, drop
+ * failures, then diff the survivors.
+ */
+export declare function diffPageChange(c: PageChange): PatchDiff;
+/** Convert a single domain patch into a `PatchDiff`. */
+export declare function diffDomainPatch(p: DomainPatch): PatchDiff;
+export interface ManifestDiff {
+    pages: Array<{
+        url: string;
+        diffs: PatchDiff[];
+    }>;
+    templates: Array<{
+        templateId: string;
+        affectedUrlCount: number;
+        recommendation: string;
+        examples: Array<{
+            url: string;
+            diffs: PatchDiff[];
+        }>;
+    }>;
+    domainLevel: PatchDiff[];
+}
+/**
+ * Walk every patch in a manifest and produce a structured-diff projection.
+ * Mirrors the manifest's tree structure so the UI can render side-by-side
+ * (page list / template clusters / domain-level), each populated with
+ * already-typed patch diffs.
+ */
+export declare function diffManifest(manifest: FixManifest): ManifestDiff;
+export {};
+//# sourceMappingURL=diff.d.ts.map

package/dist/ai/manifest/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/ai/manifest/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE,KAAK,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,KAAK,WAAW,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GACjB;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,IAAI,GAAG,OAAO,GAAG,kBAAkB,GAAG,OAAO,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAgBN;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,CAmEvD;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,CA0BzD;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,EAAE,CAAA;KAAE,CAAC,CAAC;IAClD,SAAS,EAAE,KAAK,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,SAAS,EAAE,CAAA;SAAE,CAAC,CAAC;KACtD,CAAC,CAAC;IACH,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,YAAY,CAiBhE"}