@brandlab-digital/conformance 2.1.0 → 3.0.0

package/dist/static-rules.js

@@ -0,0 +1,762 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, posix } from "node:path";
+import ts from "typescript";
+import { globMatch } from "./glob.js";
+import { findWordingInMarkdown, findWordingInSource, isPublicDocumentPath, isPublicModulePath, parseJsonSource, } from "./public-copy.js";
+import { BRANDLAB_SOURCE_ROOT_DIRECTORIES, createBrandlabModuleResolver, findImportedCalls, importedLocalNames, isDirectory, lineAt, stripCommentsPreservingLayout, lineOfNode, listModuleReferences, objectPropertyValue, parseBrandlabSourceFile, stringLiteralValue, walkProjectFiles, } from "./source-files.js";
+const SITE_CORE = (module) => new RegExp(`^@brandlab-digital/site-core/${module}$`);
+const SITE_NEXT = (module) => new RegExp(`^@brandlab-digital/site-next/${module}$`);
+const SITE_NEXT_ANY = /^@brandlab-digital\/site-next(?:\/|$)/;
+const SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mjs"];
+export function staticFinding(options) {
+    return {
+        ruleId: options.ruleId,
+        surface: options.surface,
+        severity: options.severity ?? "blocker",
+        contract: { name: "project", version: "current-only-v2" },
+        evidenceKind: "static",
+        ...(options.path ? { path: options.path } : {}),
+        ...(options.line ? { line: options.line } : {}),
+        expected: options.expected,
+        actual: options.actual,
+        remediation: options.remediation,
+    };
+}
+export function recordEvaluation(evaluations, surface, ...ruleIds) {
+    for (const ruleId of ruleIds)
+        evaluations.push({ ruleId, surface });
+}
+/** The minimal static rules behind the checks that previously passed without evidence. */
+export function inspectStaticRules(context) {
+    const project = describeProject(context);
+    inspectContactProviderRoute(context, project);
+    inspectAnalyticsPrivacy(context);
+    inspectGoogleTagOwner(context);
+    inspectSearchRouting(context, project);
+    inspectBusinessFacts(context);
+    inspectSharedBindings(context);
+    inspectRouteCatalogue(context, project);
+    inspectLocationEstate(context, project);
+    inspectImplementationWording(context);
+    inspectPlatformReimplementation(context);
+    inspectRetiredConfiguration(context);
+    inspectWorkflowPins(context);
+    inspectVercelIgnore(context);
+}
+/** Capabilities declared by brandlab.config.ts, the contact route and the location data. */
+export function describeCapabilities(root, config) {
+    const text = config ?? "";
+    const families = text.match(/\bfamilies\s*:\s*\[([^\]]*)\]/)?.[1] ?? "";
+    const strategy = text.match(/\blocations\s*:\s*\{[^{}]*\bstrategy\s*:\s*['"]([a-z-]+)['"]/)?.[1];
+    return {
+        contactEnabled: /\bcontact\s*:\s*\{/.test(text) ||
+            routeCandidates("api/contact/route").some((path) => existsSync(join(root, path))),
+        reviewsEnabled: /\breviews\s*:\s*\{/.test(text),
+        locationsDeclared: /['"](?:locations|service-locations)['"]/.test(families) ||
+            (strategy !== undefined && strategy !== "none") ||
+            isDirectory(join(root, "src/data/locations")),
+        sitemapMode: (text.match(/\bsitemap\s*:\s*\{[^{}]*\bmode\s*:\s*['"](single|split)['"]/)?.[1] ??
+            null),
+    };
+}
+function describeProject(context) {
+    const capabilities = describeCapabilities(context.root, context.config);
+    return {
+        ...capabilities,
+        contactEnabled: capabilities.contactEnabled || findContactContractRecipients(context.source).length > 0,
+        resolver: createBrandlabModuleResolver(context.root, new Set(context.source.byPath.keys())),
+        catalogueFiles: context.source.files
+            .filter((file) => findImportedCalls(file, SITE_CORE("routes"), "defineRouteCatalog").length > 0)
+            .map((file) => file.path),
+    };
+}
+// --- contact-provider-errors -------------------------------------------------
+function inspectContactProviderRoute(context, project) {
+    if (!project.contactEnabled)
+        return;
+    const ruleId = "brandlab-contact-provider-route";
+    recordEvaluation(context.evaluations, "contact", ruleId);
+    const expected = "POST /api/contact produced by the shared handler (createBrandlabContactRouteHandler, or createBrandlabContactRuntime during transition)";
+    const remediation = "Export POST = createBrandlabContactRouteHandler({ contract, runtime }) from @brandlab-digital/site-next/contact/server.";
+    const route = firstExisting(context, routeCandidates("api/contact/route"));
+    if (!route) {
+        context.findings.push(staticFinding({
+            ruleId, surface: "contact", path: "src/app/api/contact/route.ts", expected, remediation,
+            actual: "The contact capability is enabled but src/app/api/contact/route.ts is missing.",
+        }));
+        return;
+    }
+    const file = context.source.byPath.get(route);
+    if (!file || !exportedNames(file).has("POST")) {
+        context.findings.push(staticFinding({
+            ruleId, surface: "contact", path: route, expected, remediation,
+            actual: "The contact route does not export a POST handler.",
+        }));
+        return;
+    }
+    const contactServer = SITE_NEXT("contact/server");
+    const direct = findImportedCalls(file, contactServer, "createBrandlabContactRouteHandler").length > 0;
+    const runtimeModules = [file, ...localImports(context, project.resolver, file)];
+    const transitional = /\.contactRouteHandler\b/.test(file.executable) &&
+        runtimeModules.some((candidate) => findImportedCalls(candidate, contactServer, "createBrandlabContactRuntime").length > 0);
+    if (!direct && !transitional) {
+        context.findings.push(staticFinding({
+            ruleId, surface: "contact", path: route, expected, remediation,
+            actual: "The POST handler is not created by the shared contact runtime, so provider errors are project-owned.",
+        }));
+    }
+}
+// --- analytics-privacy -------------------------------------------------------
+const ANALYTICS_SINKS = new Set([
+    "gtag", "window.gtag", "globalThis.gtag",
+    "dataLayer.push", "window.dataLayer.push", "globalThis.dataLayer.push",
+    "sendGAEvent", "sendGTMEvent", "trackBrandlabBrowserEvent", "trackBrandlabEvent", "ReactGA.event",
+]);
+const PII_TOKENS = new Set([
+    "attachment", "attachment_name", "contact_email", "contact_name", "customer_name", "email",
+    "email_address", "enquiry_message", "file_name", "filename", "first_name", "form_message",
+    "full_name", "last_name", "message", "mobile", "mobile_number", "phone", "phone_number",
+    "residential_address", "street_address", "user_email", "user_phone",
+]);
+function inspectAnalyticsPrivacy(context) {
+    if (context.source.files.length === 0)
+        return;
+    const ruleId = "brandlab-analytics-pii-payload";
+    recordEvaluation(context.evaluations, "analytics", ruleId);
+    for (const file of context.source.files) {
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && ANALYTICS_SINKS.has(memberPath(node.expression) ?? "")) {
+                const userData = stringLiteralValue(node.arguments[0]) === "set" &&
+                    stringLiteralValue(node.arguments[1]) === "user_data" &&
+                    node.arguments[2] && !(ts.isObjectLiteralExpression(node.arguments[2]) && node.arguments[2].properties.length === 0);
+                const piiNode = userData ? node.arguments[2] : node.arguments.map(findPiiNode).find(Boolean);
+                if (piiNode) {
+                    context.findings.push(staticFinding({
+                        ruleId,
+                        surface: "analytics",
+                        path: file.path,
+                        line: lineOfNode(file, piiNode),
+                        expected: "Analytics payloads carry only the shared allowlisted, non-identifying parameters",
+                        actual: userData
+                            ? "Project code sets Google user_data; enhanced conversion data is owned by the shared runtime."
+                            : "A lead contact field, message or attachment detail reaches an analytics payload.",
+                        remediation: "Send events through the shared Brandlab analytics runtime without lead details.",
+                    }));
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(parseBrandlabSourceFile(file));
+    }
+}
+function findPiiNode(node) {
+    if (!node)
+        return undefined;
+    if (ts.isObjectLiteralExpression(node)) {
+        for (const property of node.properties) {
+            if (ts.isShorthandPropertyAssignment(property) && isPiiToken(property.name.text))
+                return property;
+            if (ts.isSpreadAssignment(property) && isPiiReference(property.expression))
+                return property;
+            if (!ts.isPropertyAssignment(property))
+                continue;
+            const key = ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name) ? property.name.text : null;
+            if ((key && isPiiToken(key)) || isPiiReference(property.initializer))
+                return property;
+            const nested = findPiiNode(property.initializer);
+            if (nested)
+                return nested;
+        }
+        return undefined;
+    }
+    if (ts.isArrayLiteralExpression(node))
+        return node.elements.map(findPiiNode).find(Boolean);
+    return isPiiReference(node) ? node : undefined;
+}
+function isPiiReference(node) {
+    if (ts.isIdentifier(node))
+        return isPiiToken(node.text);
+    if (ts.isPropertyAccessExpression(node))
+        return isPiiToken(node.name.text);
+    if (ts.isTemplateExpression(node))
+        return node.templateSpans.some((span) => isPiiReference(span.expression));
+    return false;
+}
+function isPiiToken(value) {
+    return PII_TOKENS.has(value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().replace(/[^a-z0-9]+/g, "_"));
+}
+function memberPath(node) {
+    if (ts.isIdentifier(node))
+        return node.text;
+    if (ts.isPropertyAccessExpression(node)) {
+        const object = memberPath(node.expression);
+        return object ? `${object}.${node.name.text}` : null;
+    }
+    return null;
+}
+// --- analytics-conversion: one Google tag owner ------------------------------
+function inspectGoogleTagOwner(context) {
+    if (context.source.files.length === 0)
+        return;
+    const ruleId = "brandlab-analytics-google-tag-owner";
+    recordEvaluation(context.evaluations, "analytics", ruleId);
+    const usages = context.source.files.flatMap((file) => {
+        const locals = new Set(importedLocalNames(file, SITE_NEXT_ANY, "BrandlabGoogleTag"));
+        if (locals.size === 0)
+            return [];
+        const found = [];
+        const visit = (node) => {
+            if ((ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) &&
+                ts.isIdentifier(node.tagName) &&
+                locals.has(node.tagName.text)) {
+                found.push({ path: file.path, line: lineOfNode(file, node) });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(parseBrandlabSourceFile(file));
+        return found;
+    });
+    const rootLayouts = new Set(routeCandidates("layout").filter((path) => context.source.byPath.has(path)));
+    const expected = "Exactly one <BrandlabGoogleTag /> rendered from the root layout (src/app/layout.tsx)";
+    const remediation = "Render BrandlabGoogleTag once, directly in src/app/layout.tsx, and remove wrappers or duplicates.";
+    if (usages.length === 1 && rootLayouts.has(usages[0].path))
+        return;
+    context.findings.push(staticFinding({
+        ruleId,
+        surface: "analytics",
+        ...(usages[0] ? { path: usages[0].path, line: usages[0].line } : { path: "src/app/layout.tsx" }),
+        expected,
+        actual: usages.length === 0
+            ? "No BrandlabGoogleTag is rendered, so the shared tag and its events are absent."
+            : usages.length > 1
+                ? `BrandlabGoogleTag is rendered ${usages.length} times (${usages.map(({ path, line }) => `${path}:${line}`).join(", ")}).`
+                : "BrandlabGoogleTag is rendered outside the root layout.",
+        remediation,
+    }));
+}
+// --- search-routing ----------------------------------------------------------
+function inspectSearchRouting(context, project) {
+    if (context.source.directoryRoots.length === 0)
+        return;
+    inspectPackageRoute(context, project, {
+        ruleId: "brandlab-robots-package-route",
+        surface: "robots",
+        candidates: routeCandidates("robots"),
+        staticFile: "public/robots.txt",
+        modules: [SITE_NEXT("robots")],
+        packageLabel: "@brandlab-digital/site-next/robots",
+        needsCatalogue: false,
+    });
+    inspectPackageRoute(context, project, {
+        ruleId: "brandlab-sitemap-package-route",
+        surface: "sitemap",
+        candidates: [...routeCandidates("sitemap.xml/route"), ...routeCandidates("sitemap")],
+        staticFile: "public/sitemap.xml",
+        modules: [SITE_NEXT("sitemaps"), SITE_CORE("sitemaps")],
+        packageLabel: "@brandlab-digital/site-next/sitemaps",
+        needsCatalogue: true,
+    });
+    inspectSitemapMode(context, project);
+    inspectMetadataBuilder(context, project);
+}
+function inspectPackageRoute(context, project, rule) {
+    recordEvaluation(context.evaluations, rule.surface, rule.ruleId);
+    const expected = `The ${rule.surface} route is a thin binding of ${rule.packageLabel}${rule.needsCatalogue ? " over the route catalogue" : ""}`;
+    const remediation = `Serve ${rule.surface} from ${rule.candidates[0]} using ${rule.packageLabel}${rule.needsCatalogue ? " and the routes from src/data/routes.ts" : ""}.`;
+    const report = (actual, path) => context.findings.push(staticFinding({
+        ruleId: rule.ruleId, surface: rule.surface, path, expected, actual, remediation,
+    }));
+    if (existsSync(join(context.root, rule.staticFile))) {
+        report(`${rule.staticFile} bypasses the environment-aware shared ${rule.surface} output.`, rule.staticFile);
+    }
+    const route = firstExisting(context, rule.candidates);
+    const file = route ? context.source.byPath.get(route) : undefined;
+    if (!route || !file) {
+        report(`No ${rule.surface} route was found.`, rule.candidates[0]);
+        return;
+    }
+    const references = listModuleReferences(file);
+    if (!references.some((reference) => rule.modules.some((module) => module.test(reference.specifier)))) {
+        report(`${route} does not use ${rule.packageLabel}.`, route);
+        return;
+    }
+    if (rule.needsCatalogue && project.catalogueFiles.length > 0 && !reachesCatalogue(context, project, file)) {
+        report(`${route} does not read the route catalogue.`, route);
+    }
+}
+function inspectSitemapMode(context, project) {
+    if (!project.sitemapMode)
+        return;
+    const ruleId = "brandlab-sitemap-split-mode";
+    recordEvaluation(context.evaluations, "sitemap", ruleId);
+    const chunkRoute = ["src/app/sitemaps", "app/sitemaps"].find((path) => isDirectory(join(context.root, path)));
+    if (project.sitemapMode === "split" ? chunkRoute : !chunkRoute)
+        return;
+    context.findings.push(staticFinding({
+        ruleId,
+        surface: "sitemap",
+        path: chunkRoute ?? "brandlab.config.ts",
+        expected: "/sitemaps/[chunk] exists only when brandlab.config sets sitemap.mode: 'split'",
+        actual: project.sitemapMode === "split"
+            ? "sitemap.mode is 'split' but no /sitemaps/[chunk] route exists."
+            : `sitemap.mode is 'single' but ${chunkRoute} still serves sitemap chunks.`,
+        remediation: "Keep the sitemap routes and brandlab.config sitemap.mode in agreement.",
+    }));
+}
+function inspectMetadataBuilder(context, project) {
+    const ruleId = "brandlab-metadata-route-builder";
+    recordEvaluation(context.evaluations, "metadata", ruleId);
+    const builders = context.source.files.filter((file) => findImportedCalls(file, SITE_NEXT("metadata"), "createRouteMetadataBuilder").length > 0);
+    const expected = "Page metadata built by createRouteMetadataBuilder(site, routes) from @brandlab-digital/site-next/metadata";
+    const remediation = "Bind pageMetadata = createRouteMetadataBuilder(site, routes) in src/lib/seo/metadata.ts.";
+    if (builders.length === 0) {
+        context.findings.push(staticFinding({
+            ruleId, surface: "metadata", path: "src/lib/seo/metadata.ts", expected, remediation,
+            actual: "No module builds page metadata with createRouteMetadataBuilder.",
+        }));
+        return;
+    }
+    if (project.catalogueFiles.length === 0)
+        return;
+    for (const builder of builders.filter((file) => !reachesCatalogue(context, project, file))) {
+        context.findings.push(staticFinding({
+            ruleId, surface: "metadata", path: builder.path, expected, remediation,
+            actual: "The metadata builder does not read the route catalogue.",
+        }));
+    }
+}
+function reachesCatalogue(context, project, file) {
+    const catalogues = new Set(project.catalogueFiles);
+    const seen = new Set([file.path]);
+    let frontier = [file];
+    for (let depth = 0; depth < 4 && frontier.length > 0; depth += 1) {
+        const next = [];
+        for (const current of frontier) {
+            for (const imported of localImports(context, project.resolver, current)) {
+                if (catalogues.has(imported.path))
+                    return true;
+                if (seen.has(imported.path))
+                    continue;
+                seen.add(imported.path);
+                next.push(imported);
+            }
+        }
+        frontier = next;
+    }
+    return false;
+}
+// --- business-identity and route-identity ------------------------------------
+function inspectBusinessFacts(context) {
+    if (context.source.files.length === 0)
+        return;
+    exactlyOneDefinition(context, {
+        ruleId: "brandlab-business-facts",
+        surface: "business",
+        module: SITE_CORE("business"),
+        name: "defineBrandlabBusiness",
+        expectedPath: "src/data/business.ts",
+        subject: "Business facts",
+    });
+}
+/** The one-owner 3.0 bindings: site identity, redirects, analytics, next.config and instrumentation. */
+function inspectSharedBindings(context) {
+    if (context.source.files.length === 0)
+        return;
+    exactlyOneDefinition(context, {
+        ruleId: "brandlab-site-identity",
+        surface: "metadata",
+        module: SITE_CORE("site"),
+        name: "defineBrandlabSite",
+        expectedPath: "src/config/site.ts",
+        subject: "The site identity",
+    });
+    exactlyOneDefinition(context, {
+        ruleId: "brandlab-redirects-table",
+        surface: "routes",
+        module: SITE_CORE("redirects"),
+        name: "defineRedirects",
+        expectedPath: "src/data/redirects.ts",
+        subject: "The redirect table",
+    });
+    exactlyOneDefinition(context, {
+        ruleId: "brandlab-analytics-contract",
+        surface: "analytics",
+        module: SITE_NEXT("analytics"),
+        name: "defineBrandlabAnalytics",
+        expectedPath: "src/config/analytics.ts",
+        subject: "The analytics contract",
+    });
+    requireBindingCall(context, {
+        ruleId: "brandlab-runtime-next-config",
+        surface: "runtime",
+        candidates: ["next.config.ts", "next.config.mts", "next.config.mjs", "next.config.js"],
+        module: SITE_NEXT("next-config"),
+        name: "defineBrandlabNextConfig",
+        expected: "next.config exports defineBrandlabNextConfig({ site, redirects, ... }) from @brandlab-digital/site-next/next-config",
+        consequence: "headers, image formats and Preview noindex are then project-owned",
+    });
+    requireBindingCall(context, {
+        ruleId: "brandlab-analytics-instrumentation",
+        surface: "analytics",
+        candidates: ["src/instrumentation-client.ts", "src/instrumentation-client.js", "instrumentation-client.ts", "instrumentation-client.js"],
+        module: SITE_NEXT("instrumentation-client"),
+        name: "installBrandlabInstrumentation",
+        expected: "src/instrumentation-client.ts calls installBrandlabInstrumentation(analytics)",
+        consequence: "telephone taps and the initial landing are not reported by the shared runtime",
+    });
+}
+function requireBindingCall(context, rule) {
+    recordEvaluation(context.evaluations, rule.surface, rule.ruleId);
+    const path = rule.candidates.find((candidate) => context.source.byPath.has(candidate));
+    const file = path ? context.source.byPath.get(path) : undefined;
+    if (file && findImportedCalls(file, rule.module, rule.name).length > 0)
+        return;
+    context.findings.push(staticFinding({
+        ruleId: rule.ruleId,
+        surface: rule.surface,
+        path: path ?? rule.candidates[0],
+        expected: rule.expected,
+        actual: file
+            ? `${path} does not call ${rule.name}, so ${rule.consequence}.`
+            : `${rule.candidates[0]} is missing, so ${rule.consequence}.`,
+        remediation: `Call ${rule.name} from the shared package in ${rule.candidates[0]}.`,
+    }));
+}
+function inspectRouteCatalogue(context, project) {
+    if (context.source.files.length === 0)
+        return;
+    exactlyOneDefinition(context, {
+        ruleId: "brandlab-routes-catalogue",
+        surface: "routes",
+        module: SITE_CORE("routes"),
+        name: "defineRouteCatalog",
+        expectedPath: "src/data/routes.ts",
+        subject: "The route catalogue",
+        known: project.catalogueFiles,
+    });
+}
+function exactlyOneDefinition(context, rule) {
+    recordEvaluation(context.evaluations, rule.surface, rule.ruleId);
+    const owners = rule.known ?? context.source.files
+        .filter((file) => findImportedCalls(file, rule.module, rule.name).length > 0)
+        .map((file) => file.path);
+    if (owners.length === 1)
+        return;
+    context.findings.push(staticFinding({
+        ruleId: rule.ruleId,
+        surface: rule.surface,
+        path: owners[0] ?? rule.expectedPath,
+        expected: `${rule.subject} declared once with ${rule.name}`,
+        actual: owners.length === 0
+            ? `No module calls ${rule.name}.`
+            : `${rule.name} is called in ${owners.length} modules: ${owners.join(", ")}.`,
+        remediation: `Keep one ${rule.name} owner in ${rule.expectedPath} and import it everywhere else.`,
+    }));
+}
+function inspectLocationEstate(context, project) {
+    if (!project.locationsDeclared)
+        return;
+    const ruleId = "brandlab-routes-location-estate";
+    recordEvaluation(context.evaluations, "routes", ruleId);
+    const estate = firstExisting(context, SOURCE_EXTENSIONS.slice(0, 2).map((extension) => `src/data/locations/estate.${extension}`));
+    const file = estate ? context.source.byPath.get(estate) : undefined;
+    if (file && findImportedCalls(file, SITE_CORE("locations"), "defineLocationEstate").length > 0)
+        return;
+    context.findings.push(staticFinding({
+        ruleId,
+        surface: "routes",
+        path: estate ?? "src/data/locations/estate.ts",
+        expected: "The published location list declared once in src/data/locations/estate.ts with defineLocationEstate",
+        actual: file
+            ? "src/data/locations/estate.ts does not declare the estate with defineLocationEstate."
+            : "The project publishes locations but has no src/data/locations/estate.ts.",
+        remediation: "Declare the published locations, retained exclusions and any site-owned locations with defineLocationEstate as literal data.",
+    }));
+}
+// --- public-output-safety ----------------------------------------------------
+/** Directories that can hold public content documents (MDX, Markdown and JSON data). */
+const DOCUMENT_ROOTS = [...BRANDLAB_SOURCE_ROOT_DIRECTORIES, "content", "posts"];
+/**
+ * Implementation wording in anything that can render publicly: JSX text, rendered
+ * attributes (alt, title, aria-label and component copy props), copy-bearing string
+ * literals in pages, components, metadata, schema, configuration and data, MDX and
+ * Markdown content with its frontmatter, and JSON data. Class lists, styles, import
+ * paths, keys, types, comparisons, errors and console output are code, not copy.
+ */
+function inspectImplementationWording(context) {
+    const modules = context.source.files.filter((file) => isPublicModulePath(file.path));
+    const documents = [...new Set(DOCUMENT_ROOTS)]
+        .flatMap((directory) => walkProjectFiles(context.root, directory))
+        .filter(isPublicDocumentPath);
+    if (modules.length === 0 && documents.length === 0)
+        return;
+    const ruleId = "brandlab-content-implementation-wording";
+    recordEvaluation(context.evaluations, "content", ruleId);
+    const report = (path, finding) => {
+        context.findings.push(staticFinding({
+            ruleId,
+            surface: "content",
+            path,
+            line: finding.line,
+            expected: "Publicly rendered copy is finished customer copy, not implementation wording",
+            actual: `Implementation-facing wording (${finding.pattern.source}) appears in ${finding.where}.`,
+            remediation: "Replace the wording with the finished customer copy before it can render publicly.",
+        }));
+    };
+    for (const file of modules) {
+        for (const finding of findWordingInSource(parseBrandlabSourceFile(file)))
+            report(file.path, finding);
+    }
+    for (const path of documents) {
+        const text = readFileSync(join(context.root, path), "utf8");
+        const findings = path.endsWith(".json")
+            ? findWordingInSource(parseJsonSource(path, text))
+            : findWordingInMarkdown(text);
+        for (const finding of findings)
+            report(path, finding);
+    }
+}
+// --- source-safety -----------------------------------------------------------
+/** Shared platform surfaces a project must import rather than declare. */
+const PROTECTED_PLATFORM_NAMES = new Set([
+    "BrandlabBreadcrumbs", "BrandlabGoogleTag", "ContactFormEmail", "SafeRichText", "SchemaScript",
+    "buildBrandlabMetadata", "buildLocalBusinessSchema", "buildNextMetadata", "buildRobotsMetadata",
+    "buildSchemaGraph", "buildSitemapEntries", "createBrandlabContactRouteHandler",
+    "createBrandlabContactRuntime", "createBrandlabRobots", "createBrandlabSitemapRoute",
+    "createNextMetadataBuilder", "createRouteAwareMdxBlogAdapter", "createRouteAwareStructuredBlogAdapter",
+    "createRouteMetadataBuilder", "defineAnalyticsContract", "defineBrandlabAnalytics",
+    "defineBrandlabBusiness", "defineBrandlabContact", "defineBrandlabNextConfig", "defineBrandlabProject",
+    "defineBrandlabSite", "defineBreadcrumbTrail", "defineContactContract", "defineLocationEstate",
+    "defineRedirects", "defineRouteCatalog", "installBrandlabInstrumentation", "installPhoneClickListener",
+    "renderContactEmail", "sitemapIndexXmlResponse", "sitemapXmlResponse", "trackBrandlabBrowserEvent",
+    "useBrandlabContactForm",
+]);
+/** Package exports removed in 3.0.0 (web-vitals APIs are reported by the analytics rule). */
+const RETIRED_PACKAGE_EXPORTS = [
+    "TrackedTelephoneLink", "shouldIndexSite", "buildRobotsMetadata", "buildSeoMetadata", "buildNextMetadata",
+    "buildBrandlabNextMetadata", "createNextMetadataBuilder", "createBrandlabNextMetadataBuilder",
+    "isBrandlabProductionDeployment", "resolveBrowserAnalyticsConfig", "resolveBrandlabGoogleTagConfig",
+    "BRANDLAB_NEXT_HEADER_PROFILES", "createContactHttpSubmissionController", "trackDeliveredContactResult",
+    "trackDeliveredContactWithEnhancedConversions", "trackDeliveredContact", "shouldTrackContactResult",
+    "isTrackableContactActionResult",
+];
+/** APIs, options and paths removed in 3.0.0; their presence means an unfinished migration. */
+const RETIRED_SOURCE_APIS = [
+    ...RETIRED_PACKAGE_EXPORTS.map((name) => ({ pattern: new RegExp(`\\b${name}\\b`), label: name })),
+    { pattern: /\bALLOW_INDEXING\b/, label: "the ALLOW_INDEXING override" },
+    { pattern: /\bNEXT_PUBLIC_SITE_URL\b/, label: "NEXT_PUBLIC_SITE_URL" },
+    {
+        pattern: /\bbuildBrandlabHeaderRules\s*\(\s*\{[^}]*\b(?:isProduction|profile)\b/,
+        label: "buildBrandlabHeaderRules({ isProduction, profile }) (pass the deployment instead)",
+    },
+    { pattern: /\b(?:xRobotsTag|contentSecurityPolicyMode)\s*:/, label: "the xRobotsTag or contentSecurityPolicyMode header option" },
+    { pattern: /\bleadDiagnostics\s*:/, label: "the leadDiagnostics flag (lead diagnostics are always sent)" },
+];
+function inspectPlatformReimplementation(context) {
+    if (context.source.files.length === 0)
+        return;
+    const reimplementation = "brandlab-source-platform-reimplementation";
+    const retired = "brandlab-source-retired-api";
+    recordEvaluation(context.evaluations, "source", reimplementation, retired);
+    for (const file of context.source.files) {
+        const declared = declaredProtectedNames(file);
+        if (declared) {
+            context.findings.push(staticFinding({
+                ruleId: reimplementation,
+                surface: "source",
+                path: file.path,
+                line: declared.line,
+                expected: "Protected Brandlab platform surfaces are imported from the shared packages",
+                actual: `${declared.name} is declared locally instead of imported from the shared packages.`,
+                remediation: `Import ${declared.name} from @brandlab-digital/site-core or site-next and remove the local copy.`,
+            }));
+        }
+        for (const api of RETIRED_SOURCE_APIS) {
+            const match = file.executable.match(api.pattern);
+            if (!match || match.index === undefined)
+                continue;
+            context.findings.push(staticFinding({
+                ruleId: retired,
+                surface: "source",
+                path: file.path,
+                line: lineAt(file.text, match.index),
+                expected: "Only current 3.0 platform APIs",
+                actual: `The project still uses ${api.label}, which 3.0 removed.`,
+                remediation: "Migrate the caller to the current shared API and delete the retired path.",
+            }));
+        }
+    }
+}
+function declaredProtectedNames(file) {
+    const source = parseBrandlabSourceFile(file);
+    for (const statement of source.statements) {
+        const names = [];
+        if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) {
+            names.push({ name: statement.name.text, node: statement.name });
+        }
+        else if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    names.push({ name: declaration.name.text, node: declaration.name });
+            }
+        }
+        const protectedName = names.find(({ name }) => PROTECTED_PLATFORM_NAMES.has(name));
+        if (protectedName)
+            return { name: protectedName.name, line: lineOfNode(file, protectedName.node) };
+    }
+    return null;
+}
+/** Project configuration keys removed in 3.0.0. */
+const RETIRED_CONFIG_KEYS = [
+    {
+        pattern: /\broutes\s*:\s*\{[^{}]*\baliases\s*:/,
+        key: "aliases",
+        label: "routes.aliases",
+        remediation: "Move each alias into the redirect table in src/data/redirects.ts.",
+    },
+    {
+        pattern: /\bprofile\s*:/,
+        key: "profile",
+        label: "the profile field",
+        remediation: "Delete the profile field; defineBrandlabProject rejects unknown keys.",
+    },
+];
+function inspectRetiredConfiguration(context) {
+    if (!context.config)
+        return;
+    const ruleId = "brandlab-source-retired-api";
+    recordEvaluation(context.evaluations, "source", ruleId);
+    const config = stripCommentsPreservingLayout(context.config);
+    for (const retired of RETIRED_CONFIG_KEYS) {
+        const match = config.match(retired.pattern);
+        if (!match || match.index === undefined)
+            continue;
+        context.findings.push(staticFinding({
+            ruleId,
+            surface: "source",
+            path: "brandlab.config.ts",
+            line: lineAt(context.config, match.index + match[0].lastIndexOf(retired.key)),
+            expected: "Only current 3.0 platform APIs",
+            actual: `brandlab.config.ts still declares ${retired.label}, which 3.0 removed.`,
+            remediation: retired.remediation,
+        }));
+    }
+}
+// --- structural: CI and deployment -------------------------------------------
+function inspectWorkflowPins(context) {
+    const directory = join(context.root, ".github/workflows");
+    if (!isDirectory(directory))
+        return;
+    const workflows = readdirSync(directory).filter((name) => /\.ya?ml$/.test(name)).sort();
+    if (workflows.length === 0)
+        return;
+    const ruleId = "brandlab-ci-workflow-pinned";
+    recordEvaluation(context.evaluations, "project-verification", ruleId);
+    for (const name of workflows) {
+        const path = `.github/workflows/${name}`;
+        const text = readFileSync(join(context.root, path), "utf8");
+        for (const match of text.matchAll(/^[ \t]*-?[ \t]*uses[ \t]*:[ \t]*['"]?([^'"\s#]+)/gm)) {
+            const reference = match[1];
+            if (reference.startsWith("./") || reference.startsWith("docker://"))
+                continue;
+            if (/@[0-9a-f]{40}$/.test(reference))
+                continue;
+            context.findings.push(staticFinding({
+                ruleId,
+                surface: "project-verification",
+                path,
+                line: lineAt(text, match.index ?? 0),
+                expected: "Every reused workflow and action pinned to a full 40-character commit SHA",
+                actual: `${reference} is not pinned to an immutable commit.`,
+                remediation: "Pin the reference to the fleet workflow SHA recorded in the control repo.",
+            }));
+        }
+    }
+}
+function inspectVercelIgnore(context) {
+    const text = readOptionalFile(join(context.root, ".vercelignore"));
+    if (text === null)
+        return;
+    const ruleId = "brandlab-deployment-vercelignore-lockfile";
+    recordEvaluation(context.evaluations, "deployment", ruleId);
+    const excluded = ["package.json", "package-lock.json"].filter((file) => isIgnored(text, file));
+    if (excluded.length === 0)
+        return;
+    context.findings.push(staticFinding({
+        ruleId,
+        surface: "deployment",
+        path: ".vercelignore",
+        expected: ".vercelignore never excludes package.json or package-lock.json",
+        actual: `.vercelignore excludes ${excluded.join(" and ")}, so Vercel cannot install the exact locked release.`,
+        remediation: "Remove the package manifest and lockfile patterns from .vercelignore.",
+    }));
+}
+/** Evaluate gitignore-style patterns (last match wins) for a root-level file. */
+export function isIgnored(patterns, file) {
+    let ignored = false;
+    for (const rawLine of patterns.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const negated = line.startsWith("!");
+        let pattern = negated ? line.slice(1) : line;
+        if (pattern.endsWith("/"))
+            continue;
+        pattern = pattern.replace(/^\//, "").replace(/^\*\*\//, "");
+        if (pattern.includes("/"))
+            continue;
+        if (globMatch(pattern, file))
+            ignored = !negated;
+    }
+    return ignored;
+}
+/** Every defineContactContract call and the recipient environment key it declares. */
+export function findContactContractRecipients(source) {
+    return source.files.flatMap((file) => findImportedCalls(file, SITE_CORE("contact"), "defineContactContract").map((call) => ({
+        path: file.path,
+        line: lineOfNode(file, call),
+        recipientEnv: stringLiteralValue(objectPropertyValue(objectPropertyValue(call.arguments[0], "delivery"), "recipientEnv")),
+    })));
+}
+/** Framework route file candidates under src/app, then a legacy root app/. */
+function routeCandidates(name) {
+    return ["src/app", "app"].flatMap((directory) => SOURCE_EXTENSIONS.map((extension) => posix.join(directory, `${name}.${extension}`)));
+}
+function firstExisting(context, candidates) {
+    return candidates.find((path) => context.source.byPath.has(path) || existsSync(join(context.root, path))) ?? null;
+}
+function localImports(context, resolver, file) {
+    return listModuleReferences(file)
+        .filter((reference) => !reference.typeOnly)
+        .flatMap((reference) => {
+        const resolved = resolver(file.path, reference.specifier);
+        const target = resolved ? context.source.byPath.get(resolved) : undefined;
+        return target ? [target] : [];
+    });
+}
+/** Names a module exports, including `export { local as POST }` forms. */
+export function exportedNames(file) {
+    const names = new Set();
+    for (const statement of parseBrandlabSourceFile(file).statements) {
+        const exported = ts.canHaveModifiers(statement) &&
+            ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+        if (exported && (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) {
+            names.add(statement.name.text);
+        }
+        else if (exported && ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    names.add(declaration.name.text);
+            }
+        }
+        else if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+            for (const element of statement.exportClause.elements)
+                names.add(element.name.text);
+        }
+    }
+    return names;
+}
+function readOptionalFile(path) {
+    return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+//# sourceMappingURL=static-rules.js.map