@eightmedia/flightcheck 0.0.0-stage → 1.0.0

package/dist/analyze/reportTier1.d.ts

@@ -0,0 +1,46 @@
+import type { AgentReadyCheckResult } from "../checks/agent-ready.js";
+import type { DnsCheckResult } from "../checks/dns.js";
+import type { RedirectCheckResult } from "../checks/redirect.js";
+import type { RobotsTxtCheckResult } from "../checks/robots-txt.js";
+import type { SecurityHeadersCheckResult } from "../checks/security-headers.js";
+import type { SitemapCheckResult } from "../checks/sitemap.js";
+export type Tier1ReportData = {
+    redirect?: RedirectCheckResult;
+    securityHeaders?: SecurityHeadersCheckResult;
+    dns?: DnsCheckResult;
+    robotsTxt?: RobotsTxtCheckResult;
+    sitemap?: SitemapCheckResult;
+    agentReady?: AgentReadyCheckResult;
+};
+export type BuildMarkdownOptions = {
+    redirectOnly?: boolean;
+    stackProfile?: import("./stack.js").StackProfile;
+};
+export declare function buildRedirectSection(result: RedirectCheckResult): string[];
+export declare function buildDnsSection(dns: DnsCheckResult): string[];
+export declare function buildSecurityHeadersSection(result: SecurityHeadersCheckResult): string[];
+export declare function buildRobotsTxtSection(result: RobotsTxtCheckResult): string[];
+export declare function buildSitemapSection(result: SitemapCheckResult): string[];
+export declare function buildRobotsAndSitemapSection(robotsTxt?: RobotsTxtCheckResult, sitemap?: SitemapCheckResult): string[];
+export declare function buildAgentReadySection(result: AgentReadyCheckResult): string[];
+export declare function countTier1InfraIssues(tier1: Tier1ReportData): number;
+export type CrawlIssueCounts = {
+    seo: {
+        issueCount: number;
+        pageCount: number;
+    };
+    a11y: {
+        issueCount: number;
+        pageCount: number;
+    };
+    bestPractices: {
+        issueCount: number;
+        pageCount: number;
+    };
+    security: {
+        issueCount: number;
+        pageCount: number;
+    };
+};
+export declare function buildIssuesSummarySection(tier1: Tier1ReportData, crawlCounts: CrawlIssueCounts, redirectOnly: boolean, performanceChecked?: boolean, performanceIssueCount?: number, performancePageCount?: number): string[];
+//# sourceMappingURL=reportTier1.d.ts.map

package/dist/analyze/reportTier1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reportTier1.d.ts","sourceRoot":"","sources":["../../src/analyze/reportTier1.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,eAAe,CAAC,EAAE,0BAA0B,CAAC;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,YAAY,EAAE,YAAY,CAAC;CAClD,CAAC;AAUF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAuC1E;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,EAAE,CAkC7D;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,EAAE,CAUxF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAoB5E;AAUD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAkCxE;AAED,wBAAgB,4BAA4B,CAAC,SAAS,CAAC,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAOrH;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAoD9E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CASpE;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,aAAa,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CAAC;AA4BF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,eAAe,EACtB,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,OAAO,EACrB,kBAAkB,UAAQ,EAC1B,qBAAqB,SAAI,EACzB,oBAAoB,SAAI,GACvB,MAAM,EAAE,CA+BV"}

package/dist/analyze/reportTier1.js

@@ -0,0 +1,251 @@
+function severityLabel(severity) {
+    return severity.toUpperCase();
+}
+function issueTodo(issue) {
+    return `- [ ] **${severityLabel(issue.severity)}** ${issue.message}`;
+}
+export function buildRedirectSection(result) {
+    const lines = [
+        "## Domain redirect",
+        "",
+        `- URL: \`${result.url}\``,
+        `- Status: \`${result.status ?? "unreachable"}\``,
+    ];
+    if (result.location) {
+        lines.push(`- Location: \`${result.location}\``);
+    }
+    if (result.resolvedTarget) {
+        lines.push(`- Resolved target: \`${result.resolvedTarget}\``);
+    }
+    if (result.targetStatus !== null) {
+        lines.push(`- Target response: \`${result.targetStatus}\``);
+    }
+    if (result.wwwAlias) {
+        lines.push("");
+        lines.push(`- Canonical host: \`${new URL(result.wwwAlias.canonicalUrl).hostname}\``);
+        lines.push(`- Alternate host: \`${result.wwwAlias.alternateUrl}\``);
+        lines.push(`- Alternate status: \`${result.wwwAlias.status ?? "unreachable"}\``);
+        if (result.wwwAlias.location) {
+            lines.push(`- Alternate Location: \`${result.wwwAlias.location}\``);
+        }
+        if (result.wwwAlias.resolvedTarget) {
+            lines.push(`- Alternate resolved target: \`${result.wwwAlias.resolvedTarget}\``);
+        }
+    }
+    lines.push("");
+    if (result.issues.length === 0) {
+        lines.push("- Redirect looks correctly configured.");
+    }
+    else {
+        lines.push(...result.issues.map(issueTodo));
+    }
+    lines.push("");
+    return lines;
+}
+export function buildDnsSection(dns) {
+    const lines = ["## DNS", "", `- Hostname: \`${dns.hostname}\``];
+    if (dns.records.a.length > 0) {
+        lines.push(`- A: ${dns.records.a.join(", ")}`);
+    }
+    if (dns.records.aaaa.length > 0) {
+        lines.push(`- AAAA: ${dns.records.aaaa.join(", ")}`);
+    }
+    if (dns.records.cname.length > 0) {
+        lines.push(`- CNAME: ${dns.records.cname.join(", ")}`);
+    }
+    if (dns.records.mx.length > 0) {
+        lines.push(`- MX: ${dns.records.mx.map((entry) => `${entry.exchange} (${entry.priority})`).join(", ")}`);
+    }
+    if (dns.records.ns.length > 0) {
+        lines.push(`- NS: ${dns.records.ns.join(", ")}`);
+    }
+    if (dns.mail.spf) {
+        lines.push(`- SPF: \`${dns.mail.spf}\``);
+    }
+    if (dns.mail.dmarc) {
+        lines.push(`- DMARC: \`${dns.mail.dmarc}\``);
+    }
+    lines.push("");
+    if (dns.issues.length === 0) {
+        lines.push("- No DNS issues found.");
+    }
+    else {
+        lines.push("### Issues", "");
+        lines.push(...dns.issues.map(issueTodo));
+    }
+    lines.push("");
+    return lines;
+}
+export function buildSecurityHeadersSection(result) {
+    const lines = ["## Security headers", "", `- Checked: \`${result.url}\``, ""];
+    if (result.issues.length === 0) {
+        lines.push("- No security header issues found.");
+    }
+    else {
+        lines.push(...result.issues.map(issueTodo));
+    }
+    lines.push("");
+    return lines;
+}
+export function buildRobotsTxtSection(result) {
+    const lines = [
+        "### Robots.txt",
+        "",
+        `- URL: \`${result.url}\``,
+        `- Status: \`${result.status ?? "unreachable"}\``,
+    ];
+    if (result.sitemapUrls.length > 0) {
+        lines.push(`- Sitemaps: ${result.sitemapUrls.map((url) => `\`${url}\``).join(", ")}`);
+    }
+    lines.push("");
+    if (result.issues.length === 0) {
+        lines.push("- No robots.txt issues found.");
+    }
+    else {
+        lines.push(...result.issues.map(issueTodo));
+    }
+    lines.push("");
+    return lines;
+}
+function listSampleUrls(urls, limit = 10) {
+    const lines = urls.slice(0, limit).map((url) => `- \`${url}\``);
+    if (urls.length > limit) {
+        lines.push(`- ...and ${urls.length - limit} more`);
+    }
+    return lines;
+}
+export function buildSitemapSection(result) {
+    const lines = ["### Sitemap", ""];
+    for (const source of result.sources) {
+        lines.push(`- \`${source.url}\`: status \`${source.status ?? "unreachable"}\`, ${source.pageUrls.length} URL(s)`);
+    }
+    lines.push(`- Compared: ${result.sitemapPageUrls.length} sitemap URL(s) vs ${result.crawledUrls.length} crawled URL(s)`);
+    lines.push(`- Mismatch: ${result.mismatchPercent.toFixed(1)}%`);
+    lines.push("");
+    if (result.inSitemapNotCrawled.length > 0) {
+        lines.push("#### In sitemap but not crawled (CRITICAL)", "");
+        lines.push(...listSampleUrls(result.inSitemapNotCrawled));
+        lines.push("");
+    }
+    if (result.crawledNotInSitemap.length > 0) {
+        lines.push("#### Crawled but missing from sitemap (CRITICAL)", "");
+        lines.push(...listSampleUrls(result.crawledNotInSitemap));
+        lines.push("");
+    }
+    if (result.issues.length === 0) {
+        lines.push("- No sitemap issues found.");
+    }
+    else {
+        lines.push(...result.issues.map(issueTodo));
+    }
+    lines.push("");
+    return lines;
+}
+export function buildRobotsAndSitemapSection(robotsTxt, sitemap) {
+    if (!robotsTxt && !sitemap)
+        return [];
+    const lines = ["## Robots.txt & sitemap", ""];
+    if (robotsTxt)
+        lines.push(...buildRobotsTxtSection(robotsTxt));
+    if (sitemap)
+        lines.push(...buildSitemapSection(sitemap));
+    return lines;
+}
+export function buildAgentReadySection(result) {
+    const { findings } = result;
+    const lines = [
+        "## Agent readiness",
+        "",
+        `- Checked: \`${result.url}\``,
+        `- Content Signals: ${findings.robotsTxt.hasContentSignals ? "yes" : "no"}`,
+    ];
+    if (findings.robotsTxt.contentSignals.length > 0) {
+        lines.push(`- Content-Signal values: ${findings.robotsTxt.contentSignals.map((value) => `\`${value}\``).join(", ")}`);
+    }
+    if (findings.robotsTxt.aiBotUserAgents.length > 0) {
+        lines.push(`- AI bot User-agent rules: ${findings.robotsTxt.aiBotUserAgents.map((bot) => `\`${bot}\``).join(", ")}`);
+    }
+    else {
+        lines.push("- AI bot User-agent rules: none");
+    }
+    lines.push(`- llms.txt: \`${findings.llmsTxt.url}\` (status \`${findings.llmsTxt.status ?? "unreachable"}\`)`, `- Markdown negotiation: ${findings.markdownNegotiation.supportsMarkdown ? "yes" : "no"}` +
+        (findings.markdownNegotiation.contentType
+            ? ` (\`${findings.markdownNegotiation.contentType}\`)`
+            : ""), `- Agent Link relations: ${findings.linkHeaders.relations.length > 0
+        ? findings.linkHeaders.relations.map((rel) => `\`${rel}\``).join(", ")
+        : "none"}`);
+    const wellKnownBits = [
+        findings.wellKnown.mcpServerCard ? "MCP Server Card" : null,
+        findings.wellKnown.agentSkills ? "Agent Skills" : null,
+        findings.wellKnown.apiCatalog ? "API Catalog" : null,
+        findings.wellKnown.ard ? "ARD" : null,
+        findings.wellKnown.a2aAgentCard ? "A2A Agent Card" : null,
+    ].filter(Boolean);
+    lines.push(`- Protocol discovery: ${wellKnownBits.length > 0 ? wellKnownBits.join(", ") : "none"}`, "");
+    if (result.issues.length === 0) {
+        lines.push("- No agent readiness issues found.");
+    }
+    else {
+        lines.push(...result.issues.map(issueTodo));
+    }
+    lines.push("");
+    return lines;
+}
+export function countTier1InfraIssues(tier1) {
+    return ((tier1.redirect?.issues.length ?? 0) +
+        (tier1.dns?.issues.length ?? 0) +
+        (tier1.securityHeaders?.issues.length ?? 0) +
+        (tier1.robotsTxt?.issues.length ?? 0) +
+        (tier1.sitemap?.issues.length ?? 0) +
+        (tier1.agentReady?.issues.length ?? 0));
+}
+function buildInfraSummaryParts(tier1, redirectOnly) {
+    const parts = [];
+    if (redirectOnly) {
+        parts.push("redirect-only mode");
+    }
+    if (tier1.redirect) {
+        parts.push(`redirect (${tier1.redirect.issues.length} issue(s))`);
+    }
+    if (tier1.dns) {
+        parts.push(`DNS (${tier1.dns.issues.length} issue(s))`);
+    }
+    if (tier1.securityHeaders) {
+        parts.push(`security headers (${tier1.securityHeaders.issues.length} issue(s))`);
+    }
+    if (tier1.robotsTxt) {
+        parts.push(`robots.txt (${tier1.robotsTxt.issues.length} issue(s))`);
+    }
+    if (tier1.sitemap) {
+        parts.push(`sitemap (${tier1.sitemap.issues.length} issue(s))`);
+    }
+    if (tier1.agentReady) {
+        parts.push(`agent readiness (${tier1.agentReady.issues.length} issue(s))`);
+    }
+    return parts;
+}
+export function buildIssuesSummarySection(tier1, crawlCounts, redirectOnly, performanceChecked = false, performanceIssueCount = 0, performancePageCount = 0) {
+    const lines = ["### Issues summary", ""];
+    const infraParts = buildInfraSummaryParts(tier1, redirectOnly);
+    const infraIssueCount = countTier1InfraIssues(tier1);
+    if (infraParts.length > 0) {
+        lines.push(`- **Infra:** ${infraIssueCount} issue(s) — ${infraParts.join(", ")}`);
+    }
+    if (!redirectOnly) {
+        lines.push(`- **SEO:** ${crawlCounts.seo.issueCount} issue(s) on ${crawlCounts.seo.pageCount} page(s)`, `- **A11y:** ${crawlCounts.a11y.issueCount} issue(s) on ${crawlCounts.a11y.pageCount} page(s) — image alt + static hints`, `- **Best practices:** ${crawlCounts.bestPractices.issueCount} issue(s) on ${crawlCounts.bestPractices.pageCount} page(s) — landmarks, robots, template meta`);
+        if (crawlCounts.security.issueCount > 0) {
+            lines.push(`- **Security:** ${crawlCounts.security.issueCount} finding(s) on ${crawlCounts.security.pageCount} page(s)`);
+        }
+        if (performanceChecked) {
+            lines.push(`- **Performance:** ${performanceIssueCount} issue(s) on ${performancePageCount} page(s)`);
+        }
+        else {
+            lines.push("- **Performance:** not checked");
+        }
+    }
+    else if (infraParts.length === 0) {
+        lines.push("- No issues found.");
+    }
+    lines.push("");
+    return lines;
+}

package/dist/analyze/stack.d.ts

@@ -0,0 +1,33 @@
+import type { DnsCheckResult } from "../checks/dns.js";
+import type { RobotsTxtCheckResult } from "../checks/robots-txt.js";
+import type { SecurityHeadersCheckResult } from "../checks/security-headers.js";
+import { type StackDetection } from "../crawler/stack.js";
+import type { TrackingItem } from "../crawler/schema.js";
+export type StackRecord = {
+    url: string;
+    stack?: {
+        detections: StackDetection[];
+    };
+    tracking: {
+        tagManager: TrackingItem[];
+        analytics: TrackingItem[];
+    };
+};
+export type AggregatedStackDetection = StackDetection & {
+    pageCount: number;
+};
+export type StackProfile = {
+    detections: AggregatedStackDetection[];
+    tracking: {
+        tagManager: TrackingItem[];
+        analytics: TrackingItem[];
+    };
+};
+export declare function aggregateStackFromRecords(records: StackRecord[]): StackProfile;
+export declare function buildStackProfile(records: StackRecord[], options?: {
+    securityHeaders?: SecurityHeadersCheckResult;
+    dns?: DnsCheckResult;
+    robotsTxt?: RobotsTxtCheckResult;
+}): StackProfile;
+export declare function buildStackSection(profile: StackProfile, totalPages: number): string[];
+//# sourceMappingURL=stack.d.ts.map

package/dist/analyze/stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../../src/analyze/stack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,UAAU,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;IACzC,QAAQ,EAAE;QACR,UAAU,EAAE,YAAY,EAAE,CAAC;QAC3B,SAAS,EAAE,YAAY,EAAE,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,cAAc,GAAG;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,wBAAwB,EAAE,CAAC;IACvC,QAAQ,EAAE;QACR,UAAU,EAAE,YAAY,EAAE,CAAC;QAC3B,SAAS,EAAE,YAAY,EAAE,CAAC;KAC3B,CAAC;CACH,CAAC;AAkHF,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,YAAY,CAS9E;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,0BAA0B,CAAC;IAC7C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAC7B,GACL,YAAY,CA2Bd;AAOD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAgErF"}

package/dist/analyze/stack.js

@@ -0,0 +1,188 @@
+import { detectStackFromDns, detectStackFromHeaders, detectStackFromRobots, } from "../crawler/stack.js";
+const TRACKING_PROVIDER_LABELS = {
+    "google-tag-manager": "Google Tag Manager",
+    "google-analytics-ga4": "Google Analytics (GA4)",
+    "google-analytics-ua": "Google Analytics (Universal)",
+    matomo: "Matomo",
+    "facebook-pixel": "Facebook Pixel",
+    plausible: "Plausible",
+};
+function confidenceRank(confidence) {
+    return confidence === "high" ? 2 : confidence === "medium" ? 1 : 0;
+}
+function mergeConfidence(a, b) {
+    return confidenceRank(a) >= confidenceRank(b) ? a : b;
+}
+function dedupeTracking(items) {
+    const seen = new Set();
+    return items.filter((item) => {
+        const key = `${item.provider}:${item.id}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function aggregateTracking(records) {
+    const tagManager = [];
+    const analytics = [];
+    for (const record of records) {
+        tagManager.push(...record.tracking.tagManager);
+        analytics.push(...record.tracking.analytics);
+    }
+    return {
+        tagManager: dedupeTracking(tagManager),
+        analytics: dedupeTracking(analytics),
+    };
+}
+const STACK_CATEGORY_ORDER = ["Platform", "Framework", "CMS", "Search", "Hosting", "CDN", "Other"];
+function isCuratedStackDetection(detection) {
+    return detection.detector === "flightcheck-v1";
+}
+function filterCuratedDetections(detections) {
+    return detections.filter(isCuratedStackDetection);
+}
+function primaryCategory(detection) {
+    return detection.categories[0] ?? "Other";
+}
+function categorySortKey(category) {
+    const index = STACK_CATEGORY_ORDER.indexOf(category);
+    return index === -1 ? STACK_CATEGORY_ORDER.length : index;
+}
+function aggregateDetections(pageDetections, originDetections) {
+    const merged = new Map();
+    const add = (detection, pageUrl) => {
+        const key = detection.name;
+        const existing = merged.get(key);
+        if (!existing) {
+            merged.set(key, {
+                ...detection,
+                evidence: [...detection.evidence],
+                pageCount: pageUrl ? 1 : 0,
+                pages: new Set(pageUrl ? [pageUrl] : []),
+            });
+            return;
+        }
+        existing.evidence = [...new Set([...existing.evidence, ...detection.evidence])];
+        existing.confidence = mergeConfidence(existing.confidence, detection.confidence);
+        existing.categories = [...new Set([...existing.categories, ...detection.categories])];
+        if (!existing.website && detection.website)
+            existing.website = detection.website;
+        if (!existing.version && detection.version)
+            existing.version = detection.version;
+        if (pageUrl)
+            existing.pages.add(pageUrl);
+    };
+    for (const { url, detections } of pageDetections) {
+        for (const detection of filterCuratedDetections(detections)) {
+            add(detection, url);
+        }
+    }
+    for (const detection of originDetections) {
+        add(detection);
+    }
+    return [...merged.values()]
+        .map(({ pages, ...detection }) => ({
+        ...detection,
+        pageCount: pages.size,
+    }))
+        .sort((a, b) => {
+        const categoryDiff = categorySortKey(primaryCategory(a)) - categorySortKey(primaryCategory(b));
+        if (categoryDiff !== 0)
+            return categoryDiff;
+        return a.name.localeCompare(b.name);
+    });
+}
+export function aggregateStackFromRecords(records) {
+    const pageDetections = records
+        .filter((record) => record.stack?.detections?.length)
+        .map((record) => ({ url: record.url, detections: record.stack.detections }));
+    return {
+        detections: aggregateDetections(pageDetections, []),
+        tracking: aggregateTracking(records),
+    };
+}
+export function buildStackProfile(records, options = {}) {
+    const pageDetections = records
+        .filter((record) => record.stack?.detections?.length)
+        .map((record) => ({ url: record.url, detections: record.stack.detections }));
+    const originDetections = [];
+    if (options.securityHeaders) {
+        originDetections.push(...detectStackFromHeaders(options.securityHeaders.headers));
+    }
+    if (options.dns) {
+        originDetections.push(...detectStackFromDns({
+            cname: options.dns.records.cname,
+            ns: options.dns.records.ns,
+            mx: options.dns.records.mx,
+            txt: options.dns.records.txt,
+        }));
+    }
+    if (options.robotsTxt?.body) {
+        originDetections.push(...detectStackFromRobots(options.robotsTxt.body));
+    }
+    return {
+        detections: aggregateDetections(pageDetections, originDetections),
+        tracking: aggregateTracking(records),
+    };
+}
+function formatTrackingItem(item) {
+    const label = TRACKING_PROVIDER_LABELS[item.provider] ?? item.provider;
+    return item.id ? `${label}: \`${item.id}\`` : label;
+}
+export function buildStackSection(profile, totalPages) {
+    const hasDetections = profile.detections.length > 0;
+    const hasTracking = profile.tracking.tagManager.length > 0 || profile.tracking.analytics.length > 0;
+    if (!hasDetections && !hasTracking) {
+        return [];
+    }
+    const lines = ["## Stack", ""];
+    if (hasDetections) {
+        const byCategory = new Map();
+        for (const detection of profile.detections) {
+            const category = primaryCategory(detection);
+            const list = byCategory.get(category) ?? [];
+            list.push(detection);
+            byCategory.set(category, list);
+        }
+        for (const [category, items] of [...byCategory.entries()].sort(([a], [b]) => categorySortKey(a) - categorySortKey(b))) {
+            lines.push(`### ${category}`, "");
+            for (const item of items) {
+                const scope = item.pageCount > 0
+                    ? item.pageCount === totalPages
+                        ? "site-wide"
+                        : `${item.pageCount}/${totalPages} page(s)`
+                    : "origin";
+                const versionSuffix = item.version ? `, v${item.version}` : "";
+                lines.push(`- **${item.name}** (${item.confidence}${versionSuffix}, ${scope})`);
+                for (const evidence of item.evidence.slice(0, 3)) {
+                    lines.push(`  - ${evidence}`);
+                }
+                if (item.evidence.length > 3) {
+                    lines.push(`  - …and ${item.evidence.length - 3} more signal(s)`);
+                }
+                if (item.website) {
+                    lines.push(`  - website: ${item.website}`);
+                }
+            }
+            lines.push("");
+        }
+    }
+    if (hasTracking) {
+        lines.push("### Tracking (flightcheck crawl)", "");
+        if (profile.tracking.tagManager.length > 0) {
+            lines.push("- Tag managers:");
+            for (const item of profile.tracking.tagManager) {
+                lines.push(`  - ${formatTrackingItem(item)}`);
+            }
+        }
+        if (profile.tracking.analytics.length > 0) {
+            lines.push("- Analytics & pixels:");
+            for (const item of profile.tracking.analytics) {
+                lines.push(`  - ${formatTrackingItem(item)}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}

package/dist/analyze/structuredReport.d.ts

@@ -0,0 +1,62 @@
+import type { CheckIssueSeverity } from "../checks/issues.js";
+import { type BuildMarkdownOptions, type ReportRecord, type Tier1ReportData } from "./report.js";
+export declare const FLIGHTCHECK_REPORT_VERSION: 1;
+export type FindingSeverity = CheckIssueSeverity;
+export type FindingCategory = "infra" | "seo" | "a11y" | "best-practices" | "security" | "performance";
+export type FindingScope = "site-wide" | "template" | "page" | "origin";
+export type ReportStackEntry = {
+    name: string;
+    categories: string[];
+    confidence: string;
+    evidence: string[];
+    pageCount?: number;
+};
+export type ReportFinding = {
+    id: string;
+    severity: FindingSeverity;
+    category: FindingCategory;
+    scope: FindingScope;
+    title: string;
+    message: string;
+    template?: string;
+    urls?: string[];
+    count?: number;
+};
+export type ReportReviewPage = {
+    url: string;
+    status: number | null;
+    reason: string;
+};
+export type FlightcheckReportAnalysis = {
+    pagesAnalyzed: number;
+    pagesWithIssues: number;
+    findingCounts: Record<FindingSeverity, number>;
+    stack: ReportStackEntry[];
+    templates: string[];
+    dns?: {
+        hostname: string;
+        summary: string[];
+    };
+    redirect?: {
+        url: string;
+        status: number | null;
+        location: string | null;
+        issueCount: number;
+    };
+    reviewPages: ReportReviewPage[];
+};
+export type FlightcheckReport = {
+    version: typeof FLIGHTCHECK_REPORT_VERSION;
+    generatedAt: string;
+    source: string;
+    redirectOnly: boolean;
+    analysis: FlightcheckReportAnalysis;
+    findings: ReportFinding[];
+};
+export type BuildStructuredReportOptions = BuildMarkdownOptions & {
+    generatedAt?: string;
+};
+export declare function buildStructuredReport(sourcePath: string, records: ReportRecord[], tier1?: Tier1ReportData, options?: BuildStructuredReportOptions): Promise<FlightcheckReport>;
+/** Human-friendly Markdown rendered from the structured report (single source of truth). */
+export declare function renderReportMarkdown(report: FlightcheckReport): string;
+//# sourceMappingURL=structuredReport.d.ts.map

package/dist/analyze/structuredReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredReport.d.ts","sourceRoot":"","sources":["../../src/analyze/structuredReport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,0BAA0B,EAAG,CAAU,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AACjD,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,KAAK,GACL,MAAM,GACN,gBAAgB,GAChB,UAAU,GACV,aAAa,CAAC;AAClB,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAC/C,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9C,QAAQ,CAAC,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,OAAO,0BAA0B,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,yBAAyB,CAAC;IACpC,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAidF,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,GAAE,eAAoB,EAC3B,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,iBAAiB,CAAC,CAW5B;AAgCD,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAqFtE"}