@pseolint/core 0.1.0 → 0.2.1

package/dist/auditor.js

@@ -26,6 +26,7 @@ import { hreflangConsistencyRule } from "./rules/tech/hreflang-consistency.js";
 import { ogCompletenessRule } from "./rules/tech/og-completeness.js";
 import { robotsNoindexConflictRule } from "./rules/tech/robots-noindex-conflict.js";
 import { sitemapCompletenessRule } from "./rules/tech/sitemap-completeness.js";
+import { robotsComplianceRule } from "./rules/tech/robots-sitemap-presence.js";
 import { redirectChainRule } from "./rules/tech/redirect-chain.js";
 import { soft404Rule } from "./rules/tech/soft-404.js";
 import { jsonLdValidRule } from "./rules/schema/json-ld-valid.js";
@@ -35,9 +36,17 @@ import { titleOverlapRule } from "./rules/cannibal/title-overlap.js";
 import { keywordCollisionRule } from "./rules/cannibal/keyword-collision.js";
 import { urlPatternRule } from "./rules/cannibal/url-pattern.js";
 import { templateCoverageRule } from "./rules/spam/template-coverage.js";
+import { dataBindingRule, dataIdenticalRule } from "./rules/data/data-binding.js";
 import { classifyPages, isRuleEnabled } from "./page-classifier.js";
 import { RULE_REFERENCES } from "./rule-references.js";
 import { enrichFindings } from "./enrich-findings.js";
+import { triageFindings } from "./ai/triage.js";
+import { createLanguageModel } from "./ai/adapters/index.js";
+import { promptTriageFeedback } from "./ai/feedback-prompt.js";
+import { generateRunId, appendTelemetryRecord, todayTriageSpendUsd, } from "./telemetry/index.js";
+import { cachedFetch } from "./cache.js";
+import { stratifiedSample } from "./stratified-sample.js";
+import { readState, writeState, computeContentHash, STATE_SCHEMA_VERSION, } from "./state.js";
 const DEFAULTS = {
     nearDuplicateThreshold: 0.85,
     entitySwapThreshold: 0.95,
@@ -84,13 +93,17 @@ function resolveGroupRules(baseRules, overrides) {
     }
     return result;
 }
-function runRulesOnPages(pages, resolvedRules, isEnabled, groupName, knownUrls, adjacency, inbound, rootUrl, normalizeUrlOptions, source, entityPatterns) {
+function runRulesOnPages(pages, resolvedRules, isEnabled, groupName, knownUrls, adjacency, inbound, rootUrl, normalizeUrlOptions, source, entityPatterns, overrides) {
     const findings = [];
-    const tag = (results) => results.map((r) => ({
-        ...r,
-        group: groupName === "__default" ? undefined : groupName,
-        ref: r.ref ?? RULE_REFERENCES[r.ruleId],
-    }));
+    const tag = (results) => results.map((r) => {
+        const override = overrides?.[r.ruleId];
+        return {
+            ...r,
+            group: groupName === "__default" ? undefined : groupName,
+            ref: r.ref ?? RULE_REFERENCES[r.ruleId],
+            ...(override?.severity ? { severity: override.severity } : {}),
+        };
+    });
     // Spam rules — always compute cross-page data, only push findings if enabled
     const nearDuplicate = nearDuplicateRule(pages, resolvedRules.nearDuplicateThreshold);
     if (isEnabled("spam/near-duplicate")) {
@@ -257,79 +270,57 @@ async function collectHtmlFiles(directory) {
     }));
     return files.flat();
 }
-async function fetchWithRetry(url, timeoutMs) {
+async function fetchWithRetry(url, timeoutMs, cache, stats) {
     try {
-        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-        if (!response.ok) {
-            return null;
+        stats.total += 1;
+        const r = await cachedFetch(url, { timeoutMs, cache });
+        if (r.fromCache) {
+            stats.hits += 1;
+            stats.bytesSavedEstimate += r.body.length;
         }
-        return {
-            text: await response.text(),
-            contentType: response.headers.get("content-type")?.toLowerCase() ?? ""
-        };
+        if (r.status < 200 || r.status >= 300)
+            return null;
+        return { text: r.body, contentType: (r.headers["content-type"] ?? "").toLowerCase() };
     }
     catch {
         return null;
     }
 }
-async function fetchPageWithMeta(url, timeoutMs) {
-    const redirectChain = [];
-    let currentUrl = url;
-    for (let hop = 0; hop < 10; hop += 1) {
-        let response;
-        try {
-            response = await fetch(currentUrl, {
-                redirect: "manual",
-                signal: AbortSignal.timeout(timeoutMs),
-            });
-        }
-        catch {
-            return null;
-        }
-        const status = response.status;
-        if (status >= 300 && status < 400) {
-            const location = response.headers.get("location");
-            if (!location)
-                break;
-            redirectChain.push(currentUrl);
-            try {
-                currentUrl = new URL(location, currentUrl).href;
-            }
-            catch {
-                break;
-            }
-            continue;
-        }
-        let html;
-        try {
-            html = await response.text();
-        }
-        catch {
-            return null;
+async function fetchPageWithMeta(url, timeoutMs, cache, stats) {
+    try {
+        stats.total += 1;
+        const r = await cachedFetch(url, { timeoutMs, cache });
+        if (r.fromCache) {
+            stats.hits += 1;
+            stats.bytesSavedEstimate += r.body.length;
         }
         return {
             url,
-            html,
+            html: r.body,
             httpMeta: {
-                statusCode: status,
-                finalUrl: currentUrl,
-                redirectChain,
-                xRobotsTag: response.headers.get("x-robots-tag") ?? "",
-                linkHeader: response.headers.get("link") ?? "",
+                statusCode: r.status,
+                finalUrl: r.url,
+                redirectChain: r.redirectChain,
+                xRobotsTag: r.headers["x-robots-tag"] ?? "",
+                linkHeader: r.headers.link ?? "",
             },
         };
     }
-    return null;
+    catch {
+        return null;
+    }
 }
-async function fetchTextStrict(url, timeoutMs) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-    if (!response.ok) {
-        throw new Error(`Failed to fetch source: ${response.status} ${response.statusText}`);
+async function fetchTextStrict(url, timeoutMs, cache, stats) {
+    stats.total += 1;
+    const r = await cachedFetch(url, { timeoutMs, cache });
+    if (r.fromCache) {
+        stats.hits += 1;
+        stats.bytesSavedEstimate += r.body.length;
     }
-    return {
-        text: await response.text(),
-        contentType: response.headers.get("content-type")?.toLowerCase() ?? ""
-    };
+    if (r.status < 200 || r.status >= 300) {
+        throw new Error(`Failed to fetch source: ${r.status}`);
+    }
+    return { text: r.body, contentType: (r.headers["content-type"] ?? "").toLowerCase() };
 }
 async function runWithConcurrency(items, limit, fn) {
     let index = 0;
@@ -418,7 +409,7 @@ function fisherYatesSample(items, n) {
     }
     return arr.slice(arr.length - n);
 }
-async function collectUrlsFromSitemap(sitemapText, sitemapUrl, visited, timeoutMs) {
+async function collectUrlsFromSitemap(sitemapText, sitemapUrl, visited, timeoutMs, cache, stats) {
     visited.add(sitemapUrl);
     const locs = parseSitemapUrls(sitemapText);
     if (!isSitemapIndex(sitemapText)) {
@@ -428,24 +419,24 @@ async function collectUrlsFromSitemap(sitemapText, sitemapUrl, visited, timeoutM
     for (const childUrl of locs) {
         if (visited.has(childUrl))
             continue;
-        const child = await fetchWithRetry(childUrl, timeoutMs);
+        const child = await fetchWithRetry(childUrl, timeoutMs, cache, stats);
         if (!child)
             continue;
         const childLike = child.contentType.includes("xml") || looksLikeSitemap(child.text);
         if (!childLike)
             continue;
-        const childUrls = await collectUrlsFromSitemap(child.text, childUrl, visited, timeoutMs);
+        const childUrls = await collectUrlsFromSitemap(child.text, childUrl, visited, timeoutMs, cache, stats);
         allUrls.push(...childUrls);
     }
     return allUrls;
 }
-async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscovery) {
+async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscovery, discoveryBudget, cache, stats) {
     if (/^https?:\/\//i.test(source)) {
         let text;
         let contentType;
         let sourceStatus = 200;
         try {
-            const fetched = await fetchTextStrict(source, timeoutMs);
+            const fetched = await fetchTextStrict(source, timeoutMs, cache, stats);
             text = fetched.text;
             contentType = fetched.contentType;
         }
@@ -454,7 +445,7 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
             if (source.includes("sitemap")) {
                 try {
                     const origin = new URL(source).origin;
-                    const fallback = await fetchTextStrict(origin, timeoutMs);
+                    const fallback = await fetchTextStrict(origin, timeoutMs, cache, stats);
                     text = fallback.text;
                     contentType = fallback.contentType;
                     sourceStatus = -1; // flag that we fell back
@@ -470,17 +461,21 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
         const isXml = (contentType.includes("xml") || looksLikeSitemap(text)) && sourceStatus !== -1;
         if (isXml) {
             const visited = new Set();
-            const urls = await collectUrlsFromSitemap(text, source, visited, timeoutMs);
+            const allSitemapUrls = await collectUrlsFromSitemap(text, source, visited, timeoutMs, cache, stats);
+            // If we have a budget, sample from sitemap URLs before fetching
+            const urlsToFetch = discoveryBudget > 0 && allSitemapUrls.length > discoveryBudget
+                ? fisherYatesSample(allSitemapUrls, discoveryBudget)
+                : allSitemapUrls;
             const pages = [];
-            await runWithConcurrency(urls, concurrency, async (url) => {
-                const result = await fetchPageWithMeta(url, timeoutMs);
+            await runWithConcurrency(urlsToFetch, concurrency, async (url) => {
+                const result = await fetchPageWithMeta(url, timeoutMs, cache, stats);
                 if (result) {
                     pages.push(result);
                 }
             });
-            // Crawl discovery: follow internal links to find pages not in sitemap
-            if (crawlDiscovery) {
-                const sitemapUrlSet = new Set(urls);
+            // Skip additional crawl discovery when budget is active — sitemap is authoritative
+            if (crawlDiscovery && discoveryBudget === 0) {
+                const sitemapUrlSet = new Set(allSitemapUrls);
                 const discoveredUrls = new Set();
                 let sourceOrigin;
                 try {
@@ -516,14 +511,14 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
                 }
                 if (discoveredUrls.size > 0) {
                     await runWithConcurrency(Array.from(discoveredUrls), concurrency, async (url) => {
-                        const result = await fetchPageWithMeta(url, timeoutMs);
+                        const result = await fetchPageWithMeta(url, timeoutMs, cache, stats);
                         if (result && result.httpMeta && result.httpMeta.statusCode >= 200 && result.httpMeta.statusCode < 300) {
                             pages.push(result);
                         }
                     });
                 }
             }
-            return { pages, sitemapUrls: new Set(urls) };
+            return { pages, sitemapUrls: new Set(allSitemapUrls), discoveredUrlCount: allSitemapUrls.length };
         }
         if (contentType.includes("html") || looksLikeHtml(text)) {
             const initialPage = { url: source, html: text };
@@ -537,8 +532,12 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
                     sourceOrigin = "";
                 }
                 const knownCrawled = new Set([source]);
+                const allDiscoveredUrls = new Set([source]);
                 const maxDepth = 3;
                 for (let depth = 0; depth < maxDepth; depth += 1) {
+                    // Stop if we've hit the discovery budget
+                    if (discoveryBudget > 0 && pages.length >= discoveryBudget)
+                        break;
                     const frontier = new Set();
                     for (const page of pages) {
                         if (depth > 0 && !knownCrawled.has("__depth_" + depth + "_" + page.url))
@@ -568,11 +567,25 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
                             }
                         }
                     }
+                    // Track all discovered URLs even if we don't fetch them
+                    for (const url of frontier) {
+                        allDiscoveredUrls.add(url);
+                    }
                     if (frontier.size === 0)
                         break;
+                    // If budget active, only fetch up to budget
+                    let urlsToFetch = Array.from(frontier);
+                    if (discoveryBudget > 0) {
+                        const remaining = discoveryBudget - pages.length;
+                        if (remaining <= 0)
+                            break;
+                        if (urlsToFetch.length > remaining) {
+                            urlsToFetch = urlsToFetch.slice(0, remaining);
+                        }
+                    }
                     const newPages = [];
-                    await runWithConcurrency(Array.from(frontier), concurrency, async (url) => {
-                        const result = await fetchPageWithMeta(url, timeoutMs);
+                    await runWithConcurrency(urlsToFetch, concurrency, async (url) => {
+                        const result = await fetchPageWithMeta(url, timeoutMs, cache, stats);
                         if (result && result.httpMeta && result.httpMeta.statusCode >= 200 && result.httpMeta.statusCode < 300) {
                             newPages.push(result);
                             knownCrawled.add(url);
@@ -586,6 +599,7 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
                     if (newPages.length === 0)
                         break;
                 }
+                return { pages, discoveredUrlCount: allDiscoveredUrls.size };
             }
             return { pages };
         }
@@ -613,6 +627,8 @@ async function loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscover
     return { pages: [] };
 }
 export async function auditSource(source, options) {
+    const runId = generateRunId();
+    const runStartedAt = Date.now();
     const concurrency = options?.concurrency ?? 5;
     const timeoutMs = options?.timeout ?? 30000;
     const ignorePatterns = options?.ignore ?? [];
@@ -638,7 +654,63 @@ export async function auditSource(source, options) {
         stripWwwHost: options?.rules?.stripWwwHost ?? false
     });
     const crawlDiscovery = /^https?:\/\//i.test(source) && (options?.crawlDiscovery ?? true);
-    const { pages: loadedPages, sitemapUrls: sitemapUrlSet } = await loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscovery);
+    // Discovery budget: when sampleSize is set, cap discovery at 2x (min 50) to avoid
+    // fetching far more pages than we'll sample. First-run egress is bounded by sampleSize;
+    // re-runs hit the cache. Remove adaptive 200-cap: users get full crawl by default,
+    // repeated audits stay cheap via --cache.
+    const discoveryBudget = options?.sampleSize && options.sampleSize > 0
+        ? Math.max(50, options.sampleSize * 2)
+        : 0;
+    const cacheStats = { hits: 0, total: 0, bytesSavedEstimate: 0 };
+    const cacheConfig = options?.cache
+        ? {
+            dir: options.cache.dir ?? ".pseolint/cache",
+            ttlMs: options.cache.ttlMs ?? 7 * 24 * 60 * 60 * 1000,
+        }
+        : null;
+    const { pages: loadedPagesRaw, sitemapUrls: sitemapUrlSet, discoveredUrlCount } = await loadPagesFromSource(source, concurrency, timeoutMs, crawlDiscovery, discoveryBudget, cacheConfig, cacheStats);
+    const loadedPages = [...loadedPagesRaw];
+    if (discoveredUrlCount && discoveredUrlCount > loadedPages.length) {
+        console.error(`Discovered ${discoveredUrlCount} pages, fetched ${loadedPages.length} for audit. Use --sample-size 0 for full crawl.`);
+    }
+    // State read + delta filtering
+    let priorState = null;
+    const skippedUrls = [];
+    if (options?.state?.since || options?.state?.exitOnRegression) {
+        const statePath = options.state.path ?? ".pseolint/state.json";
+        priorState = await readState(statePath);
+        const currentRenderMode = options.render ? "rendered" : "static";
+        if (priorState && priorState.renderMode !== currentRenderMode) {
+            console.error(`warning: prior state renderMode=${priorState.renderMode} differs from current ${currentRenderMode}. Performing full re-audit.`);
+            priorState = null;
+        }
+        if (priorState && options.state.since) {
+            const kept = [];
+            for (const p of loadedPages) {
+                const prior = priorState.urls[p.url];
+                if (prior && prior.contentHash === computeContentHash(p.html)) {
+                    skippedUrls.push(p.url);
+                }
+                else {
+                    kept.push(p);
+                }
+            }
+            loadedPages.splice(0, loadedPages.length, ...kept);
+        }
+        else if (!priorState && options.state.since) {
+            console.error("no prior state found — performing full baseline audit");
+        }
+    }
+    let robotsTxtContent = "";
+    if (/^https?:\/\//i.test(source)) {
+        try {
+            const origin = new URL(source).origin;
+            const result = await fetchWithRetry(`${origin}/robots.txt`, timeoutMs, cacheConfig, cacheStats);
+            if (result)
+                robotsTxtContent = result.text;
+        }
+        catch { /* ignore */ }
+    }
     const deduped = [];
     const urlHashes = new Map();
     const duplicateUrlFindings = [];
@@ -665,8 +737,15 @@ export async function auditSource(source, options) {
     const filtered = ignorePatterns.length > 0
         ? deduped.filter((page) => !shouldIgnore(page.url, ignorePatterns))
         : deduped;
+    const strategy = options?.samplingStrategy ?? "stratified";
     const sampled = sampleSize > 0 && sampleSize < filtered.length
-        ? fisherYatesSample(filtered, sampleSize)
+        ? (strategy === "stratified"
+            ? (() => {
+                const urlsMap = new Map(filtered.map(p => [p.url, p]));
+                const sampledUrls = stratifiedSample(filtered.map(p => p.url), sampleSize);
+                return sampledUrls.map(u => urlsMap.get(u));
+            })()
+            : fisherYatesSample(filtered, sampleSize))
         : filtered;
     const parsedPages = sampled.map((page) => {
         const parsed = parseHtmlPage(page.html, page.url, { normalizeUrl: normalizeUrlOptions });
@@ -686,6 +765,29 @@ export async function auditSource(source, options) {
             inbound.set(link, (inbound.get(link) ?? 0) + 1);
         }
     }
+    // Build entity patterns, merging user-supplied config patterns with defaults.
+    // Flags are restricted to known-safe characters to prevent ReDoS via crafted flags;
+    // each pattern is compiled eagerly so bad regexes fail at config time, not mid-audit.
+    const SAFE_FLAGS_RE = /^[gimsuy]*$/;
+    const entityPatterns = options?.entityPatterns
+        ? [
+            ...DEFAULT_ENTITY_PATTERNS,
+            ...options.entityPatterns.map((p) => {
+                const rawFlags = p.flags ?? "gi";
+                if (!SAFE_FLAGS_RE.test(rawFlags)) {
+                    throw new Error(`Invalid regex flags "${rawFlags}" in entityPatterns for placeholder "${p.placeholder}". ` +
+                        `Only the flags g, i, m, s, u, y are permitted.`);
+                }
+                try {
+                    // Flags validated against SAFE_FLAGS_RE above; pattern is from trusted local config, not HTTP input.
+                    return { placeholder: p.placeholder, pattern: new RegExp(p.pattern, rawFlags) }; // nosemgrep
+                }
+                catch (err) {
+                    throw new Error(`Invalid regex pattern for placeholder "${p.placeholder}": ${err.message}`);
+                }
+            }),
+        ]
+        : DEFAULT_ENTITY_PATTERNS;
     // Classify pages into groups and run only enabled rules per group
     const classified = classifyPages(parsedPages, options?.pageGroups);
     const allFindings = [...duplicateUrlFindings];
@@ -695,6 +797,18 @@ export async function auditSource(source, options) {
     if (sitemapUrlSet && sitemapUrlSet.size > 0) {
         const sitemapFindings = sitemapCompletenessRule(parsedPages, sitemapUrlSet);
         allFindings.push(...sitemapFindings.map((f) => ({ ...f, ref: f.ref ?? RULE_REFERENCES[f.ruleId] })));
+        if (robotsTxtContent) {
+            const robotsFindings = robotsComplianceRule(parsedPages, sitemapUrlSet, robotsTxtContent);
+            allFindings.push(...robotsFindings.map((f) => ({ ...f, ref: f.ref ?? RULE_REFERENCES[f.ruleId] })));
+        }
+    }
+    // Data source comparison rules
+    if (options?.dataSource?.records && options.dataSource.records.length > 0) {
+        const dataFindings = [
+            ...dataBindingRule(parsedPages, options.dataSource.records),
+            ...dataIdenticalRule(parsedPages, options.dataSource.records),
+        ];
+        allFindings.push(...dataFindings.map((f) => ({ ...f, ref: f.ref ?? RULE_REFERENCES[f.ruleId] })));
     }
     for (const [groupName, groupPages] of classified) {
         if (groupPages.length === 0)
@@ -704,7 +818,7 @@ export async function auditSource(source, options) {
             continue;
         const groupRules = resolveGroupRules(resolvedRules, groupConfig?.overrides);
         const enabledCheck = (ruleId) => isRuleEnabled(ruleId, groupConfig?.rules);
-        const findings = runRulesOnPages(groupPages, groupRules, enabledCheck, groupName, knownUrls, adjacency, inbound, rootUrl, normalizeUrlOptions, source, DEFAULT_ENTITY_PATTERNS);
+        const findings = runRulesOnPages(groupPages, groupRules, enabledCheck, groupName, knownUrls, adjacency, inbound, rootUrl, normalizeUrlOptions, source, DEFAULT_ENTITY_PATTERNS, groupConfig?.overrides);
         allFindings.push(...findings);
         groupPageCounts[groupName] = groupPages.length;
         const { score } = scoreFromFindings(findings);
@@ -716,7 +830,7 @@ export async function auditSource(source, options) {
     });
     const { score, categoryScores } = scoreFromFindings(enriched.findings);
     const auditedPageCount = Object.values(groupPageCounts).reduce((a, b) => a + b, 0);
-    return {
+    const summary = {
         score,
         categoryScores,
         groupScores: options?.pageGroups ? groupScores : undefined,
@@ -726,5 +840,207 @@ export async function auditSource(source, options) {
         templateDetected: enriched.templateDetected,
         rawFindingCount: enriched.rawFindingCount,
     };
+    if (cacheConfig) {
+        summary.cacheStats = cacheStats;
+    }
+    if (skippedUrls.length > 0) {
+        summary.skippedUrls = skippedUrls;
+    }
+    if (priorState && options?.state?.exitOnRegression) {
+        let hasRegression = false;
+        const currentFindings = new Map();
+        for (const f of summary.findings) {
+            if (!f.pageUrl)
+                continue;
+            const set = currentFindings.get(f.pageUrl) ?? new Set();
+            set.add(f.ruleId);
+            currentFindings.set(f.pageUrl, set);
+        }
+        for (const [url, entry] of Object.entries(priorState.urls)) {
+            const cur = currentFindings.get(url);
+            if (!cur)
+                continue;
+            const priorIds = new Set(entry.findingIds);
+            for (const ruleId of cur) {
+                if (!priorIds.has(ruleId)) {
+                    hasRegression = true;
+                    break;
+                }
+            }
+            if (hasRegression)
+                break;
+        }
+        summary.hasRegression = hasRegression;
+    }
+    if (options?.state) {
+        const statePath = options.state.path ?? ".pseolint/state.json";
+        const renderMode = options.render ? "rendered" : "static";
+        const urls = {};
+        const findingsByUrl = new Map();
+        for (const f of summary.findings) {
+            if (!f.pageUrl)
+                continue;
+            const list = findingsByUrl.get(f.pageUrl) ?? [];
+            if (!list.includes(f.ruleId))
+                list.push(f.ruleId);
+            findingsByUrl.set(f.pageUrl, list);
+        }
+        // Preserve prior entries for URLs skipped by --since (they didn't change).
+        // Without this, delta runs would lose state for unchanged URLs.
+        if (priorState && skippedUrls.length > 0) {
+            for (const url of skippedUrls) {
+                const prior = priorState.urls[url];
+                if (prior)
+                    urls[url] = prior;
+            }
+        }
+        for (const p of loadedPages) {
+            urls[p.url] = {
+                contentHash: computeContentHash(p.html),
+                fetchedAt: new Date().toISOString(),
+                status: p.httpMeta?.statusCode ?? 200,
+                findingIds: findingsByUrl.get(p.url) ?? [],
+            };
+        }
+        const newState = {
+            version: STATE_SCHEMA_VERSION,
+            lastRun: new Date().toISOString(),
+            source,
+            renderMode,
+            urls,
+            summary: {
+                score: summary.score,
+                totalFindings: summary.findings.length,
+                byCategory: Object.fromEntries(Object.entries(summary.categoryScores).map(([k, v]) => [k, v])),
+            },
+        };
+        await writeState(statePath, newState);
+    }
+    // Captured for telemetry even when triage is skipped, so users can diagnose
+    // model/provider reliability from their local stats.jsonl.
+    let triageAttempt;
+    if (options?.ai?.enabled) {
+        if (options.ai.apiKey) {
+            console.error("[ai-triage] warning: ai.apiKey is set in options. Prefer env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) — never commit an apiKey to a config file.");
+        }
+        try {
+            const resolved = await createLanguageModel({
+                provider: options.ai.provider,
+                model: options.ai.model,
+                endpoint: options.ai.endpoint,
+                apiKey: options.ai.apiKey,
+            });
+            const cacheConfig = options.ai.cache === false
+                ? false
+                : {
+                    dir: options.ai.cache?.dir ?? ".pseolint/ai-cache",
+                    ttlMs: options.ai.cache?.ttlMs ?? 30 * 24 * 60 * 60 * 1000,
+                };
+            // Daily-budget pre-flight read (best-effort — missing file is fine).
+            let spentTodayUsd;
+            if (options.ai.dailyBudgetUsd !== undefined) {
+                const telemetryPath = options.telemetry?.path ?? ".pseolint/telemetry.jsonl";
+                try {
+                    spentTodayUsd = await todayTriageSpendUsd(telemetryPath);
+                }
+                catch {
+                    spentTodayUsd = 0;
+                }
+            }
+            const outcome = await triageFindings(summary.findings, summary.pageCount, {
+                enabled: true,
+                model: resolved.model,
+                providerId: resolved.providerId,
+                modelId: resolved.modelId,
+                maxInputTokens: options.ai.maxInputTokens,
+                maxOutputTokens: options.ai.maxOutputTokens,
+                maxCostUsd: options.ai.maxCostUsd,
+                dailyBudgetUsd: options.ai.dailyBudgetUsd,
+                spentTodayUsd,
+                cache: cacheConfig,
+            });
+            if (outcome.skipReason) {
+                console.error(`[ai-triage] skipped: ${outcome.skipReason}`);
+                triageAttempt = { providerId: resolved.providerId, modelId: resolved.modelId, skipReason: outcome.skipReason };
+            }
+            else {
+                summary.triage = outcome.result;
+            }
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : "unknown error";
+            console.error(`[ai-triage] skipped: ${reason}`);
+            // No resolved model — providerId/modelId blank.
+            triageAttempt = { providerId: options.ai.provider ?? "", modelId: options.ai.model ?? "", skipReason: reason };
+        }
+    }
+    if (options?.telemetry?.enabled) {
+        const telemetryPath = options.telemetry.path ?? ".pseolint/telemetry.jsonl";
+        const auditRecord = {
+            type: "audit",
+            schemaVersion: 1,
+            runId,
+            timestamp: new Date().toISOString(),
+            durationMs: Date.now() - runStartedAt,
+            score: summary.score,
+            pageCount: summary.pageCount,
+            findingCount: summary.findings.length,
+            ...(summary.rawFindingCount !== undefined && { rawFindingCount: summary.rawFindingCount }),
+            ...(summary.templateDetected !== undefined && { templateDetected: summary.templateDetected }),
+            ...(summary.cacheStats && { cacheStats: summary.cacheStats }),
+            ...(summary.triage && {
+                triage: {
+                    success: true,
+                    rootCauseCount: summary.triage.rootCauses.length,
+                    providerId: summary.triage.providerId,
+                    modelId: summary.triage.modelUsed,
+                    cacheHit: summary.triage.cacheHit,
+                    tokenUsage: summary.triage.tokenUsage,
+                    ...(summary.triage.estimatedCostUsd !== undefined && {
+                        estimatedCostUsd: summary.triage.estimatedCostUsd,
+                    }),
+                    truncatedInput: summary.triage.truncatedInput,
+                },
+            }),
+            ...(!summary.triage && triageAttempt && {
+                triage: {
+                    success: false,
+                    skipReason: triageAttempt.skipReason,
+                    rootCauseCount: 0,
+                    providerId: triageAttempt.providerId,
+                    modelId: triageAttempt.modelId,
+                    cacheHit: false,
+                    tokenUsage: { input: 0, output: 0 },
+                    truncatedInput: false,
+                },
+            }),
+        };
+        await appendTelemetryRecord(telemetryPath, auditRecord);
+        // Feedback: only if triage ran
+        if (summary.triage) {
+            let rating;
+            if (options.telemetry.feedback) {
+                rating = options.telemetry.feedback;
+            }
+            else if (options.telemetry.prompt !== false) {
+                rating = await promptTriageFeedback();
+            }
+            if (rating) {
+                const feedbackRecord = {
+                    type: "feedback",
+                    schemaVersion: 1,
+                    runId,
+                    timestamp: new Date().toISOString(),
+                    rating,
+                };
+                await appendTelemetryRecord(telemetryPath, feedbackRecord);
+            }
+        }
+    }
+    const aiHintEnabled = options?.ai?.suggest !== false;
+    if (aiHintEnabled && !options?.ai?.enabled && process.env.ANTHROPIC_API_KEY) {
+        console.error(`💡 AI triage available — re-run with --ai to prioritize ${summary.findings.length} findings into a fix list.`);
+    }
+    return summary;
 }
 //# sourceMappingURL=auditor.js.map