@eightmedia/flightcheck 0.0.0-stage → 0.1.0

package/dist/analyze/report.js

@@ -0,0 +1,726 @@
+import { z } from "zod";
+import { aggregateStackFromRecords } from "./stack.js";
+const iconSchema = z.object({
+    rel: z.string(),
+    href: z.string(),
+    type: z.string(),
+    sizes: z.string(),
+    media: z.string(),
+});
+const trackingItemSchema = z.object({
+    provider: z.string(),
+    id: z.string(),
+});
+const secretFindingSchema = z.object({
+    type: z.string(),
+    provider: z.string(),
+    severity: z.enum(["critical", "review"]),
+    masked: z.string(),
+    source: z.string(),
+});
+const crawlIssueSchema = z.object({
+    id: z.string(),
+    severity: z.enum(["critical", "error", "warning", "review"]),
+    message: z.string(),
+});
+const stackDetectionSchema = z.object({
+    name: z.string(),
+    categories: z.array(z.string()),
+    confidence: z.enum(["high", "medium", "low"]),
+    evidence: z.array(z.string()),
+    website: z.string().optional(),
+    version: z.string().optional(),
+    detector: z.literal("flightcheck-v1").optional(),
+});
+const recordSchema = z.object({
+    url: z.string(),
+    status: z.number().nullable(),
+    h1: z.string(),
+    title: z.string(),
+    metaTitle: z.string(),
+    metaDescription: z.string(),
+    robots: z.string(),
+    template: z.string().optional().default(""),
+    mainCount: z.number().nullable().optional().default(null),
+    charset: z.string(),
+    language: z.string(),
+    colorScheme: z.string(),
+    themeColor: z.string(),
+    doctype: z.string(),
+    viewport: z.string(),
+    canonical: z.string(),
+    favicon: z.string(),
+    icons: z.array(iconSchema),
+    og: z.object({
+        title: z.string(),
+        description: z.string(),
+        image: z.string(),
+        url: z.string(),
+        type: z.string(),
+        siteName: z.string(),
+    }),
+    twitter: z.object({
+        card: z.string(),
+        title: z.string(),
+        description: z.string(),
+        image: z.string(),
+    }),
+    tracking: z.object({
+        tagManager: z.array(trackingItemSchema),
+        analytics: z.array(trackingItemSchema),
+    }),
+    stack: z
+        .object({
+        detections: z.array(stackDetectionSchema),
+    })
+        .optional(),
+    security: z
+        .object({
+        secrets: z.array(secretFindingSchema),
+        scannedAssets: z.number(),
+    })
+        .optional(),
+    images: z.object({ issues: z.array(crawlIssueSchema) }).optional(),
+    a11yStatic: z.object({ issues: z.array(crawlIssueSchema) }).optional(),
+    note: z.string().optional(),
+    error: z.string().optional(),
+});
+export const reportSchema = z.array(recordSchema);
+export function parseReport(json) {
+    return reportSchema.parse(json);
+}
+const fieldSelectors = [
+    { label: "h1", get: (r) => r.h1 },
+    { label: "title", get: (r) => r.title },
+    { label: "metaTitle", get: (r) => r.metaTitle },
+    { label: "metaDescription", get: (r) => r.metaDescription },
+    { label: "charset", get: (r) => r.charset },
+    { label: "language", get: (r) => r.language },
+    { label: "colorScheme", get: (r) => r.colorScheme },
+    { label: "themeColor", get: (r) => r.themeColor },
+    { label: "doctype", get: (r) => r.doctype },
+    { label: "viewport", get: (r) => r.viewport },
+    { label: "canonical", get: (r) => r.canonical },
+    { label: "favicon", get: (r) => r.favicon },
+    { label: "og.title", get: (r) => r.og.title },
+    { label: "og.description", get: (r) => r.og.description },
+    { label: "og.image", get: (r) => r.og.image },
+    { label: "og.url", get: (r) => r.og.url },
+    { label: "og.type", get: (r) => r.og.type },
+    { label: "og.siteName", get: (r) => r.og.siteName },
+    { label: "twitter.card", get: (r) => r.twitter.card },
+    { label: "twitter.title", get: (r) => r.twitter.title },
+    { label: "twitter.description", get: (r) => r.twitter.description },
+    { label: "twitter.image", get: (r) => r.twitter.image },
+    { label: "icons", get: (r) => (r.icons.length > 0 ? ["present"] : []) },
+];
+function isMissingValue(value) {
+    if (Array.isArray(value))
+        return value.length === 0;
+    return value.trim() === "";
+}
+function parseRobotsDirectives(robots) {
+    return new Set(robots
+        .toLowerCase()
+        .split(/[\s,]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0));
+}
+function collectWarnings(record) {
+    const warnings = [];
+    if (record.template.trim() === "") {
+        warnings.push("Missing template meta tag — adding `<meta name=\"template\">` helps flightcheck give better tailored reports.");
+    }
+    const robots = record.robots.trim();
+    if (robots === "")
+        return warnings;
+    const directives = parseRobotsDirectives(robots);
+    if (directives.has("noindex") || directives.has("none")) {
+        warnings.push(`Page is set to noindex (robots: "${robots}") — search engines are told not to index it.`);
+    }
+    if (directives.has("nofollow") || directives.has("none")) {
+        warnings.push(`Page is set to nofollow (robots: "${robots}") — search engines are told not to follow its links.`);
+    }
+    return warnings;
+}
+function collectMainLandmarkIssues(mainCount) {
+    if (mainCount == null || mainCount === 1) {
+        return { todos: [], issueKeys: [] };
+    }
+    const todo = buildMainLandmarkTodo(mainCount, "page");
+    if (mainCount === 0) {
+        return {
+            todos: todo ? [todo] : [],
+            issueKeys: ["main-missing"],
+        };
+    }
+    return {
+        todos: todo ? [todo] : [],
+        issueKeys: ["main-multiple"],
+    };
+}
+const WARNING_LABELS = {
+    noindex: "noindex",
+    nofollow: "nofollow",
+    "missing-template": "missing template meta",
+    "main-missing": "missing main landmark",
+    "main-multiple": "multiple main landmarks",
+};
+const IMAGE_TIER1_IDS = new Set(["missing-alt", "empty-alt", "generic-alt"]);
+const TIER1_LABELS = {
+    "missing-alt": "missing image alt",
+    "empty-alt": "empty image alt",
+    "generic-alt": "generic image alt",
+    "heading-skip": "heading hierarchy skip",
+    "multiple-h1": "multiple h1",
+    "unlabeled-input": "unlabeled form input",
+    "missing-lang": "missing html lang (a11y)",
+    "positive-tabindex": "positive tabindex",
+};
+const TIER1_SCOPE_TODOS = {
+    "missing-alt": {
+        page: "Add alt text to images on page",
+        template: "Add alt text to images in template",
+        site: "Add alt text to images in shared components",
+    },
+    "empty-alt": {
+        page: "Review empty alt attributes on page images",
+        template: "Review empty alt attributes on template images",
+        site: "Review empty alt attributes on shared images",
+    },
+    "generic-alt": {
+        page: "Replace generic image alt text on page",
+        template: "Replace generic image alt text in template",
+        site: "Replace generic image alt text in shared components",
+    },
+    "heading-skip": {
+        page: "Fix heading hierarchy skip on page",
+        template: "Fix heading hierarchy skip in template",
+        site: "Fix heading hierarchy skip in shared layout",
+    },
+    "multiple-h1": {
+        page: "Use a single h1 on page",
+        template: "Use a single h1 in template",
+        site: "Use a single h1 in shared layout",
+    },
+    "unlabeled-input": {
+        page: "Add labels to form inputs on page",
+        template: "Add labels to form inputs in template",
+        site: "Add labels to form inputs in shared components",
+    },
+    "missing-lang": {
+        page: "Add lang attribute to html element on page",
+        template: "Add lang attribute to html element in template",
+        site: "Add lang attribute to html element in site layout",
+    },
+    "positive-tabindex": {
+        page: "Remove positive tabindex values on page",
+        template: "Remove positive tabindex values in template",
+        site: "Remove positive tabindex values in shared layout",
+    },
+};
+const PAGE_TODO_MESSAGES = {
+    h1: "Add h1 to page",
+    title: "Add title element to page head",
+    metaTitle: "Add meta title to page head",
+    metaDescription: "Add meta description tag to page head",
+    charset: "Add charset meta tag to page head",
+    language: "Add lang attribute to html element",
+    colorScheme: "Add color-scheme meta tag to page head",
+    themeColor: "Add theme-color meta tag to page head",
+    doctype: "Add doctype to page",
+    viewport: "Add viewport meta tag to page head",
+    canonical: "Add canonical link to page head",
+    favicon: "Add favicon link to page head",
+    icons: "Add icon links to page head",
+};
+const OG_FIELD_LABELS = {
+    "og.title": "og:title",
+    "og.description": "og:description",
+    "og.image": "og:image",
+    "og.url": "og:url",
+    "og.type": "og:type",
+    "og.siteName": "og:site_name",
+};
+const TWITTER_FIELD_LABELS = {
+    "twitter.card": "twitter:card",
+    "twitter.title": "twitter:title",
+    "twitter.description": "twitter:description",
+    "twitter.image": "twitter:image",
+};
+function scopedHead(scope) {
+    if (scope === "site")
+        return "site layout head";
+    if (scope === "template")
+        return "template head";
+    return "page head";
+}
+function pageTodoForField(field, scope = "page") {
+    const message = PAGE_TODO_MESSAGES[field] ?? `Add ${field} to page`;
+    if (scope === "page")
+        return message;
+    if (scope === "site") {
+        return message
+            .replace(/ to page head/g, " to site layout head")
+            .replace(/ to page/g, " in site layout")
+            .replace(/ to html element/g, " on html element in site layout");
+    }
+    return message
+        .replace(/ to page head/g, " to template head")
+        .replace(/ to page/g, " to template")
+        .replace(/ to html element/g, " in template");
+}
+function buildBundledFieldTodos(missingFields, scope) {
+    const ogFields = [];
+    const twitterFields = [];
+    const otherFields = [];
+    for (const field of missingFields) {
+        if (field.startsWith("og.")) {
+            ogFields.push(field);
+        }
+        else if (field.startsWith("twitter.")) {
+            twitterFields.push(field);
+        }
+        else {
+            otherFields.push(field);
+        }
+    }
+    const head = scopedHead(scope);
+    const todos = [];
+    for (const field of otherFields) {
+        if (field === "fetch") {
+            if (scope === "page")
+                todos.push("- [ ] Resolve page fetch error");
+            else if (scope === "template")
+                todos.push("- [ ] Fix fetch handling in template");
+            else
+                todos.push("- [ ] Fix fetch handling in site routing or server config");
+        }
+        else {
+            todos.push(`- [ ] ${pageTodoForField(field, scope)}`);
+        }
+    }
+    if (ogFields.length > 0) {
+        const labels = ogFields.map((field) => OG_FIELD_LABELS[field] ?? field).join(", ");
+        todos.push(`- [ ] Add Open Graph meta tags to ${head}: ${labels}`);
+    }
+    if (twitterFields.length > 0) {
+        const labels = twitterFields.map((field) => TWITTER_FIELD_LABELS[field] ?? field).join(", ");
+        todos.push(`- [ ] Add Twitter meta tags to ${head}: ${labels}`);
+    }
+    return todos;
+}
+function buildMainLandmarkTodo(mainCount, scope) {
+    if (mainCount == null || mainCount === 1)
+        return null;
+    if (mainCount === 0) {
+        if (scope === "site")
+            return "- [ ] Add main landmark to site layout";
+        if (scope === "template")
+            return "- [ ] Add main landmark to template";
+        return "- [ ] Add main landmark to page";
+    }
+    if (scope === "page")
+        return `- [ ] Ensure page has exactly one main landmark (found ${mainCount})`;
+    if (scope === "site")
+        return "- [ ] Ensure site layout renders exactly one main landmark";
+    return "- [ ] Ensure template renders exactly one main landmark";
+}
+function fieldsMissingOnAllPages(items) {
+    if (items.length === 0)
+        return [];
+    const total = items.length;
+    const fieldCounts = new Map();
+    for (const item of items) {
+        for (const field of item.missingFields) {
+            fieldCounts.set(field, (fieldCounts.get(field) ?? 0) + 1);
+        }
+    }
+    return [...fieldCounts.entries()].filter(([, count]) => count === total).map(([field]) => field);
+}
+function warningKeysOnAllPages(items) {
+    if (items.length === 0)
+        return [];
+    const total = items.length;
+    const keyCounts = new Map();
+    for (const item of items) {
+        for (const key of item.warningKeys) {
+            keyCounts.set(key, (keyCounts.get(key) ?? 0) + 1);
+        }
+    }
+    return [...keyCounts.entries()].filter(([, count]) => count === total).map(([key]) => key);
+}
+function tier1KeysOnAllPages(items) {
+    if (items.length === 0)
+        return [];
+    const total = items.length;
+    const keyCounts = new Map();
+    for (const item of items) {
+        for (const key of item.tier1IssueKeys) {
+            keyCounts.set(key, (keyCounts.get(key) ?? 0) + 1);
+        }
+    }
+    return [...keyCounts.entries()].filter(([, count]) => count === total).map(([key]) => key);
+}
+function countTier1IssueOccurrences(items) {
+    const counts = new Map();
+    for (const item of items) {
+        for (const key of item.tier1IssueKeys) {
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+const SITE_WARNING_TODOS = {
+    noindex: "Remove noindex from shared robots meta tag in site layout",
+    nofollow: "Remove nofollow from shared robots meta tag in site layout",
+    "missing-template": "Add template meta tag to site layout head — helps flightcheck give better tailored reports",
+};
+const TEMPLATE_WARNING_TODOS = {
+    noindex: "Remove noindex from template robots meta tag",
+    nofollow: "Remove nofollow from template robots meta tag",
+};
+const PAGE_WARNING_TODOS = {
+    noindex: "Remove noindex from page robots meta tag",
+    nofollow: "Remove nofollow from page robots meta tag",
+    "missing-template": "Add template meta tag to page head — helps flightcheck give better tailored reports",
+};
+function buildWarningTodos(keys, scope) {
+    const messages = scope === "site" ? SITE_WARNING_TODOS : scope === "template" ? TEMPLATE_WARNING_TODOS : PAGE_WARNING_TODOS;
+    const todos = [];
+    for (const key of keys) {
+        if (key === "main-missing" || key === "main-multiple")
+            continue;
+        const message = messages[key];
+        if (message)
+            todos.push(`- [ ] ${message}`);
+    }
+    if (keys.includes("main-missing")) {
+        const todo = buildMainLandmarkTodo(0, scope);
+        if (todo)
+            todos.push(todo);
+    }
+    else if (keys.includes("main-multiple")) {
+        const todo = buildMainLandmarkTodo(2, scope);
+        if (todo)
+            todos.push(todo);
+    }
+    return todos;
+}
+function buildTier1Todos(keys, scope) {
+    const scopeKey = scope === "site" ? "site" : scope === "template" ? "template" : "page";
+    return keys
+        .map((key) => TIER1_SCOPE_TODOS[key]?.[scopeKey])
+        .filter((message) => Boolean(message))
+        .map((message) => `- [ ] ${message}`);
+}
+function buildImageIssueTodos(issues) {
+    return issues.map((issue) => `- [ ] ${issue.message}`);
+}
+function buildScopedFixTodos(items, scope, excludedFields = new Set(), excludedWarningKeys = new Set(), excludedTier1Keys = new Set()) {
+    const universalFields = fieldsMissingOnAllPages(items).filter((field) => !excludedFields.has(field));
+    const universalWarningKeys = warningKeysOnAllPages(items).filter((key) => !excludedWarningKeys.has(key));
+    const universalTier1Keys = tier1KeysOnAllPages(items).filter((key) => !excludedTier1Keys.has(key));
+    return [
+        ...buildBundledFieldTodos(universalFields, scope),
+        ...buildWarningTodos(universalWarningKeys, scope),
+        ...buildTier1Todos(universalTier1Keys, scope),
+    ];
+}
+function buildRemainingPageTodos(item, coveredFields, coveredWarningKeys, coveredTier1Keys) {
+    const remainingFields = item.missingFields.filter((field) => !coveredFields.has(field));
+    const remainingWarningKeys = item.warningKeys.filter((key) => !coveredWarningKeys.has(key));
+    const remainingTier1Keys = item.tier1IssueKeys.filter((key) => !coveredTier1Keys.has(key));
+    const remainingNonImageTier1Keys = remainingTier1Keys.filter((key) => !IMAGE_TIER1_IDS.has(key));
+    const todos = [...buildBundledFieldTodos(remainingFields, "page")];
+    for (const key of remainingWarningKeys) {
+        if (key === "main-missing" || key === "main-multiple")
+            continue;
+        const message = PAGE_WARNING_TODOS[key];
+        if (message)
+            todos.push(`- [ ] ${message}`);
+    }
+    if (remainingWarningKeys.includes("main-missing")) {
+        todos.push("- [ ] Add main landmark to page");
+    }
+    else if (remainingWarningKeys.includes("main-multiple")) {
+        const todo = buildMainLandmarkTodo(item.mainCount, "page");
+        if (todo)
+            todos.push(todo);
+    }
+    todos.push(...buildTier1Todos(remainingNonImageTier1Keys, "page"));
+    const uncoveredImageIssues = item.imageIssues.filter((issue) => !coveredTier1Keys.has(issue.id));
+    todos.push(...buildImageIssueTodos(uncoveredImageIssues));
+    return todos;
+}
+/**
+ * Structured counterpart to buildRemainingPageTodos: returns the open issues for a page
+ * after site-wide and template coverage is removed, split by surface so the manifest can
+ * route them to the right work package (SEO markup vs best-practice vs a11y/content).
+ * Landmarks stay in warningKeys (owned by best-practices) so they are not double-counted in a11y.
+ */
+function buildRemainingPageData(item, coveredFields, coveredWarningKeys, coveredTier1Keys) {
+    const remainingFields = item.missingFields.filter((field) => !coveredFields.has(field));
+    const remainingWarningKeys = item.warningKeys.filter((key) => !coveredWarningKeys.has(key));
+    const remainingTier1Keys = item.tier1IssueKeys.filter((key) => !coveredTier1Keys.has(key));
+    const remainingNonImageTier1Keys = remainingTier1Keys.filter((key) => !IMAGE_TIER1_IDS.has(key));
+    const remainingA11yIssues = [];
+    for (const key of remainingNonImageTier1Keys) {
+        const message = TIER1_SCOPE_TODOS[key]?.page;
+        if (message)
+            remainingA11yIssues.push({ id: key, message });
+    }
+    for (const issue of item.imageIssues.filter((entry) => !coveredTier1Keys.has(entry.id))) {
+        remainingA11yIssues.push({ id: issue.id, message: issue.message });
+    }
+    return { remainingFields, remainingWarningKeys, remainingA11yIssues };
+}
+function collectTier1IssueKeys(record) {
+    const issues = [...(record.images?.issues ?? []), ...(record.a11yStatic?.issues ?? [])];
+    return [...new Set(issues.map((entry) => entry.id))];
+}
+function analyzeRecord(record) {
+    const missingFields = fieldSelectors
+        .filter((selector) => isMissingValue(selector.get(record)))
+        .map((selector) => selector.label);
+    if (record.error) {
+        missingFields.unshift("fetch");
+    }
+    const warnings = collectWarnings(record);
+    const { todos: mainLandmarkTodos, issueKeys: mainIssueKeys } = collectMainLandmarkIssues(record.mainCount);
+    const warningKeys = [...mainIssueKeys];
+    if (record.template.trim() === "") {
+        warningKeys.push("missing-template");
+    }
+    if (warnings.length > 0) {
+        const directives = parseRobotsDirectives(record.robots);
+        if (directives.has("noindex") || directives.has("none"))
+            warningKeys.push("noindex");
+        if (directives.has("nofollow") || directives.has("none"))
+            warningKeys.push("nofollow");
+    }
+    return {
+        url: record.url,
+        status: record.status,
+        template: record.template.trim(),
+        missingFields,
+        warnings,
+        warningKeys,
+        tier1IssueKeys: collectTier1IssueKeys(record),
+        imageIssues: record.images?.issues ?? [],
+        a11yStaticIssues: record.a11yStatic?.issues ?? [],
+        mainLandmarkTodos,
+        mainCount: record.mainCount,
+        note: record.note,
+        error: record.error,
+    };
+}
+function countFieldOccurrences(items) {
+    const counts = new Map();
+    for (const item of items) {
+        for (const field of item.missingFields) {
+            counts.set(field, (counts.get(field) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+function countWarningOccurrences(items) {
+    const counts = new Map();
+    for (const item of items) {
+        for (const key of item.warningKeys) {
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+function resolveIssueScope(issueKey, count, totalPages, siteWideKeys, templateKeyMap) {
+    if (siteWideKeys.has(issueKey) || count === totalPages)
+        return "site-wide";
+    for (const [template, keys] of templateKeyMap) {
+        if (keys.has(issueKey))
+            return `template: ${template}`;
+    }
+    return "page-specific";
+}
+function buildCoverageSection(allItems, totalPages, siteWideFields, siteWideWarningKeys, siteWideTier1Keys, templateFieldMap, templateWarningKeyMap, templateTier1KeyMap) {
+    const fieldCounts = countFieldOccurrences(allItems);
+    const warningCounts = countWarningOccurrences(allItems);
+    const tier1Counts = countTier1IssueOccurrences(allItems);
+    const lines = ["## Issue coverage", "", "How widely each issue appears across scanned pages:", ""];
+    if (fieldCounts.size === 0 && warningCounts.size === 0 && tier1Counts.size === 0) {
+        lines.push("- No issues found.");
+        return lines;
+    }
+    const sortedFields = [...fieldCounts.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [field, count] of sortedFields) {
+        const scope = resolveIssueScope(field, count, totalPages, siteWideFields, templateFieldMap);
+        lines.push(`- \`${field}\`: ${count}/${totalPages} pages (${scope})`);
+    }
+    const sortedWarnings = [...warningCounts.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [key, count] of sortedWarnings) {
+        const label = WARNING_LABELS[key] ?? key;
+        const scope = resolveIssueScope(key, count, totalPages, siteWideWarningKeys, templateWarningKeyMap);
+        lines.push(`- \`${label}\`: ${count}/${totalPages} pages (${scope})`);
+    }
+    const sortedTier1 = [...tier1Counts.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [key, count] of sortedTier1) {
+        const label = TIER1_LABELS[key] ?? key;
+        const scope = resolveIssueScope(key, count, totalPages, siteWideTier1Keys, templateTier1KeyMap);
+        lines.push(`- \`${label}\`: ${count}/${totalPages} pages (${scope})`);
+    }
+    return lines;
+}
+function formatTemplatesThatNeedFixes(templatesWithFixes, templateGroupCount, totalPages) {
+    if (templatesWithFixes.length > 0) {
+        return templatesWithFixes.map((template) => `\`${template}\``).join(", ");
+    }
+    if (totalPages > 0 && templateGroupCount === 0) {
+        return "Unavailable, template meta missing";
+    }
+    return "none";
+}
+function buildHowToUseSection(redirectOnly) {
+    const lines = ["## How to use this report", ""];
+    if (redirectOnly) {
+        lines.push("1. Fix redirect issues listed below (status code, Location target, HTTPS/HSTS).");
+        lines.push("2. Re-run flightcheck to confirm the redirect is healthy.");
+        lines.push("3. Run against the final destination URL if you need a full site crawl.");
+    }
+    else {
+        lines.push("1. Fix **site-wide** items once in shared layout/head.");
+        lines.push("2. Fix **template** items in each template file.");
+        lines.push("3. Fix **per-page** items in page content or route-specific files.");
+        lines.push("4. Re-run flightcheck and confirm issue counts drop to zero.");
+    }
+    lines.push("");
+    return lines;
+}
+const BEST_PRACTICE_WARNING_KEYS = new Set(["noindex", "nofollow", "missing-template", "main-missing", "main-multiple"]);
+function countCrawlIssueCategories(allItems, records) {
+    let seoIssueCount = 0;
+    let seoPageCount = 0;
+    let a11yIssueCount = 0;
+    let a11yPageCount = 0;
+    let bestPracticesIssueCount = 0;
+    let bestPracticesPageCount = 0;
+    let securityIssueCount = 0;
+    let securityPageCount = 0;
+    for (const item of allItems) {
+        if (item.missingFields.length > 0) {
+            seoIssueCount += item.missingFields.length;
+            seoPageCount += 1;
+        }
+        const a11yOnPage = item.imageIssues.length + item.a11yStaticIssues.length;
+        if (a11yOnPage > 0) {
+            a11yIssueCount += a11yOnPage;
+            a11yPageCount += 1;
+        }
+        const bestPracticeKeys = item.warningKeys.filter((key) => BEST_PRACTICE_WARNING_KEYS.has(key));
+        if (bestPracticeKeys.length > 0) {
+            bestPracticesIssueCount += bestPracticeKeys.length;
+            bestPracticesPageCount += 1;
+        }
+    }
+    for (const record of records) {
+        const secrets = record.security?.secrets.length ?? 0;
+        if (secrets > 0) {
+            securityIssueCount += secrets;
+            securityPageCount += 1;
+        }
+    }
+    return {
+        seo: { issueCount: seoIssueCount, pageCount: seoPageCount },
+        a11y: { issueCount: a11yIssueCount, pageCount: a11yPageCount },
+        bestPractices: { issueCount: bestPracticesIssueCount, pageCount: bestPracticesPageCount },
+        security: { issueCount: securityIssueCount, pageCount: securityPageCount },
+    };
+}
+export async function buildReportAnalysis(records, tier1 = {}, options = {}) {
+    const redirectOnly = options.redirectOnly ?? false;
+    const allItems = records.map(analyzeRecord);
+    const totalPages = allItems.length;
+    const crawlIssueCounts = countCrawlIssueCategories(allItems, records);
+    const siteWideFields = new Set(fieldsMissingOnAllPages(allItems));
+    const siteWideWarningKeys = new Set(warningKeysOnAllPages(allItems));
+    const siteWideTier1Keys = new Set(tier1KeysOnAllPages(allItems));
+    const siteWideFixTodos = buildScopedFixTodos(allItems, "site");
+    const templateGroups = new Map();
+    for (const item of allItems) {
+        if (item.template === "")
+            continue;
+        const group = templateGroups.get(item.template);
+        if (group)
+            group.push(item);
+        else
+            templateGroups.set(item.template, [item]);
+    }
+    const templateFieldMap = new Map();
+    const templateWarningKeyMap = new Map();
+    const templateTier1KeyMap = new Map();
+    for (const [template, items] of templateGroups) {
+        templateFieldMap.set(template, new Set(fieldsMissingOnAllPages(items).filter((field) => !siteWideFields.has(field))));
+        templateWarningKeyMap.set(template, new Set(warningKeysOnAllPages(items).filter((key) => !siteWideWarningKeys.has(key))));
+        templateTier1KeyMap.set(template, new Set(tier1KeysOnAllPages(items).filter((key) => !siteWideTier1Keys.has(key))));
+    }
+    const coveredFieldsByTemplate = new Map();
+    const coveredWarningKeysByTemplate = new Map();
+    const coveredTier1KeysByTemplate = new Map();
+    for (const [template, fields] of templateFieldMap) {
+        coveredFieldsByTemplate.set(template, new Set([...siteWideFields, ...fields]));
+    }
+    for (const [template, keys] of templateWarningKeyMap) {
+        coveredWarningKeysByTemplate.set(template, new Set([...siteWideWarningKeys, ...keys]));
+    }
+    for (const [template, keys] of templateTier1KeyMap) {
+        coveredTier1KeysByTemplate.set(template, new Set([...siteWideTier1Keys, ...keys]));
+    }
+    const pageFixes = [];
+    for (const item of allItems) {
+        const coveredFields = coveredFieldsByTemplate.get(item.template) ?? siteWideFields;
+        const coveredWarningKeys = coveredWarningKeysByTemplate.get(item.template) ?? siteWideWarningKeys;
+        const coveredTier1Keys = coveredTier1KeysByTemplate.get(item.template) ?? siteWideTier1Keys;
+        const remainingTodos = buildRemainingPageTodos(item, coveredFields, coveredWarningKeys, coveredTier1Keys);
+        const { remainingFields, remainingWarningKeys, remainingA11yIssues } = buildRemainingPageData(item, coveredFields, coveredWarningKeys, coveredTier1Keys);
+        const hasSecrets = records.some((record) => record.url === item.url && (record.security?.secrets.length ?? 0) > 0);
+        if (remainingTodos.length === 0 && !hasSecrets)
+            continue;
+        pageFixes.push({ item, remainingTodos, remainingFields, remainingWarningKeys, remainingA11yIssues });
+    }
+    const securityPages = records
+        .map((record) => ({ url: record.url, secrets: record.security?.secrets ?? [] }))
+        .filter((entry) => entry.secrets.length > 0);
+    const stackProfile = options.stackProfile ??
+        (redirectOnly
+            ? { detections: [], tracking: { tagManager: [], analytics: [] } }
+            : aggregateStackFromRecords(records));
+    return {
+        allItems,
+        totalPages,
+        redirectOnly,
+        siteWideFields,
+        siteWideWarningKeys,
+        siteWideTier1Keys,
+        siteWideFixTodos,
+        templateGroups,
+        templateFieldMap,
+        templateWarningKeyMap,
+        templateTier1KeyMap,
+        coveredFieldsByTemplate,
+        coveredWarningKeysByTemplate,
+        coveredTier1KeysByTemplate,
+        pageFixes,
+        securityPages,
+        stackProfile,
+        crawlIssueCounts,
+    };
+}
+export async function buildMarkdown(inputPath, records, includeOnlyErrors, tier1 = {}, options = {}) {
+    const { buildStructuredReport, renderReportMarkdown } = await import("./structuredReport.js");
+    const report = await buildStructuredReport(inputPath, records, tier1, options);
+    if (!includeOnlyErrors)
+        return renderReportMarkdown(report);
+    return renderReportMarkdown({
+        ...report,
+        findings: report.findings.filter((finding) => finding.severity === "critical" || finding.severity === "error"),
+    });
+}