periderm-cli 0.1.0

package/dist/scanner/index.js

@@ -0,0 +1,100 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { walk } from "./walk.js";
+import { parseSource } from "./ast.js";
+import { runChecks, PER_FILE_CHECK_COUNT } from "./checks.js";
+import { runRepoChecks, REPO_WIDE_CHECK_COUNT } from "./repo-checks.js";
+import { runPolicyChecks, POLICY_CHECK_COUNT } from "./policy-checks.js";
+import { runSeoChecks, SEO_CHECK_COUNT } from "./seo-checks.js";
+import { computeScores, computeVerdict } from "../report/verdict.js";
+import { renderMarkdown } from "../report/markdown.js";
+import { mapWithProgress } from "./progress.js";
+export { formatScanPath } from "./progress.js";
+export async function scan(root, options = {}) {
+    const { onProgress } = options;
+    const findings = [];
+    onProgress?.({ type: "discovering" });
+    const files = await walk(root);
+    onProgress?.({ type: "discovered", total: files.length });
+    const estimatedChecks = files.length * PER_FILE_CHECK_COUNT +
+        REPO_WIDE_CHECK_COUNT +
+        POLICY_CHECK_COUNT +
+        SEO_CHECK_COUNT;
+    let checksRun = 0;
+    const bumpChecks = (n) => {
+        checksRun += n;
+        onProgress?.({ type: "checks", current: checksRun, total: estimatedChecks });
+    };
+    let policySignalsChecked = 0;
+    await mapWithProgress(files, 6, async (abs) => {
+        let src;
+        try {
+            src = await fs.readFile(abs, "utf8");
+        }
+        catch {
+            bumpChecks(PER_FILE_CHECK_COUNT);
+            return;
+        }
+        if (src.length > 500_000) {
+            bumpChecks(PER_FILE_CHECK_COUNT);
+            return;
+        }
+        const rel = path.relative(root, abs);
+        const ast = parseSource(src, rel);
+        findings.push(...runChecks(src, rel, ast));
+        bumpChecks(PER_FILE_CHECK_COUNT);
+    }, (_abs, completed, total) => {
+        const rel = path.relative(root, _abs);
+        onProgress?.({ type: "file", file: rel, index: completed, total });
+    });
+    onProgress?.({ type: "phase", label: "Running repo-wide checks…" });
+    findings.push(...(await runRepoChecks(root, files)));
+    bumpChecks(REPO_WIDE_CHECK_COUNT);
+    onProgress?.({ type: "phase", label: "Cross-referencing privacy policy vs codebase…" });
+    const policyFindings = await runPolicyChecks(root, files);
+    findings.push(...policyFindings);
+    policySignalsChecked = policyFindings.length > 0 ? 12 : 8;
+    bumpChecks(POLICY_CHECK_COUNT);
+    onProgress?.({ type: "phase", label: "Checking SEO & social meta…" });
+    findings.push(...(await runSeoChecks(root, files)));
+    bumpChecks(SEO_CHECK_COUNT);
+    onProgress?.({ type: "phase", label: "Computing launch verdict…" });
+    const meta = {
+        perFileCheckCount: PER_FILE_CHECK_COUNT,
+        repoWideCheckCount: REPO_WIDE_CHECK_COUNT,
+        seoCheckCount: SEO_CHECK_COUNT,
+        policySignalsChecked,
+        totalChecksRun: checksRun,
+    };
+    const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    const scores = computeScores(findings);
+    const { score, verdict } = computeVerdict(counts, scores.confidence);
+    const projectName = path.basename(root);
+    const scannedAt = new Date().toISOString();
+    const markdown = renderMarkdown({
+        projectName,
+        scannedAt,
+        findings,
+        counts,
+        score,
+        scores,
+        verdict,
+        filesScanned: files.length,
+        markdown: "",
+        meta,
+    });
+    return {
+        projectName,
+        scannedAt,
+        filesScanned: files.length,
+        findings,
+        counts,
+        score,
+        scores,
+        verdict,
+        markdown,
+        meta,
+    };
+}

package/dist/scanner/policy-checks.js

@@ -0,0 +1,134 @@
+/**
+ * Cross-reference privacy/legal copy against what the codebase actually does.
+ * Catches the FTC-class failure mode: policy says one thing, app does another.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+async function readMaybe(p) {
+    try {
+        return await fs.readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Signals that user data is sent to trackers, ad networks, or data brokers. */
+const TRACKING_IN_CODE = [
+    [/gtag\s*\(|googletagmanager|google-analytics|GA_MEASUREMENT_ID|G-[A-Z0-9]{6,}/i, "Google Analytics / gtag"],
+    [/fbq\s*\(|facebook\.net\/en_US\/fbevents|connect\.facebook\.net/i, "Meta / Facebook Pixel"],
+    [/posthog\.(?:capture|init)|import\s+posthog/i, "PostHog analytics"],
+    [/mixpanel\.(?:track|init)|from\s+['"]mixpanel/i, "Mixpanel"],
+    [/analytics\.(?:track|page)|segment\.(?:track|page)|@segment\//i, "Segment analytics"],
+    [/amplitude\.(?:track|init)|@amplitude\//i, "Amplitude"],
+    [/hotjar|hj\s*\(|clarity\.ms|fullstory|logrocket/i, "Session recording / heatmap tool"],
+    [/doubleclick|googlesyndication|googleadservices|ads\.twitter|tiktok.*track/i, "Ad / retargeting network"],
+    [/linkedin\.com\/px|snap\.licdn|taboola|outbrain|criteo/i, "Ad / retargeting pixel"],
+    [/plausible\(|umami\.track|heap\.(?:track|load)/i, "Analytics SDK"],
+];
+/** Strong privacy promises that contradict the signals above. */
+const PRIVACY_PROMISES = [
+    [/(?:do|does|will|shall)\s+not\s+(?:share|sell|disclose|transfer)/i, "promises not to share/sell/disclose data"],
+    [/never\s+(?:share|sell|disclose|transfer)/i, "promises never to share/sell data"],
+    [/(?:remain|stays?|keeping?|keep)\s+(?:private|confidential)/i, "claims user data stays private"],
+    [/not\s+(?:shared|sold|disclosed|transferred)\s+(?:with|to)\s+third/i, "denies third-party sharing"],
+    [/(?:no|without)\s+third[- ]party\s+(?:sharing|access|tracking|data)/i, "denies third-party tracking/sharing"],
+    [/(?:do|does)\s+not\s+(?:use|employ|utilize)\s+(?:tracking|analytics|advertising|ad\s)/i, "denies use of tracking/analytics/ads"],
+    [/information\s+(?:will|shall)\s+(?:remain|stay)\s+private/i, "claims information will remain private"],
+    [/(?:personal\s+information|user\s+data).{0,40}(?:is\s+not|are\s+not|will\s+not\s+be)\s+sold/i, "claims personal data is not sold"],
+    [/(?:only|solely)\s+(?:for|to)\s+(?:provide|operate|improve)\s+(?:the\s+)?(?:service|app|site)/i, "claims data is used only to provide the service"],
+    [/(?:do|does)\s+not\s+(?:use|set)\s+cookies?\s+(?:for|to)\s+(?:track|advertis|market)/i, "denies tracking/ad cookies"],
+    [/(?:no|without)\s+(?:advertising|marketing)\s+cookies?/i, "denies advertising cookies"],
+];
+const COOKIE_TRACKING_IN_CODE = [
+    [/document\.cookie\s*[+=]|cookies?\.set\s*\(/i, "sets cookies in JavaScript"],
+    [/localStorage\.setItem\s*\(\s*['"][^'"]*(?:track|analytics|pixel|utm|session|user)/i, "persists tracking identifiers in localStorage"],
+    [/sessionStorage\.setItem\s*\(\s*['"][^'"]*(?:track|analytics|pixel|utm|session|user)/i, "persists tracking identifiers in sessionStorage"],
+];
+const TRACKING_DEPS = /posthog|mixpanel|segment|amplitude|google-analytics|@vercel\/analytics|plausible|heap-js|hotjar/i;
+export const POLICY_CHECK_COUNT = 2;
+export async function runPolicyChecks(root, files) {
+    const out = [];
+    const relFiles = files.map((f) => path.relative(root, f));
+    const legalPaths = relFiles.filter((f) => /(?:^|\/)routes\/.*(?:privacy|terms|cookie|policy|legal|compliance|eula|tos)/i.test(f)
+        || /(?:privacy|terms|cookie|policy|legal|compliance|eula|tos).*\.(?:tsx|jsx|md|html)$/i.test(path.basename(f)));
+    if (legalPaths.length === 0)
+        return out;
+    let legalText = "";
+    for (const rel of legalPaths) {
+        const content = await readMaybe(path.join(root, rel));
+        if (content)
+            legalText += `\n${content}`;
+    }
+    if (!legalText.trim())
+        return out;
+    const legalLower = legalText.toLowerCase();
+    // Collect what the codebase actually does
+    const codeSignals = new Map(); // label -> first file
+    const pkgRaw = await readMaybe(path.join(root, "package.json"));
+    if (pkgRaw && TRACKING_DEPS.test(pkgRaw)) {
+        codeSignals.set("tracking dependency in package.json", "package.json");
+    }
+    for (const rel of relFiles) {
+        if (!/\.(tsx|jsx|ts|js|html)$/.test(rel))
+            continue;
+        if (/node_modules|\.periderm|dist\/|build\//.test(rel))
+            continue;
+        const content = await readMaybe(path.join(root, rel));
+        if (!content)
+            continue;
+        for (const [re, label] of TRACKING_IN_CODE) {
+            if (re.test(content) && !codeSignals.has(label)) {
+                codeSignals.set(label, rel);
+            }
+        }
+        for (const [re, label] of COOKIE_TRACKING_IN_CODE) {
+            if (re.test(content) && !codeSignals.has(label)) {
+                codeSignals.set(label, rel);
+            }
+        }
+    }
+    if (codeSignals.size === 0)
+        return out;
+    // Flag outright contradictions: policy promises privacy, code sends data to trackers
+    const brokenPromises = [];
+    for (const [re, claim] of PRIVACY_PROMISES) {
+        if (re.test(legalLower))
+            brokenPromises.push(claim);
+    }
+    if (brokenPromises.length > 0) {
+        const trackingList = [...codeSignals.entries()]
+            .map(([label, file]) => `${label} (${file})`)
+            .join("; ");
+        const policyFile = legalPaths[0];
+        out.push({
+            id: "policy-code-mismatch",
+            category: "Legal & Compliance",
+            severity: "critical",
+            file: policyFile,
+            line: 1,
+            message: "Privacy policy contradicts what the codebase actually does.",
+            why: "Regulators (FTC, GDPR authorities) treat this as deceptive practice — saying data stays private while sending it to ad/analytics platforms has resulted in major fines and consent decrees.",
+            fix: "Either remove the tracking/ad integrations from your code, or rewrite the policy to accurately disclose every third party that receives user data, why, and how users can opt out.",
+            aiPrompt: `The privacy policy in ${policyFile} ${brokenPromises[0]}, but the codebase includes: ${trackingList}. ` +
+                `Audit every tracking/ad SDK, list them explicitly in the privacy policy, or remove them. ` +
+                `Do not leave contradictory language — this is an FTC enforcement pattern.`,
+        });
+    }
+    // Policy denies analytics entirely but code/package uses it (even without strong "never share" wording)
+    const deniesAnalytics = /(?:do|does)\s+not\s+(?:use|collect|employ).*analytics|no\s+analytics|without\s+analytics/i.test(legalLower);
+    if (deniesAnalytics && codeSignals.size > 0) {
+        out.push({
+            id: "policy-denies-analytics",
+            category: "Legal & Compliance",
+            severity: "critical",
+            file: legalPaths[0],
+            line: 1,
+            message: "Privacy policy denies analytics/tracking but the codebase includes tracking code.",
+            why: "Claiming 'no analytics' while running PostHog, GA, Meta Pixel, etc. is exactly the kind of mismatch regulators prosecute.",
+            fix: "Remove the 'no analytics' claim and document each tool, what it collects, and how to opt out — or remove the tracking code.",
+            aiPrompt: `In ${legalPaths[0]}, the policy denies analytics/tracking. ` +
+                `Found in code: ${[...codeSignals.keys()].join(", ")}. Align the policy with reality or remove the SDKs.`,
+        });
+    }
+    return out;
+}

package/dist/scanner/progress.js

@@ -0,0 +1,26 @@
+export function formatScanPath(rel, max = 52) {
+    if (rel.length <= max)
+        return rel;
+    const tail = rel.slice(-(max - 1));
+    return `…${tail}`;
+}
+/** Run async work with bounded concurrency and per-item progress. */
+export async function mapWithProgress(items, concurrency, fn, onItem) {
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    let completed = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex++;
+            const item = items[index];
+            results[index] = await fn(item, index);
+            completed += 1;
+            onItem?.(item, completed, items.length);
+        }
+    }
+    const workers = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    return results;
+}

package/dist/scanner/repo-checks.js

@@ -0,0 +1,197 @@
+/**
+ * Repo-wide checks: things the per-file pass can't see.
+ * No node_modules access — the walk() already filters them out.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readMaybe(p) {
+    try {
+        return await fs.readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export const REPO_WIDE_CHECK_COUNT = 9;
+export async function runRepoChecks(root, _files) {
+    const out = [];
+    const has = async (rel) => exists(path.join(root, rel));
+    // README
+    if (!(await has("README.md")) && !(await has("readme.md"))) {
+        out.push({
+            id: "missing-readme",
+            category: "Deployment & Testing Readiness",
+            severity: "medium",
+            file: "README.md", line: 1,
+            message: "README.md is missing.",
+            why: "New contributors and your future self can't tell what the project is or how to run it.",
+            fix: "Add a README with a one-line description, install, run, and deploy commands.",
+            aiPrompt: "Generate a concise README.md for this project: one-line description, prerequisites, install, dev, build, and deploy commands.",
+        });
+    }
+    // .env.example
+    if (!(await has(".env.example"))) {
+        out.push({
+            id: "missing-env-example",
+            category: "Deployment & Testing Readiness",
+            severity: "medium",
+            file: ".env.example", line: 1,
+            message: ".env.example is missing.",
+            why: "Anyone cloning the repo has to guess which env vars are required.",
+            fix: "Create a .env.example listing every env var with a placeholder value (no secrets).",
+            aiPrompt: "Scan the codebase for process.env.* and import.meta.env.* reads and produce a .env.example file listing every variable found with placeholder values.",
+        });
+    }
+    // public dir favicon
+    const pkgRaw = await readMaybe(path.join(root, "package.json"));
+    const looksLikeWeb = pkgRaw ? /react|vite|next|tanstack|svelte|vue/.test(pkgRaw) : false;
+    // Detect project type based on name/description to avoid false positives.
+    // We do NOT rely on "private": true because many SaaS landing pages are in private repos.
+    let isInternalAdmin = false;
+    let isCustomerPortal = false;
+    const evaluateName = (str) => {
+        if (/(?:^|_|-|\b)(admin|internal|backoffice|cms)(?:_|-|\b|$)/i.test(str))
+            isInternalAdmin = true;
+        if (/(?:^|_|-|\b)(portal|dashboard)(?:_|-|\b|$)/i.test(str))
+            isCustomerPortal = true;
+    };
+    if (pkgRaw) {
+        try {
+            const pkg = JSON.parse(pkgRaw);
+            evaluateName(pkg.name || "");
+            evaluateName(pkg.description || "");
+        }
+        catch { }
+    }
+    if (!isInternalAdmin && !isCustomerPortal) {
+        evaluateName(path.basename(root));
+    }
+    if (looksLikeWeb) {
+        const favicons = ["public/favicon.ico", "public/favicon.svg", "src/favicon.ico"];
+        let hasFavicon = false;
+        for (const p of favicons)
+            if (await has(p)) {
+                hasFavicon = true;
+                break;
+            }
+        if (!hasFavicon) {
+            out.push({
+                id: "missing-favicon",
+                category: "Polish & Embarrassment Risks",
+                severity: "medium",
+                file: "public/favicon.ico", line: 1,
+                message: "No favicon found.",
+                why: "Without a favicon the browser tab shows a generic blank icon. Looks unfinished.",
+                fix: "Add a favicon (favicon.ico or .svg) to /public and reference it from your root layout head.",
+                aiPrompt: "Add a favicon.svg to /public and a <link rel=\"icon\"> tag in the root layout's head().",
+            });
+        }
+        if (!isInternalAdmin && !isCustomerPortal) {
+            if (!(await has("public/robots.txt"))) {
+                out.push({
+                    id: "missing-robots",
+                    category: "SEO & Discoverability",
+                    severity: "medium",
+                    file: "public/robots.txt", line: 1,
+                    message: "robots.txt is missing.",
+                    why: "Search engines may crawl pages you don't want indexed, or miss pages you do.",
+                    fix: "Add a public/robots.txt with at minimum: User-agent: *  Allow: /  Sitemap: https://your-domain/sitemap.xml",
+                    aiPrompt: "Create public/robots.txt with sane defaults: allow all, and a Sitemap line pointing at /sitemap.xml.",
+                });
+            }
+        }
+        if (!isInternalAdmin) {
+            const legalFilePaths = _files.filter(f => /terms|privacy|cookie|policy|legal|compliance|eula|tos/i.test(path.basename(f)));
+            if (legalFilePaths.length === 0) {
+                out.push({
+                    id: "missing-legal-docs",
+                    category: "Legal & Compliance",
+                    severity: "critical",
+                    file: "root", line: 1,
+                    message: "Missing Documents: Privacy Policy, Terms of Service completely absent.",
+                    why: "Running a web app handling user data without legal policies creates massive liability.",
+                    fix: "Create a Terms of Service and Privacy Policy, and link them in your footer.",
+                    aiPrompt: "Generate a standard Privacy Policy and Terms of Service route for this application.",
+                });
+            }
+            else if (pkgRaw) {
+                let combinedSource = pkgRaw;
+                for (const abs of _files) {
+                    const rel = path.relative(root, abs);
+                    if (!/\.(tsx|jsx|ts|js)$/.test(rel))
+                        continue;
+                    const chunk = await readMaybe(abs);
+                    if (chunk)
+                        combinedSource += chunk;
+                }
+                const hasAuth = /supabase|clerk|firebase|next-auth|auth0|createClient.*auth/i.test(combinedSource);
+                const hasPayments = /stripe|braintree|paypal|lemonsqueezy/i.test(combinedSource);
+                const hasAnalytics = /posthog|mixpanel|segment|amplitude|google-analytics|gtag\s*\(|fbq\s*\(|plausible|hotjar/i.test(combinedSource);
+                let combinedLegalContent = "";
+                for (const p of legalFilePaths) {
+                    const content = await readMaybe(p);
+                    if (content)
+                        combinedLegalContent += content.toLowerCase();
+                }
+                if (hasAuth && !/account|email|password|authentication|login/i.test(combinedLegalContent)) {
+                    out.push({
+                        id: "incomplete-legal-auth",
+                        category: "Legal & Compliance",
+                        severity: "high",
+                        file: path.basename(legalFilePaths[0]), line: 1,
+                        message: "Privacy Policy does not mention User Accounts or Authentication.",
+                        why: "The app uses authentication dependencies, but the legal pages do not disclose the collection of account data (e.g. emails).",
+                        fix: "Update your Privacy Policy to disclose what user data is collected upon account creation and how it is protected.",
+                        aiPrompt: "Update the Privacy Policy to include a section about User Accounts, disclosing the collection of email addresses.",
+                    });
+                }
+                if (hasPayments && !/payment|stripe|credit card|billing/i.test(combinedLegalContent)) {
+                    out.push({
+                        id: "incomplete-legal-payments",
+                        category: "Legal & Compliance",
+                        severity: "high",
+                        file: path.basename(legalFilePaths[0]), line: 1,
+                        message: "Privacy Policy does not mention Payments or Billing.",
+                        why: "The app uses payment processing dependencies, but the legal pages do not disclose the handling of financial data.",
+                        fix: "Update your Privacy Policy to disclose that payment information is collected and processed by third-party providers.",
+                        aiPrompt: "Update the Privacy Policy to include a section about Payments, disclosing that payment data is handled securely by a processor.",
+                    });
+                }
+                if (hasAnalytics && !/analytic|tracking|cookie|mixpanel|posthog/i.test(combinedLegalContent)) {
+                    out.push({
+                        id: "incomplete-legal-analytics",
+                        category: "Legal & Compliance",
+                        severity: "high",
+                        file: path.basename(legalFilePaths[0]), line: 1,
+                        message: "Privacy Policy does not mention Analytics or Tracking.",
+                        why: "The app uses analytics dependencies, but the legal pages do not disclose tracking, cookies, or telemetry.",
+                        fix: "Update your Privacy Policy to disclose the use of analytics tools and tracking cookies.",
+                        aiPrompt: "Update the Privacy Policy to include a section about Analytics and Cookies, disclosing the use of tracking telemetry.",
+                    });
+                }
+                if (!/gdpr|ccpa|california consumer|general data protection/i.test(combinedLegalContent)) {
+                    out.push({
+                        id: "missing-legal-compliance",
+                        category: "Legal & Compliance",
+                        severity: "high",
+                        file: path.basename(legalFilePaths[0]), line: 1,
+                        message: "Privacy Policy missing GDPR / CCPA compliance wording.",
+                        why: "Failing to include required clauses for EU/CA users can result in severe FTC/regulatory fines and liabilities.",
+                        fix: "Add sections explicitly covering GDPR and CCPA rights (right to delete, right to access).",
+                        aiPrompt: "Update the Privacy Policy to include standard GDPR and CCPA data rights clauses.",
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/scanner/seo-checks.js

@@ -0,0 +1,167 @@
+/**
+ * SEO & social sharing checks — things that make links look broken on Twitter/Slack/iMessage.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readMaybe(p) {
+    try {
+        return await fs.readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function isMarketingRoute(rel) {
+    if (!/routes\//.test(rel))
+        return false;
+    if (/_authenticated|admin|dashboard|api\//.test(rel))
+        return false;
+    return /(?:^|\/)index\.(tsx|jsx)$/.test(rel)
+        || /routes\/(?:index|__root)\.(tsx|jsx)$/.test(rel)
+        || !/_authenticated|admin/.test(rel);
+}
+export const SEO_CHECK_COUNT = 5;
+export async function runSeoChecks(root, files) {
+    const out = [];
+    const relFiles = files.map((f) => path.relative(root, f));
+    const pkgRaw = await readMaybe(path.join(root, "package.json"));
+    const looksLikeWeb = pkgRaw ? /react|vite|next|tanstack|svelte|vue/.test(pkgRaw) : false;
+    if (!looksLikeWeb)
+        return out;
+    const routeSources = [];
+    for (const rel of relFiles) {
+        if (!/routes\/.*\.(tsx|jsx)$/.test(rel))
+            continue;
+        const content = await readMaybe(path.join(root, rel));
+        if (content)
+            routeSources.push({ rel, content });
+    }
+    // ── og:image on public-facing routes ──────────────────────────────────
+    const socialMetaSource = await readMaybe(path.join(root, "src/lib/social-meta.ts"))
+        ?? await readMaybe(path.join(root, "src/lib/social-meta.tsx"));
+    const hasOgImageMeta = (content) => /og:image|property:\s*["']og:image["']/i.test(content)
+        || (/socialMeta|social-meta/.test(content) && !!socialMetaSource && /og:image/.test(socialMetaSource));
+    const marketingRoutes = routeSources.filter((r) => isMarketingRoute(r.rel));
+    const routesMissingOgImage = marketingRoutes.filter((r) => !hasOgImageMeta(r.content));
+    if (routesMissingOgImage.length > 0) {
+        const names = routesMissingOgImage.map((r) => r.rel).slice(0, 3).join(", ");
+        out.push({
+            id: "missing-og-image",
+            category: "SEO & Discoverability",
+            severity: "medium",
+            file: routesMissingOgImage[0].rel,
+            line: 1,
+            message: "Public route(s) missing og:image — link previews will show no image.",
+            why: "When someone shares your URL on Slack, Twitter, or iMessage, it looks broken without a preview image. First impressions matter.",
+            fix: "Add a 1200×630 og:image (PNG or JPG) to /public, then add { property: \"og:image\", content: \"https://your-domain.com/og.png\" } to the route head().",
+            aiPrompt: `In ${names}, add og:image and twitter:card meta tags pointing at a 1200×630 social preview image in /public.`,
+        });
+    }
+    // ── sitemap ───────────────────────────────────────────────────────────
+    const hasSitemap = (await exists(path.join(root, "public/sitemap.xml")))
+        || relFiles.some((f) => /sitemap\.(?:xml|ts|tsx|js)$/i.test(f));
+    const hasRobots = await exists(path.join(root, "public/robots.txt"));
+    if (hasRobots && !hasSitemap) {
+        const robots = await readMaybe(path.join(root, "public/robots.txt"));
+        if (robots && /sitemap/i.test(robots)) {
+            out.push({
+                id: "missing-sitemap",
+                category: "SEO & Discoverability",
+                severity: "medium",
+                file: "public/sitemap.xml",
+                line: 1,
+                message: "robots.txt references a sitemap but no sitemap file was found.",
+                why: "Search engines expect the sitemap URL in robots.txt to actually exist.",
+                fix: "Generate public/sitemap.xml listing your public routes, or remove the Sitemap line from robots.txt until you have one.",
+                aiPrompt: "Create public/sitemap.xml with URLs for all public marketing pages, or fix the robots.txt Sitemap URL.",
+            });
+        }
+        else if (marketingRoutes.length > 0) {
+            out.push({
+                id: "missing-sitemap",
+                category: "SEO & Discoverability",
+                severity: "low",
+                file: "public/sitemap.xml",
+                line: 1,
+                message: "No sitemap.xml found for a public-facing site.",
+                why: "Search engines discover pages faster with a sitemap. Without one, new pages may index slowly or not at all.",
+                fix: "Add public/sitemap.xml listing your public routes.",
+                aiPrompt: "Create public/sitemap.xml listing the landing page, docs, privacy, and terms routes.",
+            });
+        }
+    }
+    // ── broken asset references in head/links ───────────────────────────
+    const assetRefs = [];
+    for (const { rel, content } of routeSources) {
+        const re = /href:\s*["'](\/[^"']+\.(?:png|jpg|jpeg|webp|svg|ico))["']/gi;
+        let m;
+        while ((m = re.exec(content)))
+            assetRefs.push(m[1]);
+    }
+    for (const asset of [...new Set(assetRefs)]) {
+        const candidates = [
+            path.join(root, "public", asset.replace(/^\//, "")),
+            path.join(root, asset.replace(/^\//, "")),
+        ];
+        let found = false;
+        for (const c of candidates) {
+            if (await exists(c)) {
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            out.push({
+                id: "missing-seo-asset",
+                category: "SEO & Discoverability",
+                severity: "medium",
+                file: routeSources.find((r) => r.content.includes(asset))?.rel ?? "routes",
+                line: 1,
+                message: `Head/link references ${asset} but the file does not exist.`,
+                why: "Broken apple-touch-icon or og:image URLs produce 404s and broken previews in browsers and social crawlers.",
+                fix: `Add the missing file to /public${asset} or remove the reference.`,
+                aiPrompt: `Create ${asset} in /public or remove the broken link reference from the route head().`,
+            });
+        }
+    }
+    // ── duplicate page titles ─────────────────────────────────────────────
+    const titles = new Map();
+    for (const { rel, content } of routeSources) {
+        const re = /(?:title:\s*["']([^"']+)["']|property:\s*["']og:title["'],\s*content:\s*["']([^"']+)["'])/g;
+        let m;
+        while ((m = re.exec(content))) {
+            const title = (m[1] || m[2] || "").trim();
+            if (!title || title.length < 8)
+                continue;
+            if (!titles.has(title))
+                titles.set(title, []);
+            titles.get(title).push(rel);
+        }
+    }
+    for (const [title, routes] of titles) {
+        const uniqueRoutes = [...new Set(routes)];
+        if (uniqueRoutes.length > 1) {
+            out.push({
+                id: "duplicate-page-title",
+                category: "SEO & Discoverability",
+                severity: "low",
+                file: uniqueRoutes[0],
+                line: 1,
+                message: `Duplicate page title "${title.slice(0, 50)}${title.length > 50 ? "…" : ""}" on ${uniqueRoutes.length} routes.`,
+                why: "Duplicate titles confuse search engines and make browser tabs indistinguishable.",
+                fix: "Give each route a unique, descriptive title in its head() meta.",
+                aiPrompt: `Routes ${uniqueRoutes.join(", ")} share the same title. Give each a unique title describing that page.`,
+            });
+        }
+    }
+    return out;
+}

package/dist/scanner/walk.js

@@ -0,0 +1,16 @@
+import fg from "fast-glob";
+export async function walk(root) {
+    return fg([
+        "**/*.{ts,tsx,js,jsx,mjs,cjs}",
+        "!**/node_modules/**",
+        "!**/dist/**",
+        "!**/build/**",
+        "!**/.next/**",
+        "!**/.output/**",
+        "!**/.git/**",
+        "!**/coverage/**",
+        "!**/*.d.ts",
+        "!**/routeTree.gen.*",
+        "!**/packages/cli/**", // never scan the scanner itself
+    ], { cwd: root, absolute: true, dot: false });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};