@empline/preflight 1.1.11 → 1.1.13

package/dist/checks/consolidated/seo.js

@@ -0,0 +1,1438 @@
+#!/usr/bin/env tsx
+"use strict";
+/**
+ * SEO Preflight (Authoritative)
+ *
+ * This module is used in two ways:
+ * 1) Imported by the main preflight system (via the consolidated module runner)
+ *    - Should be non-blocking by default (returns passed=true with warnings)
+ * 2) Executed directly via `pnpm preflight:seo` (package.json)
+ *    - Supports `--strict` to fail on blocking issues
+ *
+ * Goals:
+ * - Single source of truth for SEO validation.
+ * - Keep legacy node-based SEO checks (already battle-tested).
+ * - Add missing coverage: metadata presence/quality, OG/Twitter correctness,
+ *   robots/sitemap safety rails, and crawlable internal linking.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = run;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ts = __importStar(require("typescript"));
+const console_chars_1 = require("../../utils/console-chars");
+const file_cache_1 = require("../../shared/file-cache");
+const glob_1 = require("glob");
+const EXCLUDED_GLOBS = [
+    "**/node_modules/**",
+    "**/.next/**",
+    "**/dist/**",
+    "**/coverage/**",
+    "**/test-results/**",
+    "**/__tests__/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+];
+function readText(filePath) {
+    return fs.readFileSync(filePath, "utf8");
+}
+function addIssue(issues, issue) {
+    issues.push(issue);
+}
+function formatIssue(issue) {
+    const where = issue.file ? ` (${issue.file})` : "";
+    return `${issue.message}${where}`;
+}
+function runScriptAsChildProcess(params) {
+    const { command, args, label, strict, verbose, alwaysWarn } = params;
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(command, args, {
+            cwd: process.cwd(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        child.on("close", (code) => {
+            stdout = stdout.trim();
+            stderr = stderr.trim();
+            if (verbose) {
+                if (stdout)
+                    console.log(stdout);
+                if (stderr)
+                    console.error(stderr);
+            }
+            // Heuristic: non-zero exit code is blocking in strict mode, warning otherwise.
+            if (code && code !== 0) {
+                const severity = alwaysWarn ? "warning" : strict ? "blocking" : "warning";
+                const message = `${label} failed (exit ${code})`;
+                const details = [stdout, stderr].filter(Boolean).join("\n");
+                resolve([
+                    {
+                        severity,
+                        message: details ? `${message}: ${details.split("\n")[0]}` : message,
+                    },
+                ]);
+                return;
+            }
+            // Some scripts return 0 but contain warnings; surface a summary line (optional).
+            if (!strict && stdout.includes(`${console_chars_1.emoji.warning}`) && !stdout.includes(`${console_chars_1.emoji.error}`)) {
+                resolve([
+                    {
+                        severity: "warning",
+                        message: `${label} reported warnings`,
+                    },
+                ]);
+                return;
+            }
+            resolve([]);
+        });
+        child.on("error", (err) => {
+            resolve([
+                {
+                    severity: "blocking",
+                    message: `${label} failed to spawn: ${err.message}`,
+                },
+            ]);
+        });
+    });
+}
+function parseMetadataLiteralForStrings(content) {
+    // Deprecated: kept for backward compatibility in case other callers rely on it.
+    // New checks use AST parsing (see analyzeNextMetadata()).
+    const titleMatch = content.match(/\btitle\s*:\s*(?:"([^"\n]+)"|'([^'\n]+)'|`([^`\n]+)`)/);
+    const descriptionMatch = content.match(/\bdescription\s*:\s*(?:"([^"\n]+)"|'([^'\n]+)'|`([^`\n]+)`)/);
+    const title = (titleMatch?.[1] || titleMatch?.[2] || titleMatch?.[3])?.trim();
+    const description = (descriptionMatch?.[1] ||
+        descriptionMatch?.[2] ||
+        descriptionMatch?.[3])?.trim();
+    return { title, description };
+}
+function tryGetLiteralString(node) {
+    if (!node)
+        return undefined;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return { value: node.text, kind: "string" };
+    }
+    if (ts.isTemplateExpression(node)) {
+        const head = node.head.text;
+        const hasExpressions = node.templateSpans.length > 0;
+        if (!hasExpressions)
+            return { value: head, kind: "template" };
+        return undefined;
+    }
+    return undefined;
+}
+function isFalseLiteral(expr) {
+    return expr?.kind === ts.SyntaxKind.FalseKeyword;
+}
+function getPropertyNameText(name) {
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name))
+        return name.text;
+    if (ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
+}
+function collectObjectLiteralProps(expr, out) {
+    if (!expr)
+        return;
+    if (!ts.isObjectLiteralExpression(expr))
+        return;
+    for (const prop of expr.properties) {
+        if (ts.isPropertyAssignment(prop)) {
+            const key = getPropertyNameText(prop.name);
+            if (key)
+                out.set(key, prop.initializer);
+        }
+        else if (ts.isShorthandPropertyAssignment(prop)) {
+            out.set(prop.name.text, prop.name);
+        }
+        else if (ts.isSpreadAssignment(prop)) {
+            const spreadExpr = prop.expression;
+            // Common pattern: ...buildMetadata({ title, description, path })
+            if (ts.isCallExpression(spreadExpr) && spreadExpr.arguments.length > 0) {
+                const arg0 = spreadExpr.arguments[0];
+                if (ts.isObjectLiteralExpression(arg0))
+                    collectObjectLiteralProps(arg0, out);
+            }
+        }
+    }
+}
+function tryGetNestedLiteralString(root, pathSegments) {
+    let current = root;
+    for (const seg of pathSegments) {
+        if (!current || !ts.isObjectLiteralExpression(current))
+            return undefined;
+        const props = new Map();
+        collectObjectLiteralProps(current, props);
+        current = props.get(seg);
+    }
+    return tryGetLiteralString(current);
+}
+function isLikelyInternalOrAuthRoute(routePath) {
+    return (routePath.startsWith("/admin") ||
+        routePath.startsWith("/api") ||
+        routePath.startsWith("/account") ||
+        routePath.startsWith("/auth") ||
+        routePath.startsWith("/dashboard") ||
+        routePath.startsWith("/seller") ||
+        routePath.startsWith("/store/") ||
+        routePath.startsWith("/login") ||
+        routePath.startsWith("/register") ||
+        routePath.startsWith("/reset-password") ||
+        routePath.startsWith("/forgot-password"));
+}
+function classifyAppFileKind(appFile) {
+    if (!appFile.startsWith("app\\") && !appFile.startsWith("app/"))
+        return "public";
+    const normalized = appFile.replace(/\\/g, "/");
+    const routePath = "/" +
+        normalized
+            .replace(/^app\//, "")
+            .replace(/\/(page|layout|template|loading|error|not-found|head)\.(ts|tsx)$/, "");
+    return isLikelyInternalOrAuthRoute(routePath) ? "internal" : "public";
+}
+function findExportedConstInitializer(sf, name) {
+    for (const statement of sf.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        const hasExport = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+        if (!hasExport)
+            continue;
+        for (const decl of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(decl.name))
+                continue;
+            if (decl.name.text !== name)
+                continue;
+            return decl.initializer;
+        }
+    }
+    return undefined;
+}
+function findExportedFunctionDeclaration(sf, name) {
+    for (const statement of sf.statements) {
+        if (!ts.isFunctionDeclaration(statement))
+            continue;
+        if (!statement.name || statement.name.text !== name)
+            continue;
+        const hasExport = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+        if (!hasExport)
+            continue;
+        return statement;
+    }
+    return undefined;
+}
+function hasReexportedNamedExport(sf, exportName) {
+    for (const statement of sf.statements) {
+        if (!ts.isExportDeclaration(statement))
+            continue;
+        if (!statement.exportClause)
+            continue;
+        if (!ts.isNamedExports(statement.exportClause))
+            continue;
+        for (const el of statement.exportClause.elements) {
+            if (el.name.text === exportName)
+                return true;
+            if (el.propertyName && el.propertyName.text === exportName)
+                return true;
+        }
+    }
+    return false;
+}
+function collectReturnedObjectLiterals(fn) {
+    const objects = [];
+    if (!fn.body)
+        return objects;
+    const visit = (node) => {
+        if (ts.isReturnStatement(node) &&
+            node.expression &&
+            ts.isObjectLiteralExpression(node.expression)) {
+            objects.push(node.expression);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(fn.body);
+    return objects;
+}
+function analyzeNextMetadata(sourceText, fileNameForDiagnostics) {
+    const sf = ts.createSourceFile(fileNameForDiagnostics, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const metadataInit = findExportedConstInitializer(sf, "metadata");
+    const generateMetadataFn = findExportedFunctionDeclaration(sf, "generateMetadata");
+    const hasReexportedMetadata = hasReexportedNamedExport(sf, "metadata");
+    const hasReexportedGenerateMetadata = hasReexportedNamedExport(sf, "generateMetadata");
+    const metadataProps = new Map();
+    if (metadataInit)
+        collectObjectLiteralProps(metadataInit, metadataProps);
+    const returnedMetadataProps = [];
+    if (generateMetadataFn) {
+        const returnedObjects = collectReturnedObjectLiterals(generateMetadataFn);
+        for (const obj of returnedObjects) {
+            const props = new Map();
+            collectObjectLiteralProps(obj, props);
+            returnedMetadataProps.push(props);
+        }
+    }
+    const hasMetadataExport = Boolean(metadataInit) || hasReexportedMetadata;
+    const hasGenerateMetadata = Boolean(generateMetadataFn) || hasReexportedGenerateMetadata;
+    const hasTitle = (hasMetadataExport && metadataProps.has("title")) ||
+        (hasGenerateMetadata && returnedMetadataProps.some((p) => p.has("title")));
+    const hasDescription = (hasMetadataExport && metadataProps.has("description")) ||
+        (hasGenerateMetadata && returnedMetadataProps.some((p) => p.has("description")));
+    const titleLiteral = (hasMetadataExport
+        ? tryGetLiteralString(metadataProps.get("title"))
+        : undefined) ||
+        (hasGenerateMetadata
+            ? (() => {
+                for (const p of returnedMetadataProps) {
+                    const lit = tryGetLiteralString(p.get("title"));
+                    if (lit)
+                        return lit;
+                }
+                return undefined;
+            })()
+            : undefined);
+    const descriptionLiteral = (hasMetadataExport
+        ? tryGetLiteralString(metadataProps.get("description"))
+        : undefined) ||
+        (hasGenerateMetadata
+            ? (() => {
+                for (const p of returnedMetadataProps) {
+                    const lit = tryGetLiteralString(p.get("description"));
+                    if (lit)
+                        return lit;
+                }
+                return undefined;
+            })()
+            : undefined);
+    const robotsIndexFalse = (hasMetadataExport &&
+        (() => {
+            const robotsExpr = metadataProps.get("robots");
+            if (!robotsExpr)
+                return false;
+            const robotsProps = new Map();
+            collectObjectLiteralProps(robotsExpr, robotsProps);
+            const indexExpr = robotsProps.get("index");
+            return isFalseLiteral(indexExpr);
+        })()) ||
+        (hasGenerateMetadata &&
+            returnedMetadataProps.some((props) => {
+                const robotsExpr = props.get("robots");
+                if (!robotsExpr)
+                    return false;
+                const robotsProps = new Map();
+                collectObjectLiteralProps(robotsExpr, robotsProps);
+                const indexExpr = robotsProps.get("index");
+                return isFalseLiteral(indexExpr);
+            }));
+    return {
+        hasMetadataExport,
+        hasGenerateMetadata,
+        hasTitle,
+        hasDescription,
+        titleLiteral,
+        descriptionLiteral,
+        canonicalLiteral: (hasMetadataExport
+            ? tryGetNestedLiteralString(metadataInit, ["alternates", "canonical"])
+            : undefined) ||
+            (hasGenerateMetadata
+                ? (() => {
+                    for (const props of returnedMetadataProps) {
+                        const canonical = tryGetNestedLiteralString(props.get("alternates"), ["canonical"]);
+                        if (canonical)
+                            return canonical;
+                    }
+                    return undefined;
+                })()
+                : undefined),
+        openGraphUrlLiteral: (hasMetadataExport
+            ? tryGetNestedLiteralString(metadataInit, ["openGraph", "url"])
+            : undefined) ||
+            (hasGenerateMetadata
+                ? (() => {
+                    for (const props of returnedMetadataProps) {
+                        const url = tryGetNestedLiteralString(props.get("openGraph"), ["url"]);
+                        if (url)
+                            return url;
+                    }
+                    return undefined;
+                })()
+                : undefined),
+        robotsIndexFalse,
+        hasReexportedMetadata,
+        hasReexportedGenerateMetadata,
+    };
+}
+function classifyPageKind(file) {
+    if (file.includes("/api/") || file.includes("\\api\\"))
+        return "internal";
+    const routePath = "/" +
+        file
+            .replace(/^app[\\/]/, "")
+            .replace(/[\\/]page\.(ts|tsx)$/, "")
+            .replace(/\\/g, "/");
+    if (isLikelyInternalOrAuthRoute(routePath))
+        return "internal";
+    return "public";
+}
+function isAbsoluteHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function stripJsComments(input) {
+    // Best-effort removal of /* */ and // comments to reduce false positives.
+    return input.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:\\])\/\/.*$/gm, "$1");
+}
+function isRelativeRootPath(value) {
+    return value.startsWith("/");
+}
+function checkMetadataUrlCorrectness(params) {
+    const { file, analysis, strict, ci, hasRootMetadataBase } = params;
+    const issues = [];
+    const pageKind = classifyPageKind(file);
+    if (pageKind !== "public")
+        return issues;
+    const canonical = analysis.canonicalLiteral?.value?.trim();
+    if (canonical) {
+        if (isAbsoluteHttpUrl(canonical)) {
+            // OK
+        }
+        else if (isRelativeRootPath(canonical)) {
+            // Relative canonicals are acceptable if metadataBase is configured.
+            if (!hasRootMetadataBase) {
+                addIssue(issues, {
+                    severity: ci ? "blocking" : "warning",
+                    file,
+                    message: "Page uses a relative canonical but root metadataBase is missing (canonical may become incorrect)",
+                });
+            }
+            else {
+                addIssue(issues, {
+                    severity: "info",
+                    file,
+                    message: "Canonical is relative; ensure metadataBase is correct for absolute output",
+                });
+            }
+        }
+        else {
+            addIssue(issues, {
+                severity: ci ? "blocking" : "warning",
+                file,
+                message: "Canonical URL does not look like an absolute URL or root-relative path",
+            });
+        }
+    }
+    const ogUrl = analysis.openGraphUrlLiteral?.value?.trim();
+    if (ogUrl) {
+        // Best practice: OpenGraph url should be absolute for scrapers.
+        if (!isAbsoluteHttpUrl(ogUrl)) {
+            addIssue(issues, {
+                severity: ci ? "blocking" : "warning",
+                file,
+                message: "openGraph.url should be an absolute URL (e.g., derived from SITE_URL)",
+            });
+        }
+    }
+    return issues;
+}
+// CACHED FILE LISTS - Scan once, use everywhere
+let _cachedPageTsFiles = null;
+async function getPageTsFiles() {
+    if (!_cachedPageTsFiles) {
+        _cachedPageTsFiles = await file_cache_1.fileCache.getPageTsFiles();
+    }
+    return _cachedPageTsFiles;
+}
+async function checkForceDynamicCaching(options) {
+    const issues = [];
+    const strict = options.strict;
+    const ci = options.ci;
+    const pageFiles = await getPageTsFiles();
+    for (const file of pageFiles) {
+        const pageKind = classifyPageKind(file);
+        if (pageKind !== "public")
+            continue;
+        const content = readText(path.join(process.cwd(), file));
+        const isForceDynamic = /export\s+const\s+dynamic\s*=\s*['"]force-dynamic['"]/.test(content);
+        if (!isForceDynamic)
+            continue;
+        const usesUnstableCache = /unstable_cache\b/.test(content);
+        const hasRevalidateConst = /export\s+const\s+revalidate\s*=\s*\d+/.test(content);
+        const usesFetchRevalidate = /next\s*:\s*\{\s*revalidate\s*:\s*\d+/.test(content);
+        if (!usesUnstableCache && !hasRevalidateConst && !usesFetchRevalidate) {
+            addIssue(issues, {
+                severity: ci ? "blocking" : "warning",
+                file,
+                message: "Page sets dynamic=force-dynamic but shows no unstable_cache/ISR revalidate; consider caching to avoid per-request database work",
+            });
+        }
+    }
+    return issues;
+}
+async function checkPaginationMetadataHeuristics(options) {
+    const issues = [];
+    const strict = options.strict;
+    const ci = options.ci;
+    const pageFiles = await getPageTsFiles();
+    for (const file of pageFiles) {
+        const pageKind = classifyPageKind(file);
+        if (pageKind !== "public")
+            continue;
+        const raw = readText(path.join(process.cwd(), file));
+        const content = stripJsComments(raw);
+        // Heuristics for pagination:
+        // - Explicit query usage: get('page') OR URLSearchParams({ page: ... })
+        // - Pagination component usage: <Pagination ...>
+        // Keep this conservative to avoid false positives from unrelated mentions.
+        const readsPageQuery = /get\(\s*['"]page['"]\s*\)/.test(content) || /\?page=/.test(content);
+        const hasClientPaginationState = /\bcurrentPage\b/.test(content) && /\btotalPages\b/.test(content);
+        const hasPageParamUsage = readsPageQuery || hasClientPaginationState;
+        const hasPaginationUi = /<Pagination\b/.test(content);
+        const looksPaginated = hasPageParamUsage || hasPaginationUi;
+        if (!looksPaginated)
+            continue;
+        const hasPrevNextAlternates = /rel\s*=\s*['"]prev['"]|rel\s*=\s*['"]next['"]/.test(content);
+        const usesPaginationHelper = /generatePaginationMetadata\s*\(/.test(content);
+        if (!hasPrevNextAlternates && !usesPaginationHelper) {
+            addIssue(issues, {
+                severity: ci ? "blocking" : strict ? "warning" : "info",
+                file,
+                message: "Paginated page heuristics detected; consider adding prev/next links via generatePaginationMetadata() for better crawl discovery",
+            });
+        }
+    }
+    return issues;
+}
+async function checkTypographyHeadingSemantics(options) {
+    const issues = [];
+    const strict = options.strict;
+    const ci = options.ci;
+    const pageFiles = await getPageTsFiles();
+    for (const file of pageFiles) {
+        const pageKind = classifyPageKind(file);
+        if (pageKind !== "public")
+            continue;
+        const content = readText(path.join(process.cwd(), file));
+        // Best-effort scan of Typography tags for semantic heading components.
+        // We only gate h1/h2/h3 variants since those matter most for SEO.
+        const tagMatches = content.match(/<Typography\b[^>]*>/g) || [];
+        for (const tag of tagMatches) {
+            const variantMatch = tag.match(/\bvariant\s*=\s*['"](h1|h2|h3)['"]/);
+            if (!variantMatch)
+                continue;
+            const variant = variantMatch[1];
+            const hasComponentProp = /\bcomponent\s*=\s*['"]/i.test(tag);
+            const componentMatch = tag.match(/\bcomponent\s*=\s*['"](h1|h2|h3|h4|h5|h6)['"]/i);
+            if (!hasComponentProp) {
+                addIssue(issues, {
+                    severity: ci ? "blocking" : strict ? "warning" : "info",
+                    file,
+                    message: `Typography variant="${variant}" is missing component="${variant}" (semantic headings improve SEO + accessibility)`,
+                });
+                continue;
+            }
+            // If component is present but differs, that's usually intentional (ex: visual h2 but semantic h1).
+            // We keep this informational even in CI.
+            if (componentMatch && componentMatch[1] !== variant) {
+                addIssue(issues, {
+                    severity: "info",
+                    file,
+                    message: `Typography variant="${variant}" uses component="${componentMatch[1]}"`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+async function checkNativeImgAndAltText(options) {
+    const issues = [];
+    const strict = options.strict;
+    const ci = options.ci;
+    // Focus on app + product components (high-SEO surface area) to avoid exploding noise.
+    const files = await file_cache_1.fileCache.getFiles("{app,components/product}/**/*.{ts,tsx}", { ignore: EXCLUDED_GLOBS });
+    for (const file of files) {
+        const isUnderApp = file.startsWith("app/") || file.startsWith("app\\");
+        if (isUnderApp && classifyAppFileKind(file) !== "public")
+            continue;
+        const content = readText(path.join(process.cwd(), file));
+        const hasImg = /<img\b/i.test(content);
+        if (hasImg) {
+            addIssue(issues, {
+                severity: ci ? "blocking" : strict ? "warning" : "info",
+                file,
+                message: "Native <img> tag detected; prefer next/image for optimization (or ensure width/height + lazy loading + good alt)",
+            });
+        }
+        const genericAlt = /\balt\s*=\s*['"](card image|image|photo|picture)['"]/i.test(content);
+        if (genericAlt) {
+            addIssue(issues, {
+                severity: ci ? "blocking" : strict ? "warning" : "info",
+                file,
+                message: "Generic alt text detected; use descriptive alt for SEO/Google Images",
+            });
+        }
+    }
+    return issues;
+}
+async function checkSchemaGeneratorSerializability() {
+    const issues = [];
+    try {
+        // These imports should be safe (pure helpers, no DB access).
+        const productSchemaModule = await Promise.resolve(`${pathToFileUrl("lib/product-schema.ts")}`).then(s => __importStar(require(s)));
+        const seoModule = await Promise.resolve(`${pathToFileUrl("lib/seo.ts")}`).then(s => __importStar(require(s)));
+        const { generateProductSchema, generateBreadcrumbSchema, generateImageSchema } = productSchemaModule;
+        const { generateFAQPageSchema, generateBreadcrumbSchema: generateSeoBreadcrumbSchema } = seoModule;
+        const dummyCard = {
+            id: "test",
+            featured: "Test Player",
+            year: "2024",
+            brand: "TOPPS",
+            series: "Test Series",
+            cardNumber: "1",
+            sport: "BASEBALL",
+            team: "Test Team",
+            productType: "SPORTS_CARD",
+            description: "Test description",
+        };
+        const dummyListing = {
+            price: 12.34,
+            imageUrls: ["https://example.com/image.jpg"],
+            condition: "NEAR_MINT",
+            sellerName: "Test Seller",
+            quantityAvailable: 1,
+            freeShipping: true,
+            shippingCost: 0,
+            returnPolicy: 30,
+        };
+        const samples = [];
+        if (typeof generateProductSchema === "function") {
+            samples.push({
+                label: "generateProductSchema",
+                value: generateProductSchema(dummyCard, [dummyListing], dummyListing, [dummyListing], "test-slug"),
+            });
+        }
+        if (typeof generateBreadcrumbSchema === "function") {
+            samples.push({
+                label: "generateBreadcrumbSchema(product)",
+                value: generateBreadcrumbSchema(dummyCard, "test-slug"),
+            });
+        }
+        if (typeof generateImageSchema === "function") {
+            samples.push({
+                label: "generateImageSchema",
+                value: generateImageSchema(dummyCard, "https://example.com/image.jpg"),
+            });
+        }
+        if (typeof generateFAQPageSchema === "function") {
+            samples.push({
+                label: "generateFAQPageSchema",
+                value: generateFAQPageSchema([
+                    { question: "What is SuperCatch?", answer: "A marketplace." },
+                ]),
+            });
+        }
+        if (typeof generateSeoBreadcrumbSchema === "function") {
+            samples.push({
+                label: "generateBreadcrumbSchema(seo)",
+                value: generateSeoBreadcrumbSchema([
+                    { name: "Home", url: "https://example.com" },
+                    { name: "Test", url: "https://example.com/test" },
+                ]),
+            });
+        }
+        for (const sample of samples) {
+            try {
+                const json = JSON.stringify(sample.value);
+                if (!json) {
+                    addIssue(issues, {
+                        severity: "warning",
+                        file: "lib/product-schema.ts",
+                        message: `${sample.label} produced empty JSON output`,
+                    });
+                    continue;
+                }
+                JSON.parse(json);
+            }
+            catch (error) {
+                addIssue(issues, {
+                    severity: "blocking",
+                    file: "lib/product-schema.ts",
+                    message: `${sample.label} output is not JSON-serializable: ${error?.message || String(error)}`,
+                });
+            }
+        }
+    }
+    catch (error) {
+        addIssue(issues, {
+            severity: "warning",
+            file: "scripts/active/preflights/seo.ts",
+            message: `Could not import schema generators for serializability checks: ${error?.message || String(error)}`,
+        });
+    }
+    return issues;
+}
+function pathToFileUrl(relativePath) {
+    // Ensure a stable file:// URL for dynamic imports.
+    const absolute = path.join(process.cwd(), relativePath);
+    const normalized = absolute.replace(/\\/g, "/");
+    return `file:///${normalized.replace(/^\/+/, "")}`;
+}
+async function checkMetadataPresenceAndQuality(options) {
+    const issues = [];
+    const strict = options.strict;
+    const pageFiles = await getPageTsFiles();
+    const titlesByFile = [];
+    const descriptionsByFile = [];
+    const robotsText = (() => {
+        const robotsPath = path.join(process.cwd(), "app/robots.ts");
+        if (!fs.existsSync(robotsPath))
+            return "";
+        return readText(robotsPath);
+    })();
+    const disallowedPrefixes = (() => {
+        const prefixes = new Set();
+        // Best-effort extraction of string literal disallow entries.
+        const matches = robotsText.matchAll(/disallow\s*:\s*\[([\s\S]*?)\]/g);
+        for (const m of matches) {
+            const list = m[1] || "";
+            const itemMatches = list.matchAll(/['"](\/[^'"]+)['"]/g);
+            for (const im of itemMatches)
+                prefixes.add(im[1]);
+        }
+        return Array.from(prefixes);
+    })();
+    const isBlockedByRobots = (routePath) => {
+        const normalized = routePath.replace(/\\/g, "/");
+        const normalizedWithSlash = normalized.endsWith("/") ? normalized : `${normalized}/`;
+        return disallowedPrefixes.some((p) => {
+            const prefix = p.endsWith("/") ? p : `${p}/`;
+            return normalizedWithSlash.startsWith(prefix);
+        });
+    };
+    const isAuthOrInternal = (file) => {
+        const normalized = file.replace(/\\/g, "/");
+        const internalPrefixes = [
+            "app/admin/",
+            "app/account/",
+            "app/store/",
+            "app/seller/",
+            "app/dashboard/",
+            "app/checkout/",
+            "app/api/",
+            "app/dev/", // Dev-only pages
+            "app/invite/", // Private invitation pages
+        ];
+        const authPrefixes = [
+            "app/login/",
+            "app/register/",
+            "app/reset-password/",
+            "app/forgot-password/",
+            "app/auth/",
+        ];
+        if (internalPrefixes.some((p) => normalized.startsWith(p)))
+            return true;
+        if (authPrefixes.some((p) => normalized.startsWith(p)))
+            return true;
+        return false;
+    };
+    const findClosestLayoutWithMetadata = (pageFile) => {
+        const normalized = pageFile.replace(/\\/g, "/");
+        const parts = normalized.split("/");
+        // parts[0] === "app"
+        for (let i = parts.length - 1; i >= 1; i--) {
+            const dir = parts.slice(0, i).join("/");
+            const layoutCandidates = [`${dir}/layout.tsx`, `${dir}/layout.ts`];
+            for (const candidate of layoutCandidates) {
+                const full = path.join(process.cwd(), candidate);
+                if (!fs.existsSync(full))
+                    continue;
+                const layoutContent = readText(full);
+                const layoutAnalysis = analyzeNextMetadata(layoutContent, candidate);
+                if (layoutAnalysis.hasMetadataExport || layoutAnalysis.hasGenerateMetadata) {
+                    return { file: candidate, analysis: layoutAnalysis };
+                }
+            }
+        }
+        return undefined;
+    };
+    for (const file of pageFiles) {
+        const fullPath = path.join(process.cwd(), file);
+        const content = readText(fullPath);
+        const analysis = analyzeNextMetadata(content, file);
+        const closestLayout = findClosestLayoutWithMetadata(file);
+        const pageHasOwnMetadata = analysis.hasMetadataExport || analysis.hasGenerateMetadata;
+        const effectiveHasMetadata = pageHasOwnMetadata ||
+            Boolean(closestLayout?.analysis.hasMetadataExport || closestLayout?.analysis.hasGenerateMetadata);
+        const effectiveHasTitle = analysis.hasTitle || Boolean(closestLayout?.analysis.hasTitle);
+        const effectiveHasDescription = analysis.hasDescription || Boolean(closestLayout?.analysis.hasDescription);
+        const effectiveRobotsNoIndex = analysis.robotsIndexFalse || Boolean(closestLayout?.analysis.robotsIndexFalse);
+        const routePath = file
+            .replace(/\\/g, "/")
+            .replace(/^app\//, "/")
+            .replace(/\/page\.(ts|tsx)$/, "");
+        // Ignore utility-only pages with special Next.js conventions (rare, but avoid noise)
+        const isNotFound = file.endsWith("/not-found.tsx");
+        if (isNotFound)
+            continue;
+        // The homepage often relies on root layout metadata.
+        const isRootPage = file.replace(/\\/g, "/") === "app/page.tsx";
+        // Requested safety rail: public pages should define their own metadata at the page level
+        // (do not rely solely on layouts). In non-strict mode this is a warning; in strict mode it blocks.
+        if (!isAuthOrInternal(file) && !isRootPage && !pageHasOwnMetadata) {
+            addIssue(issues, {
+                severity: strict ? "blocking" : "warning",
+                file,
+                message: "Public page should export metadata or generateMetadata (page-level), not only via layout",
+            });
+        }
+        // Re-exported metadata is valid, but we can't reliably verify title/description literals.
+        if ((analysis.hasReexportedMetadata || analysis.hasReexportedGenerateMetadata) &&
+            !isAuthOrInternal(file)) {
+            addIssue(issues, {
+                severity: "info",
+                file,
+                message: "Page re-exports metadata/generateMetadata; title/description quality checks may be incomplete",
+            });
+        }
+        if (!effectiveHasMetadata && !isRootPage) {
+            addIssue(issues, {
+                severity: isAuthOrInternal(file) ? "warning" : strict ? "blocking" : "warning",
+                file,
+                message: "Route has no metadata/generateMetadata on page or layout chain",
+            });
+            continue;
+        }
+        // Indexability rails: internal/auth routes should be noindex OR blocked by robots.ts.
+        if (isAuthOrInternal(file)) {
+            if (!effectiveRobotsNoIndex && !isBlockedByRobots(routePath)) {
+                addIssue(issues, {
+                    severity: strict ? "blocking" : "warning",
+                    file,
+                    message: "Internal/auth route should be noindex (metadata robots.index=false) or blocked via robots.ts",
+                });
+            }
+            // Do not enforce title/description quality on internal/auth routes.
+            continue;
+        }
+        if (!effectiveHasTitle) {
+            addIssue(issues, {
+                severity: strict ? "blocking" : "warning",
+                file,
+                message: "Metadata missing title (title is required for SEO)",
+            });
+        }
+        else if (!analysis.hasTitle && Boolean(closestLayout?.analysis.hasTitle)) {
+            addIssue(issues, {
+                severity: "info",
+                file,
+                message: "Title appears to be provided by a layout; prefer page-level title for uniqueness",
+            });
+        }
+        if (!effectiveHasDescription) {
+            addIssue(issues, {
+                severity: strict ? "blocking" : "warning",
+                file,
+                message: "Metadata missing description (description is required for SEO)",
+            });
+        }
+        else if (!analysis.hasDescription && Boolean(closestLayout?.analysis.hasDescription)) {
+            addIssue(issues, {
+                severity: "info",
+                file,
+                message: "Description appears to be provided by a layout; prefer page-level description for uniqueness",
+            });
+        }
+        if (analysis.titleLiteral?.value) {
+            const title = analysis.titleLiteral.value.trim();
+            if (title) {
+                titlesByFile.push({ file, title });
+                if (title.length < 30 || title.length > 60) {
+                    addIssue(issues, {
+                        severity: "warning",
+                        file,
+                        message: `Title length out of bounds (${title.length} chars). Expected ~30–60.`,
+                    });
+                }
+            }
+        }
+        if (analysis.descriptionLiteral?.value) {
+            const description = analysis.descriptionLiteral.value.trim();
+            if (description) {
+                descriptionsByFile.push({ file, description });
+                if (description.length < 50 || description.length > 160) {
+                    addIssue(issues, {
+                        severity: "warning",
+                        file,
+                        message: `Description length out of bounds (${description.length} chars). Expected ~50–160.`,
+                    });
+                }
+            }
+        }
+    }
+    // Duplicate-title heuristic (only for literal strings we captured)
+    const titleCounts = new Map();
+    for (const item of titlesByFile) {
+        const key = item.title.toLowerCase();
+        titleCounts.set(key, [...(titleCounts.get(key) || []), item.file]);
+    }
+    for (const [titleKey, files] of titleCounts.entries()) {
+        if (files.length >= 2) {
+            addIssue(issues, {
+                severity: "warning",
+                message: `Duplicate page titles detected (${files.length} pages share the same title): "${titleKey}"`,
+                file: files.slice(0, 3).join(", ") + (files.length > 3 ? "${chars.ellipsis}" : ""),
+            });
+        }
+    }
+    const descriptionCounts = new Map();
+    for (const item of descriptionsByFile) {
+        const key = item.description.toLowerCase();
+        descriptionCounts.set(key, [...(descriptionCounts.get(key) || []), item.file]);
+    }
+    for (const [descKey, files] of descriptionCounts.entries()) {
+        if (files.length >= 2) {
+            addIssue(issues, {
+                severity: "warning",
+                message: `Duplicate page descriptions detected (${files.length} pages share the same description): "${descKey.slice(0, 80)}${descKey.length > 80 ? "${chars.ellipsis}" : ""}"`,
+                file: files.slice(0, 3).join(", ") + (files.length > 3 ? "${chars.ellipsis}" : ""),
+            });
+        }
+    }
+    return issues;
+}
+function checkRootLayoutMetadata() {
+    const issues = [];
+    const layoutPath = path.join(process.cwd(), "app/layout.tsx");
+    if (!fs.existsSync(layoutPath)) {
+        addIssue(issues, {
+            severity: "blocking",
+            file: "app/layout.tsx",
+            message: "Missing root layout (Next.js requires app/layout.tsx)",
+        });
+        return issues;
+    }
+    const content = readText(layoutPath);
+    if (!/metadataBase\s*:/.test(content)) {
+        addIssue(issues, {
+            severity: "blocking",
+            file: "app/layout.tsx",
+            message: "Root layout metadata missing metadataBase (helps canonical + absolute OG URLs)",
+        });
+    }
+    // Hardcoded absolute metadataBase is a common source of canonical/OG drift.
+    if (/metadataBase\s*:\s*new\s+URL\(\s*['"]https?:\/\//.test(content)) {
+        addIssue(issues, {
+            severity: "blocking",
+            file: "app/layout.tsx",
+            message: "Root layout metadataBase appears hardcoded; derive it from SITE_URL/env",
+        });
+    }
+    const usesBuildMetadataHelper = /buildMetadata\s*\(/.test(content) || /generateMetadata\s+as\s+buildMetadata/.test(content);
+    if (!usesBuildMetadataHelper && !/openGraph\s*:/.test(content)) {
+        addIssue(issues, {
+            severity: "warning",
+            file: "app/layout.tsx",
+            message: "Root layout missing default openGraph metadata",
+        });
+    }
+    if (!usesBuildMetadataHelper && !/twitter\s*:/.test(content)) {
+        addIssue(issues, {
+            severity: "warning",
+            file: "app/layout.tsx",
+            message: "Root layout missing default twitter metadata",
+        });
+    }
+    // Ensure themeColor is not a CSS variable (known rendering timing issue)
+    if (/themeColor\s*:\s*["']var\(--[^)]+\)["']/.test(content)) {
+        addIssue(issues, {
+            severity: "blocking",
+            file: "app/layout.tsx",
+            message: "themeColor uses a CSS var; browsers/crawlers may not resolve it early",
+        });
+    }
+    return issues;
+}
+function checkProductOGType() {
+    const issues = [];
+    const productPage = path.join(process.cwd(), "app/product/[slug]/page.tsx");
+    if (!fs.existsSync(productPage))
+        return issues;
+    const file = "app/product/[slug]/page.tsx";
+    const content = readText(productPage);
+    const analysis = analyzeNextMetadata(content, file);
+    if (!analysis.hasGenerateMetadata && !analysis.hasMetadataExport) {
+        addIssue(issues, {
+            severity: "blocking",
+            file,
+            message: "Product page must export generateMetadata or metadata",
+        });
+        return issues;
+    }
+    // Next.js 16 only supports standard OpenGraph types: website, article, book, profile, music.*, video.*
+    // "product" is NOT a valid OpenGraph type - use "website" and rely on JSON-LD Schema.org for product data
+    const hasWebsiteType = /openGraph\s*:\s*\{[\s\S]*?type\s*:\s*["']website["']/.test(content);
+    const hasInvalidProductType = /openGraph\s*:\s*\{[\s\S]*?type\s*:\s*["']product["']/.test(content);
+    if (hasInvalidProductType) {
+        addIssue(issues, {
+            severity: "blocking",
+            file,
+            message: "Product page openGraph.type is 'product' which is invalid in Next.js 16 - use 'website' instead",
+        });
+    }
+    else if (!hasWebsiteType) {
+        addIssue(issues, {
+            severity: "warning",
+            file,
+            message: "Product page openGraph.type should be 'website' (product data via JSON-LD Schema.org)",
+        });
+    }
+    // Ensure twitter card config exists and matches product sharing expectations.
+    if (!/twitter\s*:\s*\{[\s\S]*?card\s*:\s*["']summary_large_image["']/.test(content)) {
+        addIssue(issues, {
+            severity: "blocking",
+            file,
+            message: "Product page twitter.card must be 'summary_large_image'",
+        });
+    }
+    // Images: prefer object form with url+alt, and urls should be absolute.
+    const hasOgImages = /openGraph\s*:\s*\{[\s\S]*?images\s*:\s*/.test(content);
+    if (!hasOgImages) {
+        addIssue(issues, {
+            severity: "blocking",
+            file,
+            message: "Product page openGraph.images missing",
+        });
+    }
+    const usesStringImages = /openGraph\s*:\s*\{[\s\S]*?images\s*:\s*\[[^\]]*['"][^\]]*['"]/s.test(content);
+    if (usesStringImages) {
+        addIssue(issues, {
+            severity: "blocking",
+            file,
+            message: "Product page openGraph.images should use object entries with url+alt (not plain strings)",
+        });
+    }
+    const hasAlt = /openGraph\s*:\s*\{[\s\S]*?images\s*:\s*[\s\S]*?alt\s*:\s*/.test(content);
+    if (!hasAlt) {
+        addIssue(issues, {
+            severity: "blocking",
+            file,
+            message: "Product page openGraph.images entries should include alt text",
+        });
+    }
+    // width/height is ideal for scrapers/crawlers, but not always feasible with dynamic product images.
+    const hasWidth = /openGraph\s*:\s*\{[\s\S]*?images\s*:\s*[\s\S]*?width\s*:\s*/.test(content);
+    const hasHeight = /openGraph\s*:\s*\{[\s\S]*?images\s*:\s*[\s\S]*?height\s*:\s*/.test(content);
+    if (hasOgImages && !usesStringImages && (!hasWidth || !hasHeight)) {
+        addIssue(issues, {
+            severity: "info",
+            file,
+            message: "Product page openGraph.images objects should ideally include width/height",
+        });
+    }
+    const derivesAbsoluteUrl = /new\s+URL\(\s*[^,]+,\s*SITE_URL\s*\)/.test(content);
+    if (!derivesAbsoluteUrl && !/https?:\/\//.test(content)) {
+        addIssue(issues, {
+            severity: "warning",
+            file,
+            message: "Could not confirm OG image URLs are absolute (prefer new URL(image, SITE_URL))",
+        });
+    }
+    return issues;
+}
+function checkRobotsAndSitemapSafety() {
+    const issues = [];
+    const robotsPath = path.join(process.cwd(), "app/robots.ts");
+    if (!fs.existsSync(robotsPath)) {
+        addIssue(issues, {
+            severity: "warning",
+            file: "app/robots.ts",
+            message: "Missing app/robots.ts",
+        });
+    }
+    else {
+        const content = readText(robotsPath);
+        // Environment-aware behavior: non-prod should default to disallow all crawling.
+        // We expect an explicit staging/dev guard (ex: IS_STAGING) that returns disallow: '/'.
+        const hasEnvGuard = /IS_STAGING|VERCEL_ENV|NODE_ENV/.test(content);
+        if (!hasEnvGuard) {
+            addIssue(issues, {
+                severity: "warning",
+                file: "app/robots.ts",
+                message: "robots.ts should be environment-aware (non-prod should default to disallow crawling)",
+            });
+        }
+        const hasStagingDisallowAll = /if\s*\(\s*IS_STAGING\s*\)[\s\S]*?disallow\s*:\s*['"]\/["']/.test(content);
+        if (hasEnvGuard && !hasStagingDisallowAll) {
+            addIssue(issues, {
+                severity: "warning",
+                file: "app/robots.ts",
+                message: "robots.ts should disallow '/' in staging/dev guard to prevent indexing",
+            });
+        }
+        if (content.includes("'/_next/'") || content.includes('"/_next/"')) {
+            addIssue(issues, {
+                severity: "blocking",
+                file: "app/robots.ts",
+                message: "robots.ts disallows /_next/ (Googlebot cannot render CSS/JS)",
+            });
+        }
+        if (content.includes("'/static/'") || content.includes('"/static/"')) {
+            addIssue(issues, {
+                severity: "blocking",
+                file: "app/robots.ts",
+                message: "robots.ts disallows /static/ (Googlebot cannot fetch static assets)",
+            });
+        }
+        if (/disallow.*['"]\/stores\//i.test(content)) {
+            addIssue(issues, {
+                severity: "blocking",
+                file: "app/robots.ts",
+                message: "robots.ts blocks /stores/ (public seller profiles)",
+            });
+        }
+    }
+    const sitemapPath = path.join(process.cwd(), "app/sitemap.ts");
+    if (!fs.existsSync(sitemapPath)) {
+        addIssue(issues, {
+            severity: "warning",
+            file: "app/sitemap.ts",
+            message: "Missing app/sitemap.ts",
+        });
+    }
+    else {
+        const content = readText(sitemapPath);
+        // Fake freshness / poor caching signal
+        if (/lastModified\s*:\s*new\s+Date\(\)/.test(content)) {
+            addIssue(issues, {
+                severity: "warning",
+                file: "app/sitemap.ts",
+                message: "Sitemap uses lastModified: new Date() (can create fake freshness + churn)",
+            });
+        }
+        // Quick sanity check that product sitemap pagination exists if expected.
+        const hasSitemapProductsRoute = fs.existsSync(path.join(process.cwd(), "app/sitemap-products-[page]/route.ts"));
+        if (!hasSitemapProductsRoute) {
+            addIssue(issues, {
+                severity: "info",
+                file: "app/sitemap-products-[page]/route.ts",
+                message: "No sitemap-products-[page] route found (consider sitemap index/pagination for large catalogs)",
+            });
+        }
+    }
+    return issues;
+}
+function checkStructuredDataGenerators() {
+    const issues = [];
+    const schemaFile = "lib/product-schema.ts";
+    const schemaPath = path.join(process.cwd(), schemaFile);
+    if (!fs.existsSync(schemaPath)) {
+        addIssue(issues, {
+            severity: "warning",
+            file: schemaFile,
+            message: "Missing lib/product-schema.ts (cannot validate Product/Breadcrumb schema shapes)",
+        });
+        return issues;
+    }
+    const content = readText(schemaPath);
+    const mustContain = (needle, message) => {
+        if (!content.includes(needle)) {
+            addIssue(issues, {
+                severity: "blocking",
+                file: schemaFile,
+                message,
+            });
+        }
+    };
+    // Product schema must contain key fields for Merchant / rich results.
+    mustContain('"@type": "Product"', "generateProductSchema should emit @type=Product");
+    mustContain('"@context": "https://schema.org"', "generateProductSchema should emit @context=https://schema.org");
+    mustContain("offers:", "generateProductSchema should emit offers");
+    mustContain('"@type": "Offer"', "generateProductSchema should emit individual Offer entries");
+    mustContain("priceCurrency", "Offer/AggregateOffer should include priceCurrency");
+    mustContain("availability", "Offer should include availability");
+    mustContain("url:", "Offer should include url");
+    // BreadcrumbList schema must use ListItem wrappers.
+    mustContain('"@type": "BreadcrumbList"', "generateBreadcrumbSchema should emit @type=BreadcrumbList");
+    mustContain("itemListElement", "BreadcrumbList should include itemListElement");
+    mustContain('"@type": "ListItem"', "Breadcrumb itemListElement entries should be ListItem");
+    mustContain("position", "Breadcrumb ListItem should include position");
+    mustContain("name", "Breadcrumb ListItem should include name");
+    mustContain("item", "Breadcrumb ListItem should include item URL");
+    return issues;
+}
+async function checkCrawlableInternalLinking() {
+    const issues = [];
+    // Product pages should expose crawlable internal links to related items.
+    const productPagePath = path.join(process.cwd(), "app/product/[slug]/page.tsx");
+    if (fs.existsSync(productPagePath)) {
+        const content = readText(productPagePath);
+        const usesRelatedProductsComponent = /<RelatedProducts\b/.test(content);
+        const mentionsRelated = usesRelatedProductsComponent ||
+            /Related\s+Products|You\s+may\s+also\s+like|Similar\s+items/i.test(content);
+        // Note: The product page uses a server component (`components/product/RelatedProducts.tsx`)
+        // that renders crawlable <Link href="/product/..."> anchors. This check is best-effort
+        // and should not false-positive when the component is present.
+        const hasProductLinks = usesRelatedProductsComponent ||
+            /<Link[^>]+href=\{?['"]\/product\//.test(content) ||
+            /href=\{?`\$\{.*\}\/product\//.test(content);
+        if (!mentionsRelated) {
+            addIssue(issues, {
+                severity: "info",
+                file: "app/product/[slug]/page.tsx",
+                message: "Product page does not appear to render a related-products section (helps internal linking + discovery)",
+            });
+        }
+        if (mentionsRelated && !hasProductLinks) {
+            addIssue(issues, {
+                severity: "warning",
+                file: "app/product/[slug]/page.tsx",
+                message: "Related-products section detected but no obvious crawlable /product/ links found",
+            });
+        }
+    }
+    // Category pages should avoid JS-only navigation for key lists (best-effort scan).
+    const categoryPages = await (0, glob_1.glob)("app/{sports-cards,trading-card-games,video-games,autographs,tickets,non-sports-cards}/**/page.tsx", {
+        ignore: EXCLUDED_GLOBS,
+    });
+    for (const file of categoryPages) {
+        const content = readText(path.join(process.cwd(), file));
+        const hasRouterPush = /router\.push\(/.test(content);
+        const hasLink = /<Link\b/.test(content);
+        if (hasRouterPush && !hasLink) {
+            addIssue(issues, {
+                severity: "info",
+                file,
+                message: "Category page uses router.push without obvious <Link> usage (ensure crawlable anchors for SEO)",
+            });
+        }
+    }
+    return issues;
+}
+function normalizeResult(issues, strict) {
+    const errors = [];
+    const warnings = [];
+    const info = [];
+    for (const issue of issues) {
+        const msg = formatIssue(issue);
+        if (issue.severity === "blocking") {
+            if (strict)
+                errors.push(msg);
+            else
+                warnings.push(`[BLOCKING] ${msg}`);
+        }
+        else if (issue.severity === "warning") {
+            warnings.push(msg);
+        }
+        else {
+            info.push(msg);
+        }
+    }
+    return {
+        passed: errors.length === 0,
+        errors,
+        warnings,
+        info: info.length > 0 ? info : undefined,
+    };
+}
+async function run(options = {}) {
+    const strict = options.strict ?? false;
+    const verbose = options.verbose ?? false;
+    const ci = options.ci ?? false;
+    const issues = [];
+    const rootLayoutPath = path.join(process.cwd(), "app/layout.tsx");
+    const hasRootMetadataBase = fs.existsSync(rootLayoutPath)
+        ? /metadataBase\s*:/.test(readText(rootLayoutPath))
+        : false;
+    // 1) Root layout SEO defaults
+    issues.push(...checkRootLayoutMetadata());
+    // 1b) Structured data shape validation (static, generator-level)
+    issues.push(...checkStructuredDataGenerators());
+    // 1c) Structured data runtime serializability (sample outputs must JSON.stringify + JSON.parse)
+    issues.push(...(await checkSchemaGeneratorSerializability()));
+    // 2) Metadata presence & basic quality
+    {
+        const metadataIssues = await checkMetadataPresenceAndQuality({ strict });
+        issues.push(...metadataIssues);
+        // Additional metadata URL correctness checks are derived from the same AST analysis.
+        // (We keep them separate to avoid bloating the main metadata quality loop.)
+        const pageFiles = await getPageTsFiles();
+        for (const file of pageFiles) {
+            const content = readText(path.join(process.cwd(), file));
+            const analysis = analyzeNextMetadata(content, file);
+            issues.push(...checkMetadataUrlCorrectness({
+                file,
+                analysis,
+                strict,
+                ci,
+                hasRootMetadataBase,
+            }));
+        }
+    }
+    // 3) OG correctness on product page
+    issues.push(...checkProductOGType());
+    // 4) Robots + sitemap safety rails
+    issues.push(...checkRobotsAndSitemapSafety());
+    // 5) Crawlable internal linking depth heuristics
+    issues.push(...(await checkCrawlableInternalLinking()));
+    // 5b) Caching guardrails for public pages (force-dynamic without caching)
+    issues.push(...(await checkForceDynamicCaching({ strict, ci })));
+    // 5c) Pagination metadata heuristics for public pages
+    issues.push(...(await checkPaginationMetadataHeuristics({ strict, ci })));
+    // 5d) Semantic heading enforcement for top-level headings
+    issues.push(...(await checkTypographyHeadingSemantics({ strict, ci })));
+    // 5e) Image + alt-text guardrails on public surfaces
+    issues.push(...(await checkNativeImgAndAltText({ strict, ci })));
+    // 6) Run legacy, battle-tested SEO checks as child processes
+    // NOTE: In non-strict mode, failures are downgraded to warnings so the main
+    // preflight system can treat SEO as "warnOn".
+    const childChecks = [
+        {
+            label: "SEO Best Practices",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/seo-best-practices.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "Heading Hierarchy",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/heading-hierarchy-validation.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "Schema Usage",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/schema-usage-validation.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "Hardcoded URLs",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/hardcoded-urls.js"],
+            alwaysWarn: false,
+        },
+        {
+            label: "SEO Gaps",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/seo-gaps-validation.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "Category FAQ Schema",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/category-faq-schema-validation.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "Store Local SEO",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/store-local-seo-validation.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "JSON-LD Validation",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/json-ld-validation.js"],
+            alwaysWarn: true,
+        },
+        {
+            label: "Social Meta Tags",
+            command: process.execPath,
+            args: ["scripts/active/preflights/seo/social-meta-validation.js"],
+            alwaysWarn: true,
+        },
+    ];
+    const childPromises = childChecks.map((check) => runScriptAsChildProcess({
+        command: check.command,
+        args: check.args,
+        label: check.label,
+        strict,
+        verbose,
+        alwaysWarn: check.alwaysWarn,
+    }));
+    const childResults = await Promise.all(childPromises);
+    for (const childIssues of childResults) {
+        issues.push(...childIssues);
+    }
+    return normalizeResult(issues, strict);
+}
+function isDirectCliInvocation() {
+    return require.main === module;
+}
+async function runAsCli() {
+    const strict = process.argv.includes("--strict");
+    const verbose = process.argv.includes("--verbose");
+    const ci = process.argv.includes("--ci") || process.argv.includes("--enforce-best-practices");
+    console.log(`\n${console_chars_1.emoji.search} Running SEO Preflight (authoritative)...\n`);
+    const result = await run({ strict, verbose, ci });
+    if (result.errors.length > 0) {
+        console.log(`${console_chars_1.emoji.error} Errors:\n`);
+        result.errors.forEach((e) => console.log(`  - ${e}`));
+        console.log("");
+    }
+    if (result.warnings.length > 0) {
+        console.log(`${console_chars_1.emoji.warning}  Warnings:\n`);
+        const maxLines = verbose ? result.warnings.length : 30;
+        result.warnings.slice(0, maxLines).forEach((w) => console.log(`  - ${w}`));
+        if (!verbose && result.warnings.length > maxLines) {
+            console.log(`  - ${console_chars_1.chars.ellipsis}and ${result.warnings.length - maxLines} more (re-run with --verbose)`);
+        }
+        console.log("");
+    }
+    if (result.info && result.info.length > 0 && verbose) {
+        console.log(`${console_chars_1.emoji.info}  Info:\n`);
+        result.info.forEach((i) => console.log(`  - ${i}`));
+        console.log("");
+    }
+    if (result.passed) {
+        console.log(`${console_chars_1.emoji.success} SEO preflight passed\n`);
+        process.exit(0);
+    }
+    console.log(`${console_chars_1.emoji.error} SEO preflight failed\n`);
+    process.exit(1);
+}
+if (isDirectCliInvocation()) {
+    runAsCli().catch((error) => {
+        console.error(`${console_chars_1.emoji.error} SEO preflight crashed:`, error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=seo.js.map