@fulldotdev/scan 0.1.0

package/dist/report/evidence.d.ts

@@ -0,0 +1,58 @@
+import type { Observation, UrlRow } from "../engine/types.js";
+import type { StoredFinding } from "./build.js";
+export interface PageRow {
+    url: string;
+    status: number | null;
+    outcome: string | null;
+    html: boolean;
+    title: string | null;
+    type: string | null;
+    language: string | null;
+    indexable: boolean | null;
+    canonical: string | null;
+    depth: number | null;
+    inSitemap: boolean;
+    wordCount: number | null;
+    template: string | null;
+    browser: string | null;
+    lighthouse: {
+        mobile: Record<string, number | null> | null;
+        desktop: Record<string, number | null> | null;
+    };
+    findings: {
+        critical: number;
+        warning: number;
+        hint: number;
+    };
+}
+export declare function pageRows(records: Observation[], urls: UrlRow[], findings: StoredFinding[], templateOf?: (page: Observation) => string): PageRow[];
+export type AssetType = "image" | "script" | "style" | "font" | "document" | "page" | "feed" | "other";
+export interface AssetRow {
+    url: string;
+    type: AssetType;
+    external: boolean;
+    status: number | null;
+    outcome: string | null;
+    contentType: string | null;
+    bytes: number | null;
+    sizeEvidence: "complete-response" | "response-prefix" | "content-length" | "unknown";
+    checked: boolean;
+    skipReason: string | null;
+    redirects: number;
+    usage: {
+        kind: string;
+        page: string;
+    }[];
+    pages: number;
+}
+export declare function assetType(url: string, contentType: string | null, sniffed: string | null): AssetType;
+export declare function assetInventory(records: Observation[], urls: UrlRow[], siteUrl: string): AssetRow[];
+export interface IncomingLink {
+    source: string;
+    target: string;
+    text: string | null;
+    location: string | null;
+    rel: string | null;
+    representation: "original" | "rendered";
+}
+export declare function incomingLinks(records: Observation[], target: string): IncomingLink[];

package/dist/report/evidence.js

@@ -0,0 +1,192 @@
+import { assetExtension } from "../engine/crawl-scope.js";
+import { sameSite } from "../engine/network.js";
+export function pageRows(records, urls, findings, templateOf) {
+    const graph = new Map((records.find((r) => r.kind === "link-graph")?.data?.pages ?? []).map((p) => [p.url, p]));
+    const browser = new Map(records.filter((r) => r.kind === "browser").map((r) => [r.key, r.data]));
+    const lighthouse = records.filter((r) => r.kind === "lighthouse");
+    const sitemapped = new Set(urls
+        .filter((u) => u.sources.some((s) => s.startsWith("sitemap:")))
+        .map((u) => u.url));
+    const counts = new Map();
+    for (const finding of findings)
+        for (const url of new Set(finding.items.map((i) => i.url).filter(Boolean)))
+            if (url) {
+                const row = counts.get(url) ?? { critical: 0, warning: 0, hint: 0 };
+                row[finding.severity]++;
+                counts.set(url, row);
+            }
+    const scores = (url, device) => {
+        const run = lighthouse.find((l) => l.data.url === url && l.data.device === device && l.data.scores);
+        if (!run)
+            return null;
+        const s = run.data.scores;
+        return {
+            performance: numberOrNull(s.performance),
+            accessibility: numberOrNull(s.accessibility),
+            bestPractices: numberOrNull(s["best-practices"]),
+            seo: numberOrNull(s.seo),
+        };
+    };
+    return records
+        .filter((r) => r.kind === "page")
+        .sort((a, b) => a.key.localeCompare(b.key))
+        .map((page) => {
+        const d = page.data ?? {};
+        const html = d.html !== false;
+        const directives = [
+            d.xRobotsTag,
+            ...(d.robots ?? [])
+                .filter((r) => /^(robots|googlebot)$/i.test(r.name ?? ""))
+                .map((r) => r.content),
+        ].join(",");
+        return {
+            url: page.key,
+            status: d.http?.status ?? null,
+            outcome: d.http?.outcome ?? null,
+            html,
+            title: html ? (d.title ?? null) : null,
+            type: graph.get(page.key)?.type ?? null,
+            language: html ? (d.language ?? null) : null,
+            indexable: html ? !/\b(noindex|none)\b/i.test(directives) : null,
+            canonical: d.canonicals?.[0]?.href ?? null,
+            depth: graph.get(page.key)?.clickDepth ?? null,
+            inSitemap: sitemapped.has(page.key),
+            wordCount: html ? (d.wordCount ?? null) : null,
+            template: html && templateOf ? templateOf(page) : null,
+            browser: browser.get(page.key)?.status ?? null,
+            lighthouse: {
+                mobile: scores(page.key, "mobile"),
+                desktop: scores(page.key, "desktop"),
+            },
+            findings: counts.get(page.key) ?? { critical: 0, warning: 0, hint: 0 },
+        };
+    });
+}
+const numberOrNull = (value) => typeof value === "number" ? Math.round(value * 100) : null;
+export function assetType(url, contentType, sniffed) {
+    const type = (contentType ?? "").toLowerCase();
+    if (/^image\//.test(type) ||
+        sniffed === "png" ||
+        sniffed === "jpeg" ||
+        sniffed === "webp" ||
+        sniffed === "gif")
+        return "image";
+    if (/javascript|ecmascript/.test(type))
+        return "script";
+    if (/text\/css/.test(type))
+        return "style";
+    if (/font\/|application\/font|application\/x-font/.test(type))
+        return "font";
+    if (/text\/html|xhtml/.test(type))
+        return "page";
+    if (/rss|atom/.test(type))
+        return "feed";
+    if (/pdf|msword|officedocument|zip|csv|text\/plain|markdown/.test(type) ||
+        sniffed === "pdf")
+        return "document";
+    const path = (() => {
+        try {
+            return new URL(url).pathname;
+        }
+        catch {
+            return "";
+        }
+    })();
+    const extension = assetExtension.exec(path)?.[1]?.toLowerCase();
+    if (!extension)
+        return contentType ? "other" : "page";
+    if (/^(jpe?g|png|gif|svg|webp|avif|ico)$/.test(extension))
+        return "image";
+    if (/^(js|mjs)$/.test(extension))
+        return "script";
+    if (extension === "css")
+        return "style";
+    if (/^(woff2?|ttf|otf)$/.test(extension))
+        return "font";
+    if (/^(rss|atom)$/.test(extension))
+        return "feed";
+    if (/^(pdf|zip|docx?|xlsx?|pptx?|csv|txt|md)$/.test(extension))
+        return "document";
+    return "other";
+}
+// Every discovered file, external destination and linked page with where
+// it is used, its HTTP answer and measured size.
+export function assetInventory(records, urls, siteUrl) {
+    const resources = new Map(records.filter((r) => r.kind === "resource").map((r) => [r.key, r.data]));
+    return urls
+        .filter((u) => u.kind === "resource")
+        .sort((a, b) => a.url.localeCompare(b.url))
+        .map((u) => {
+        const data = resources.get(u.url);
+        const http = data?.http;
+        const status = http?.status ?? null;
+        const usage = u.sources.map((s) => {
+            const index = s.indexOf(":");
+            return index > 0 && /^https?:/.test(s.slice(index + 1))
+                ? { kind: s.slice(0, index), page: s.slice(index + 1) }
+                : { kind: s, page: "" };
+        });
+        let bytes = http?.bytes ?? null;
+        let sizeEvidence = "unknown";
+        if (http?.outcome === "ok" && bytes !== null) {
+            sizeEvidence = http.truncated ? "response-prefix" : "complete-response";
+            const length = Number(http.headers?.["content-length"]);
+            if (http.truncated &&
+                Number.isSafeInteger(length) &&
+                length >= bytes &&
+                !http.headers?.["content-encoding"] &&
+                status === 200) {
+                bytes = length;
+                sizeEvidence = "content-length";
+            }
+        }
+        return {
+            url: u.url,
+            type: assetType(u.url, http?.headers?.["content-type"] ?? null, data?.sniffedType ?? null),
+            external: !sameSiteSafe(u.url, siteUrl),
+            status,
+            outcome: http?.outcome ?? null,
+            contentType: http?.headers?.["content-type"] ?? null,
+            bytes,
+            sizeEvidence,
+            checked: !!http,
+            skipReason: u.skipReason,
+            redirects: http?.redirects?.length ?? 0,
+            usage,
+            pages: new Set(usage.map((x) => x.page).filter(Boolean)).size,
+        };
+    });
+}
+// Links to one page from original HTML and, where the browser pass ran,
+// links that JavaScript added.
+export function incomingLinks(records, target) {
+    const rows = [];
+    const seen = new Set();
+    for (const kind of ["page", "rendered"])
+        for (const record of records)
+            if (record.kind === kind)
+                for (const link of record.data?.links ?? [])
+                    if (link.href === target) {
+                        const id = `${record.key}|${link.fragment ?? ""}`;
+                        if (kind === "rendered" && seen.has(id))
+                            continue;
+                        seen.add(id);
+                        rows.push({
+                            source: record.key,
+                            target,
+                            text: link.name ?? link.text ?? null,
+                            location: link.location ?? null,
+                            rel: link.rel ?? null,
+                            representation: kind === "page" ? "original" : "rendered",
+                        });
+                    }
+    return rows;
+}
+function sameSiteSafe(a, b) {
+    try {
+        return sameSite(a, b);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/report/rules.d.ts

@@ -0,0 +1,41 @@
+export type Topic = "availability-security" | "crawling-indexability" | "content-structure" | "links-navigation" | "structured-data" | "performance" | "accessibility-usability" | "business-profiles" | "ai-agent-access";
+export type Severity = "critical" | "warning" | "hint";
+export type Confidence = "confirmed" | "probable" | "review";
+export type Requirement = "pages" | "browser" | "lighthouse" | "rendered" | "dns" | "tls" | "domain" | "url-variant" | "robots" | "sitemap" | "analysis" | "structured-data" | "field-data" | "safe-browsing" | "ssl-labs" | "blocklists" | "certificates" | "ai-discovery" | "options";
+export declare const topicLabels: Record<Topic, string>;
+export declare const topicOrder: Topic[];
+export interface Rule {
+    topic: Topic;
+    title: string;
+    severity: Severity;
+    confidence: Confidence;
+    requires: Requirement;
+    problem: string;
+    impact: string;
+}
+export declare const rules: Record<string, Rule>;
+export declare const areaTopics: Record<string, Topic>;
+export declare function findingGuidance(code: string, area?: string): {
+    topic: Topic;
+    problem: string;
+    impact: string;
+    confidence: Confidence;
+};
+export declare const auditCondition: (id: string) => string;
+export declare const accessibilityCondition: (id: string, manual?: boolean) => string;
+export declare function diagnosticEvidence<T>(value: T): T;
+export declare function publicFinding<T extends {
+    code: string;
+    title: string;
+    group?: string;
+    id?: string;
+    area?: string;
+    problem?: string;
+    impact?: string;
+}>(finding: T): T;
+export declare function unverifiedChanges<T>(changes: {
+    resolvedFindings?: T[];
+    fixedFindings?: T[];
+    unverifiedFindings?: T[];
+}): T[];
+export declare function publicReport<T>(report: T): T;

package/dist/report/rules.js

@@ -0,0 +1,301 @@
+// Every rule the report can raise: where it lives, how severe it is by
+// default, how sure the scanner is, which evidence it needs, what the
+// problem is and why it matters. No remediation instructions anywhere:
+// the report describes conditions, not fixes.
+export const topicLabels = {
+    "availability-security": "Availability and security",
+    "crawling-indexability": "Crawling and indexability",
+    "content-structure": "Content and structure",
+    "links-navigation": "Links and navigation",
+    "structured-data": "Structured data",
+    performance: "Performance",
+    "accessibility-usability": "Accessibility and usability",
+    "business-profiles": "Business and profiles",
+    "ai-agent-access": "AI and agent access",
+};
+export const topicOrder = Object.keys(topicLabels);
+const rule = (topic, severity, confidence, requires, title, problem, impact) => ({ topic, severity, confidence, requires, title, problem, impact });
+export const rules = {
+    // Availability and security
+    "homepage-unreachable": rule("availability-security", "critical", "confirmed", "pages", "Homepage not reachable", "The homepage did not return a successful response to the scanner.", "Visitors, search engines and agents cannot reach the site's entry point."),
+    "tls-invalid": rule("availability-security", "critical", "confirmed", "tls", "TLS certificate not valid", "The HTTPS certificate failed validation for this hostname.", "Browsers show a security warning and most visitors leave; automated clients refuse the connection."),
+    "tls-expiring": rule("availability-security", "critical", "confirmed", "tls", "TLS certificate expires soon", "The certificate's validity ends within two weeks.", "Once it lapses every HTTPS visit fails with a browser error."),
+    "tls-grade-low": rule("availability-security", "warning", "confirmed", "ssl-labs", "Weak TLS configuration", "SSL Labs grades the TLS setup C or lower.", "Outdated protocols or ciphers weaken transport security and can fail compliance checks."),
+    "domain-expiring": rule("availability-security", "critical", "confirmed", "domain", "Domain registration expires soon", "The public registration record shows an approaching expiry date.", "An expired registration takes the whole site and its email offline."),
+    "insecure-forms": rule("availability-security", "critical", "confirmed", "pages", "Forms submit over plain HTTP", "A form's action is an http:// address.", "Submitted data travels unencrypted and browsers warn or block the submission."),
+    "http-not-redirected": rule("availability-security", "warning", "confirmed", "url-variant", "HTTP served without redirect to HTTPS", "The plain-HTTP address returns content instead of redirecting.", "Visitors can use the site unencrypted and two versions of every URL exist."),
+    "security-headers": rule("availability-security", "warning", "confirmed", "pages", "Missing security headers on the homepage", "One or more browser protection headers were absent from the homepage response.", "Browsers cannot enforce transport security, framing or content-type protections the headers would enable."),
+    "email-authentication": rule("availability-security", "warning", "confirmed", "dns", "Email authentication incomplete", "The domain's SPF or DMARC records are missing or DMARC has no enforcing policy.", "Receiving servers cannot verify mail from the domain, which makes spoofing easier and delivery less reliable."),
+    "email-transport-security": rule("availability-security", "hint", "confirmed", "dns", "No MTA-STS policy for mail transport", "The domain receives mail but publishes no MTA-STS record.", "Mail in transit to the domain can be downgraded to an unencrypted connection."),
+    "mixed-content": rule("availability-security", "warning", "confirmed", "browser", "HTTPS pages load HTTP resources", "A secure page requested resources over plain HTTP.", "Browsers block or flag the insecure requests, so parts of the page fail or the padlock disappears."),
+    "trackers-before-consent": rule("availability-security", "warning", "probable", "browser", "Trackers loaded before any consent", "Known tracking hosts were contacted on first load, before any interaction.", "Where consent is required, tracking before the choice is made carries legal exposure. The purpose of each request was not established."),
+    "cookies-before-consent": rule("availability-security", "warning", "probable", "browser", "Third-party cookies set before any consent", "Cookies from other domains existed after the first load without interaction.", "Where consent is required this may count as tracking before consent."),
+    "safe-browsing-flagged": rule("availability-security", "critical", "confirmed", "safe-browsing", "Google Safe Browsing flags this site", "The site is listed as unsafe by Google Safe Browsing.", "Chrome and other browsers show a full-page warning before the site."),
+    blocklisted: rule("availability-security", "critical", "confirmed", "blocklists", "Domain on a spam blocklist", "A public blocklist lists the domain.", "Mail from the domain is rejected or marked as spam and some filters block links to the site."),
+    "staging-hostnames": rule("availability-security", "hint", "review", "certificates", "Staging-like hostnames have certificates", "Certificate transparency logs show hostnames that look like test or staging environments.", "If those hosts are reachable, unfinished or duplicate content is publicly exposed. Logs also list hosts that no longer exist."),
+    // Crawling and indexability
+    "broken-pages": rule("crawling-indexability", "critical", "confirmed", "pages", "Broken pages", "Internal pages return an error status or no response.", "Visitors following these links hit an error and search engines drop the pages."),
+    "homepage-noindex": rule("crawling-indexability", "critical", "confirmed", "pages", "Homepage excluded from search", "The homepage carries a noindex directive without a configured exception.", "The site's main page cannot appear in search results."),
+    "unexpected-noindex": rule("crawling-indexability", "critical", "confirmed", "pages", "Pages excluded from search", "Pages carry a noindex directive without a configured exception.", "These pages cannot appear in search results."),
+    "search-blocked": rule("crawling-indexability", "critical", "confirmed", "robots", "Googlebot blocked by robots.txt", "The robots policy disallows Googlebot for the homepage.", "Google cannot crawl the site, so its pages drop out of or never reach the index."),
+    "robots-unavailable": rule("crawling-indexability", "warning", "confirmed", "robots", "robots.txt could not be retrieved", "The robots file returned an error or was unreadable.", "Crawlers cannot tell what they may fetch; many stop crawling when robots.txt returns a server error."),
+    "canonical-broken": rule("crawling-indexability", "warning", "confirmed", "analysis", "Canonical targets do not respond OK", "A canonical link points to a URL that returned an error.", "Search engines ignore a canonical to a broken page and choose a URL themselves."),
+    "canonical-rendered-differs": rule("crawling-indexability", "warning", "probable", "rendered", "Canonical differs after JavaScript", "The canonical in the rendered page is not the one in the original HTML.", "Crawlers that read the HTML and crawlers that render see different preferred URLs."),
+    "robots-rendered-differs": rule("crawling-indexability", "warning", "probable", "rendered", "Indexing directive differs after JavaScript", "The robots meta directive changes once scripts run.", "Whether a page is indexed depends on whether the crawler executes JavaScript."),
+    "sitemap-missing": rule("crawling-indexability", "warning", "confirmed", "sitemap", "No valid XML sitemap found", "Neither robots.txt nor the common locations served a valid sitemap.", "Search engines rely on links alone to discover pages, so deep or new pages are found later or not at all."),
+    "sitemap-invalid": rule("crawling-indexability", "warning", "confirmed", "sitemap", "Sitemap could not be parsed", "A declared or linked sitemap returned an error or invalid XML.", "Its URLs are not submitted to search engines."),
+    "sitemap-problems": rule("crawling-indexability", "warning", "confirmed", "sitemap", "Sitemap lists pages that are broken, redirected or excluded", "Sitemap entries point to error pages, redirects or noindex pages.", "Search engines treat such entries as noise and trust the sitemap less."),
+    "sitemap-dates": rule("crawling-indexability", "warning", "confirmed", "sitemap", "Sitemap lastmod dates that cannot be right", "Modification dates are unreadable, in the future or several years old.", "Search engines ignore unreliable dates, losing the freshness signal for every entry."),
+    "sitemap-not-listed": rule("crawling-indexability", "hint", "review", "sitemap", "Indexable pages missing from the sitemap", "Crawled indexable pages do not appear in any sitemap.", "These pages depend on links alone for discovery; some may be intentionally left out."),
+    "orphan-pages": rule("crawling-indexability", "warning", "review", "analysis", "Sitemap pages that no page links to", "The sitemap lists a page with no incoming link in the observed crawl.", "Without links the page gets little crawl attention and no internal relevance; unseen links may still exist."),
+    "trailing-slash-variants": rule("crawling-indexability", "warning", "confirmed", "pages", "Slash variants serve duplicates or diverge", "The URL with and without a trailing slash both return content without a shared canonical, or redirect to different pages.", "Two addresses compete for the same page and links split between them."),
+    "canonicalized-slash-variants": rule("crawling-indexability", "hint", "confirmed", "pages", "Both slash variants return content with a shared canonical", "Both URL forms respond 200 and declare the same canonical.", "Crawlers fetch both forms; the canonical resolves the duplicate but doubles crawl work."),
+    "different-slash-content": rule("crawling-indexability", "hint", "review", "pages", "Slash variants serve different content", "The URL with and without a trailing slash return different pages.", "Links and shares that differ only by the slash reach different content."),
+    "redirect-chains": rule("crawling-indexability", "warning", "confirmed", "pages", "Internal redirects through several hops", "An internal destination needed two or more redirects.", "Each hop adds latency and crawlers may stop following after a few."),
+    "hreflang-not-reciprocal": rule("crawling-indexability", "warning", "confirmed", "analysis", "hreflang links without a return link", "A language alternate does not link back to the source page.", "Search engines ignore hreflang pairs that are not confirmed from both sides."),
+    "hreflang-unreachable": rule("crawling-indexability", "warning", "confirmed", "analysis", "hreflang targets that do not respond OK", "A declared language alternate returned an error or could not be fetched.", "The alternate cannot be shown to visitors of that language."),
+    "hreflang-invalid": rule("crawling-indexability", "warning", "confirmed", "analysis", "Invalid hreflang language tags", "A hreflang value is not a valid language or region tag.", "Search engines drop the invalid alternate."),
+    "pagination-broken": rule("crawling-indexability", "warning", "confirmed", "analysis", "Pagination links to broken pages", "A next or numbered pagination link returned an error.", "Items beyond the broken page are unreachable through the listing."),
+    "pagination-canonical-first": rule("crawling-indexability", "hint", "review", "analysis", "Paginated pages canonical to the first page", "Pages 2 and beyond declare the first page as canonical.", "Items only listed on later pages lose their listing signal; this can be intentional."),
+    "pagination-noindex": rule("crawling-indexability", "hint", "review", "analysis", "Paginated pages carry noindex", "Listing pages beyond the first are excluded from indexing.", "Search engines may still follow the links, but the listing pages themselves do not rank; often intentional."),
+    "rendered-only-pages": rule("crawling-indexability", "hint", "probable", "rendered", "Pages linked only through JavaScript", "These pages are reachable only through links that scripts add after load.", "Crawlers and agents that do not run JavaScript cannot discover them from other pages."),
+    // Content and structure
+    "missing-title": rule("content-structure", "warning", "confirmed", "pages", "Pages without a title", "The page has no title element.", "Search results and browser tabs show the URL or a guessed label instead."),
+    "title-length": rule("content-structure", "hint", "review", "pages", "Titles outside 30 to 60 characters", "The title is shorter or longer than Scan's editorial range.", "Very short titles say little; long ones are cut off in search results. Search engines set no requirement."),
+    "missing-description": rule("content-structure", "warning", "confirmed", "pages", "Pages without a meta description", "The page has no meta description.", "Search engines and sharing previews compose a snippet themselves."),
+    "description-length": rule("content-structure", "hint", "review", "pages", "Meta descriptions outside 70 to 160 characters", "The description is shorter or longer than Scan's editorial range.", "Short descriptions waste the snippet; long ones are cut off."),
+    "duplicate-titles": rule("content-structure", "warning", "confirmed", "analysis", "Duplicate titles", "Several pages use the same title.", "The pages are hard to tell apart in search results and browser history, and search engines may pick one."),
+    "duplicate-descriptions": rule("content-structure", "hint", "confirmed", "analysis", "Duplicate meta descriptions", "Several pages share one meta description.", "Snippets do not describe the individual page."),
+    "duplicate-content": rule("content-structure", "hint", "review", "analysis", "Identical page text", "The extracted main text of several pages is identical.", "Search engines fold identical pages into one; shared navigation can also cause this on very short pages."),
+    "similar-content": rule("content-structure", "hint", "review", "analysis", "Pages with similar text", "Pages share at least 90% of their sampled word sets.", "Near-identical pages compete with each other; the heuristic ignores word order and meaning."),
+    "substituted-content": rule("content-structure", "hint", "review", "analysis", "Template text with a few words swapped", "Pairs of pages are identical except for a handful of words, typically a place or product name.", "Search engines may treat such pages as one; whether that matters depends on their purpose. No claim of search cannibalization is made."),
+    "overlapping-collections": rule("content-structure", "hint", "review", "analysis", "Listings with the same items", "Collection pages link to almost the same set of products.", "Near-identical listings dilute each other's signals; filters and sort variants often cause this."),
+    "thin-pages": rule("content-structure", "hint", "review", "pages", "Pages under 100 words", "The main content holds fewer than 100 words.", "Short pages can be exactly right (contact, portfolio); very thin pages give visitors and search engines little to work with. Not a minimum requirement."),
+    "h1-missing": rule("content-structure", "warning", "confirmed", "pages", "Pages without an H1 heading", "The page has no first-level heading.", "Readers and assistive technology lack the page's main topic marker."),
+    "h1-multiple": rule("content-structure", "hint", "review", "pages", "Pages with several H1 headings", "More than one first-level heading exists.", "The page's main topic is ambiguous for readers and tools; sectioned layouts sometimes do this on purpose."),
+    "heading-skips": rule("content-structure", "hint", "confirmed", "pages", "Heading levels that skip", "Heading levels jump, for example from H2 to H4.", "Screen reader users navigating by heading lose the outline."),
+    "long-paragraphs": rule("content-structure", "hint", "review", "pages", "Paragraphs over 150 words", "Some paragraphs exceed 150 words.", "Long blocks are harder to scan on small screens."),
+    "long-sentences": rule("content-structure", "hint", "review", "pages", "Many sentences over 20 words", "More than a quarter of paragraph sentences exceed 20 words.", "Long sentences reduce readability; the count is a heuristic."),
+    "language-mismatch": rule("content-structure", "warning", "probable", "pages", "Declared language differs from the text", "The lang attribute does not match the language the text appears to be written in.", "Screen readers pronounce the page with the wrong voice and search engines may target the wrong audience."),
+    "language-switch-mismatch": rule("content-structure", "warning", "probable", "analysis", "Language switch leads to another language", "A language-switch link leads to a page whose declared or detected language is different.", "Visitors choosing a language land on content in another one."),
+    "content-requires-javascript": rule("content-structure", "hint", "probable", "rendered", "Most text only appears after JavaScript", "Less than half of the rendered text exists in the original HTML.", "Crawlers, agents and readers without JavaScript see a mostly empty page."),
+    "title-rendered-differs": rule("content-structure", "hint", "probable", "rendered", "Title or headings change after JavaScript", "The title or headings in the rendered page differ from the original HTML.", "Tools reading only the HTML index a different title or outline than visitors see."),
+    // Links and navigation
+    "broken-resources": rule("links-navigation", "warning", "confirmed", "pages", "Broken images, scripts or files on this site", "Internal files linked or embedded by pages return an error.", "Images do not show, scripts do not run or downloads fail."),
+    "broken-external-resources": rule("links-navigation", "warning", "confirmed", "pages", "Broken links and files on other sites", "External destinations returned an error or no response.", "Visitors following the link reach an error page on another site."),
+    "unverifiable-external": rule("links-navigation", "hint", "review", "pages", "External destinations that could not be verified", "External destinations answered with a block, login or rate limit.", "The link may work for visitors; automated checks cannot tell."),
+    "broken-anchors": rule("links-navigation", "warning", "confirmed", "analysis", "Links to missing page anchors", "A link's fragment identifier does not exist on the destination.", "The visitor lands at the top of the page instead of the intended section."),
+    "external-redirect-chains": rule("links-navigation", "hint", "confirmed", "pages", "External links reached through redirects", "Successful external destinations needed two or more redirects, including consent or regional routing.", "Each hop adds latency; the destination still works."),
+    "vague-anchors": rule("links-navigation", "hint", "review", "analysis", "Links with vague or empty text", "Content links read 'click here', 'more' or have no text or image alternative.", "Screen reader users hearing the link out of context cannot tell where it leads, and search engines get no topic signal."),
+    "few-contextual-links": rule("links-navigation", "hint", "review", "analysis", "Pages with no contextual links compared with peers", "Within a group of similar pages, some receive links only from navigation while their peers are also linked from content.", "These pages get less internal relevance than comparable pages. Which pages matter most was not judged."),
+    "deep-pages": rule("links-navigation", "hint", "review", "analysis", "Pages four or more clicks from the homepage", "The shortest observed link path from the homepage needs four or more clicks.", "Deep pages are crawled less often and are harder for visitors to reach; the depth reflects observed links only."),
+    "language-switch-broken": rule("links-navigation", "warning", "confirmed", "analysis", "Language switch leads to an error", "A language-switch link returned an error or could not be fetched.", "Visitors cannot reach that language version."),
+    "pagination-rendered-only": rule("links-navigation", "hint", "probable", "rendered", "Pagination only exists after JavaScript", "Next or numbered links appear only in the rendered page.", "Crawlers and agents without JavaScript cannot reach later listing pages."),
+    "map-link-broken": rule("links-navigation", "warning", "confirmed", "pages", "Map links that do not respond OK", "A link to a map service returned an error.", "Visitors cannot open the location."),
+    // Structured data
+    "structured-data-invalid": rule("structured-data", "warning", "confirmed", "pages", "Structured data that does not parse", "A JSON-LD block is not valid JSON.", "Search engines and agents ignore the whole block."),
+    "structured-data-structural": rule("structured-data", "warning", "confirmed", "pages", "Structured data with invalid @type or @id shapes", "A JSON-LD node uses a non-string @type or @id.", "Processors reject or misread the node."),
+    "structured-data-missing": rule("structured-data", "hint", "confirmed", "pages", "No structured data on any page", "No page carries JSON-LD.", "Search engines and agents get no machine-readable description of the site's entities; optional, not a requirement."),
+    "homepage-business-schema": rule("structured-data", "hint", "review", "pages", "Homepage has no organization or business data", "No Organization, LocalBusiness or Person node was found on the homepage.", "Search engines and agents cannot read the site owner's identity from the page; whether it is wanted depends on the site."),
+    "rich-result-required-missing": rule("structured-data", "warning", "confirmed", "analysis", "Rich-result properties missing", "A structured-data node lacks properties Google documents as required for that result type.", "The item is unlikely to qualify for the corresponding rich result; presence of the properties does not guarantee eligibility."),
+    "offer-price-mismatch": rule("structured-data", "warning", "probable", "analysis", "Declared price differs from the visible price", "The JSON-LD offer price does not appear among the prices shown in the page text.", "Search results and agents may quote a price the visitor does not see; a discount or variant display can explain it."),
+    "offer-currency-mismatch": rule("structured-data", "warning", "probable", "analysis", "Declared currency differs from the visible currency", "The JSON-LD price currency is not the currency shown on the page.", "Listings can show the wrong currency."),
+    "offer-availability-mismatch": rule("structured-data", "warning", "probable", "analysis", "Declared availability contradicts the page", "The JSON-LD availability says in stock while the page says sold out, or the reverse.", "Listings show items as available or unavailable against what the page says."),
+    "offer-comparison-review": rule("structured-data", "hint", "review", "analysis", "Offer comparison ambiguous", "Several products, price ranges or many visible prices made a declared-versus-visible comparison inconclusive.", "Mismatches could not be confirmed or ruled out."),
+    "structured-data-rendered-only": rule("structured-data", "hint", "probable", "rendered", "Structured data only present after JavaScript", "JSON-LD appears in the rendered page but not in the original HTML.", "Processors that do not run scripts do not see it."),
+    // Performance
+    "slow-mobile": rule("performance", "warning", "confirmed", "lighthouse", "Mobile performance score below 50", "Lighthouse's simulated mobile performance score is below 50.", "On a mid-range phone with a slow connection the page loads noticeably slowly."),
+    "performance-opportunities": rule("performance", "warning", "confirmed", "lighthouse", "Substantial load-time waste measured by Lighthouse", "A Lighthouse audit estimates at least 500 ms or 100 KB of avoidable loading.", "The estimated savings show how much faster the page could load under the same conditions."),
+    "small-performance-opportunities": rule("performance", "hint", "confirmed", "lighthouse", "Smaller load-time waste measured by Lighthouse", "A Lighthouse audit estimates a small amount of avoidable loading.", "Minor on its own; listed for completeness."),
+    "heavy-pages": rule("performance", "warning", "confirmed", "lighthouse", "Pages over 3 MB on mobile", "The page transfers more than 3 MB on a mobile load.", "Slow connections take many seconds and data plans are consumed."),
+    "slow-responses": rule("performance", "warning", "confirmed", "pages", "Slow server responses", "The HTML response took over 1.5 seconds.", "Everything else waits for the HTML, so the whole page is late."),
+    "slow-lcp-own-browser": rule("performance", "warning", "confirmed", "browser", "Largest paint over 4 seconds on a fast connection", "In the unthrottled browser pass the largest content element rendered after 4 seconds.", "Real visitors on slower connections wait even longer."),
+    "field-vitals-poor": rule("performance", "warning", "confirmed", "field-data", "Real visitors experience poor Core Web Vitals", "Chrome UX Report data for the origin exceeds Google's poor thresholds.", "Real visitors experience slow loading, sluggish interaction or shifting layout; Google uses these thresholds in ranking."),
+    "field-page-vitals-poor": rule("performance", "warning", "confirmed", "field-data", "Real visitors experience poor vitals on specific pages", "Page-level Chrome UX Report data exceeds the poor thresholds.", "Visitors of this page experience slow loading, sluggish interaction or shifting layout."),
+    "unsized-images": rule("performance", "warning", "confirmed", "lighthouse", "Images without dimensions shift the layout", "Images lack width and height so the browser cannot reserve their space.", "Content jumps while images load, which counts against layout stability."),
+    // Accessibility and usability
+    "accessibility-violations": rule("accessibility-usability", "warning", "confirmed", "browser", "Accessibility rule violated", "axe-core found elements failing this WCAG or best-practice rule.", "Users of assistive technology or keyboards hit a barrier at these elements. Automated checks cover part of WCAG only."),
+    "accessibility-review": rule("accessibility-usability", "hint", "review", "browser", "Accessibility rule needs manual review", "axe-core could not decide this rule automatically for some elements.", "A person needs to check these elements; they may or may not be barriers."),
+    "missing-alt": rule("accessibility-usability", "warning", "confirmed", "pages", "Images without alt text", "Images have no alt attribute at all.", "Screen readers announce the file name or nothing; decorative images need an empty alt to be skipped."),
+    "forms-without-labels": rule("accessibility-usability", "warning", "confirmed", "pages", "Form fields without a label", "Fields have no label, aria-label or referenced label text.", "Screen reader users cannot tell what to enter."),
+    "mobile-overflow": rule("accessibility-usability", "warning", "confirmed", "browser", "Content wider than a phone screen", "The document is wider than the viewport at phone widths.", "Visitors scroll sideways or miss content at the edge."),
+    "focus-indicator": rule("accessibility-usability", "hint", "review", "browser", "Focused elements without a visible indicator", "Tab stops showed no outline or box shadow in their computed style.", "Keyboard users cannot see where they are; custom focus styles using other techniques are not detected."),
+    "javascript-errors": rule("accessibility-usability", "warning", "confirmed", "browser", "JavaScript errors from this site's own code", "The browser logged uncaught errors from the site's scripts.", "Features depending on the failing script may not work for visitors."),
+    "external-errors": rule("accessibility-usability", "hint", "confirmed", "browser", "Errors from third-party scripts and blocked requests", "The browser logged errors from other domains or blocked requests.", "Third-party features may fail; many such errors come from ad or tracking blockers."),
+    // Business and profiles
+    "missing-social-image": rule("business-profiles", "warning", "confirmed", "pages", "Homepage has no sharing image", "No og:image or twitter:image is declared.", "Shares on social networks and chat apps show no preview image."),
+    "social-image-broken": rule("business-profiles", "warning", "confirmed", "pages", "Sharing image does not load", "The declared sharing image returned an error or is not an image.", "Shares show a broken or missing preview."),
+    "missing-favicon": rule("business-profiles", "hint", "confirmed", "pages", "No favicon found", "No icon declaration and no /favicon.ico were observed.", "Browser tabs and bookmarks show a generic icon."),
+    "profile-broken": rule("business-profiles", "warning", "confirmed", "pages", "Linked profiles that do not respond OK", "A linked social or video profile on a platform that answers automated requests returned an error.", "Visitors following the link reach a missing profile."),
+    "profile-unverifiable": rule("business-profiles", "hint", "review", "pages", "Linked profiles that could not be verified", "Profiles on platforms that block automated requests could not be checked.", "The links may work for visitors; this scan cannot tell."),
+    "profile-variants": rule("business-profiles", "hint", "review", "analysis", "Several profile URLs for one platform", "Pages link to more than one profile address on the same platform.", "Visitors and search engines may see different profiles as the official one; some may be intentional (regional or personal profiles)."),
+    "sameas-not-linked": rule("business-profiles", "hint", "review", "analysis", "sameAs profiles not linked on the site", "Structured data lists profiles that no page links to.", "The declared identity and the visible identity differ."),
+    "linked-not-sameas": rule("business-profiles", "hint", "review", "analysis", "Linked profiles missing from sameAs", "Pages link to profiles that the organization's structured data does not list.", "Search engines cannot connect these profiles to the organization from the structured data."),
+    "business-name-variants": rule("business-profiles", "hint", "review", "analysis", "Business name written in several ways", "Structured data, site name and title use different names.", "Search engines and agents may not recognise them as one business; abbreviations and legal names often differ on purpose."),
+    "phone-mismatch": rule("business-profiles", "hint", "review", "analysis", "Phone numbers differ between structured data and pages", "Declared telephone numbers and visible phone numbers do not match.", "Search results may show a number visitors cannot find on the site, or the reverse."),
+    // AI and agent access
+    "llms-missing": rule("ai-agent-access", "hint", "confirmed", "ai-discovery", "No llms.txt (optional)", "The site serves no /llms.txt.", "Agents that look for it fall back to the HTML; the file is optional and has no ranking effect."),
+    "llms-links-broken": rule("ai-agent-access", "warning", "confirmed", "ai-discovery", "llms.txt links that do not respond OK", "Links listed in llms.txt returned an error.", "Agents following the file's guidance reach errors."),
+    "llms-title-mismatch": rule("ai-agent-access", "hint", "review", "ai-discovery", "llms.txt title differs from the site name", "The first heading in llms.txt does not match the site's declared names.", "Agents may not connect the file with the site; naming differences can be intentional."),
+    "markdown-unavailable": rule("ai-agent-access", "hint", "confirmed", "pages", "No Markdown version of pages found", "Neither content negotiation nor common .md locations returned Markdown.", "Agents read the HTML instead; optional and increasingly offered by documentation sites."),
+};
+export const areaTopics = {
+    availability: "availability-security",
+    search: "crawling-indexability",
+    performance: "performance",
+    accessibility: "accessibility-usability",
+    quality: "links-navigation",
+};
+// Problem and impact for a finding; historical findings keep their stored
+// title and fall back to their area when the code is unknown.
+export function findingGuidance(code, area) {
+    const known = rules[code];
+    if (known)
+        return {
+            topic: known.topic,
+            problem: known.problem,
+            impact: known.impact,
+            confidence: known.confidence,
+        };
+    return {
+        topic: areaTopics[area ?? ""] ?? "links-navigation",
+        problem: "The scan recorded this condition; the evidence lists what was observed.",
+        impact: "Impact depends on the affected pages.",
+        confidence: "confirmed",
+    };
+}
+// Lighthouse audit titles are phrased as advice; the report names the
+// measured condition instead.
+const auditConditions = {
+    "render-blocking-resources": "Render-blocking resources delay the first paint",
+    "render-blocking-insight": "Render-blocking resources delay the first paint",
+    "unused-javascript": "Unused JavaScript is downloaded",
+    "unused-css-rules": "Unused CSS is downloaded",
+    "modern-image-formats": "Images use formats with larger transfer sizes",
+    "uses-optimized-images": "Images are larger than an efficient encoding",
+    "uses-responsive-images": "Images are larger than their rendered size",
+    "image-delivery-insight": "Image delivery transfers more bytes than needed",
+    "offscreen-images": "Offscreen images load before they are needed",
+    "unminified-javascript": "JavaScript is served unminified",
+    "unminified-css": "CSS is served unminified",
+    "uses-text-compression": "Text resources are served without compression",
+    "server-response-time": "The server responds slowly to the document request",
+    "document-latency-insight": "The document request is slow, redirected or uncompressed",
+    redirects: "The page redirects before loading",
+    "uses-rel-preconnect": "Third-party origins connect late",
+    "efficient-animated-content": "Animated content is large",
+    "legacy-javascript": "Legacy JavaScript polyfills are shipped to modern browsers",
+    "legacy-javascript-insight": "Legacy JavaScript polyfills are shipped to modern browsers",
+    "duplicated-javascript-insight": "The same JavaScript is bundled more than once",
+    "uses-long-cache-ttl": "Static resources have short cache lifetimes",
+    "cache-insight": "Static resources have short cache lifetimes",
+    "third-parties-insight": "Third-party code takes main-thread time",
+    "third-party-summary": "Third-party code takes main-thread time",
+    "font-display-insight": "Web fonts block text rendering while loading",
+    "lcp-discovery-insight": "The largest content element is discovered late",
+    "lcp-breakdown-insight": "The largest content element renders late",
+    "network-dependency-tree-insight": "A long chain of requests precedes rendering",
+    "forced-reflow-insight": "Scripts force layout recalculation",
+    "dom-size-insight": "The page has a very large DOM",
+    "modern-http-insight": "Resources are served over HTTP/1.1",
+    "viewport-insight": "The viewport meta tag delays interaction",
+    "cls-culprits-insight": "Elements shift the layout after load",
+    "total-byte-weight": "The page transfers a very large number of bytes",
+    "bootup-time": "JavaScript execution takes a long time",
+    "mainthread-work-breakdown": "The main thread is busy for a long time",
+    "dom-size": "The page has a very large DOM",
+    "prioritize-lcp-image": "The largest image is requested late",
+    "largest-contentful-paint-element": "The largest content element renders late",
+    "uses-passive-event-listeners": "Scroll listeners are not passive",
+};
+export const auditCondition = (id) => auditConditions[id] ?? `Lighthouse measurement: ${id}`;
+const accessibilityConditions = {
+    "color-contrast": "Text contrast is below the measured threshold",
+    "landmark-one-main": "A main landmark is absent or repeated",
+    region: "Content is outside page landmarks",
+    "landmark-unique": "Landmark roles and labels are repeated",
+    "image-alt": "Images lack an accessible text alternative",
+    "button-name": "Buttons lack an accessible name",
+    "link-name": "Links lack an accessible name",
+    label: "Form controls lack an accessible label",
+    "html-has-lang": "The document language is absent",
+    "html-lang-valid": "The document language value is invalid",
+    "document-title": "The document title is absent",
+    "heading-order": "Heading levels skip a level",
+};
+export const accessibilityCondition = (id, manual = false) => manual
+    ? `Accessibility check needs manual review (${id})`
+    : `${accessibilityConditions[id] ?? "Accessibility rule violation"} (${id})`;
+// Normalize scanner-generated prose only. Site text, URLs, selectors and
+// measured values remain evidence, even when the site itself uses advice.
+export function diagnosticEvidence(value) {
+    if (Array.isArray(value))
+        return value.map(diagnosticEvidence);
+    if (!value || typeof value !== "object")
+        return value;
+    const source = value;
+    const result = {};
+    for (const [key, item] of Object.entries(source)) {
+        if ([
+            "description",
+            "action",
+            "help",
+            "helpUrl",
+            "failureSummary",
+            "guidance",
+        ].includes(key))
+            continue;
+        if (key === "title") {
+            if (typeof source.id === "string")
+                result.title = auditCondition(source.id);
+            continue;
+        }
+        result[key] = diagnosticEvidence(item);
+    }
+    return result;
+}
+export function publicFinding(finding) {
+    const { description: _description, action: _action, ...rest } = finding;
+    const group = finding.group ?? finding.id?.slice(finding.code.length + 1);
+    let title = finding.title;
+    if (finding.code === "accessibility-violations" ||
+        finding.code === "accessibility-review")
+        title = group
+            ? accessibilityCondition(group, finding.code === "accessibility-review")
+            : rules[finding.code].title;
+    else if (["performance-opportunities", "small-performance-opportunities"].includes(finding.code))
+        title = group ? auditCondition(group) : rules[finding.code].title;
+    else if (!finding.problem)
+        title = rules[finding.code]?.title ?? `Observed condition: ${finding.code}`;
+    return { ...rest, title };
+}
+export function unverifiedChanges(changes) {
+    return [
+        ...(changes.unverifiedFindings ?? []),
+        ...(changes.resolvedFindings === undefined
+            ? (changes.fixedFindings ?? [])
+            : []),
+    ];
+}
+export function publicReport(report) {
+    if (!report || typeof report !== "object")
+        return report;
+    const source = report;
+    const changes = source.changes ? { ...source.changes } : source.changes;
+    if (changes)
+        for (const key of [
+            "newFindings",
+            "resolvedFindings",
+            "fixedFindings",
+            "unverifiedFindings",
+            "recurringFindings",
+            "worsenedFindings",
+        ])
+            if (Array.isArray(changes[key]))
+                changes[key] = changes[key].map(publicFinding);
+    return {
+        ...source,
+        findings: (source.findings ?? []).map(publicFinding),
+        changes,
+    };
+}