@brandlab-digital/conformance 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/project-config-v3.js

@@ -7,6 +7,8 @@ import { createHash } from "node:crypto";
 import { extname, join, relative } from "node:path";
 import * as ts from "typescript";
 export const BRANDLAB_CONFIG_V3_RULESET_ID = "project-config-v3@1.0.0-rc.2";
+export const BRANDLAB_CONFIG_V4_RULESET_ID = "project-config-v4@1.0.0-rc.12";
+export const BRANDLAB_CONFIG_V5_RULESET_ID = "project-config-v5@1.0.0-rc.19";
 export const BRANDLAB_CONFIG_V3_PROFILES = [
     "next-local-service",
     "next-root-level",
@@ -32,6 +34,8 @@ const LOCATION_STRATEGIES = new Set([
     "multi-location",
 ]);
 const REVIEWS_PROVIDERS = new Set(["google-places", "project-owned"]);
+const GOOGLE_REVIEWS_MODES = new Set(["link-only", "summary", "full"]);
+const MAXIMUM_GOOGLE_REVIEWS_MONTHLY_REQUEST_LIMIT = 100_000;
 const ROOT_CONFIG_KEYS = new Set([
     "projectId",
     "profile",
@@ -181,6 +185,54 @@ const FORBIDDEN_CANDIDATE_EXPORTS = [
     },
 ];
 const PROTECTED_LOCAL_PATTERNS = [
+    {
+        ruleId: "brandlab-config-v3-circular-business-evidence",
+        minimumContract: "project-config-v5",
+        surface: "business",
+        pattern: /\b(?:existing-production-config|repository-config|source-code):/i,
+        expected: "Verified business facts cite independent evidence, not the repository value being verified.",
+        remediation: "Use structured official-registry, GBP, client-document, first-party-record or public-authority evidence; otherwise mark the fact unknown.",
+    },
+    {
+        ruleId: "brandlab-config-v3-service-area-public-address",
+        minimumContract: "project-config-v5",
+        surface: "business",
+        pattern: /\bmodel\s*:\s*["']service-area["'][\s\S]{0,1200}\baddressVisibility\s*:\s*["']public["']|\baddressVisibility\s*:\s*["']public["'][\s\S]{0,1200}\bmodel\s*:\s*["']service-area["']/i,
+        expected: "Customer-location-only service-area businesses keep address facts hidden.",
+        remediation: "Use model service-area, addressVisibility hidden and an unknown or not-applicable address fact.",
+    },
+    {
+        ruleId: "brandlab-config-v3-synthetic-review-proof",
+        minimumContract: "project-config-v5",
+        surface: "location-proof",
+        pattern: /\bregion-review:[^"'`\n]*[\s\S]{0,2400}\b(?:review\?\.\w+\s*\|\||trust\s+\w+|customer feedback across)\b/i,
+        expected: "Review proof exists only when an approved review record is bound to business.proof.",
+        remediation: "Remove fallback review proof and use verified review evidence or no review proof.",
+    },
+    {
+        ruleId: "brandlab-config-v3-local-programmatic-proof-derivation",
+        minimumContract: "project-config-v5",
+        surface: "location-proof",
+        pattern: /\bfunction\s+getProofLevelFromAssetIds\s*\(/,
+        expected: "Programmatic proof levels are derived by @brandlab-digital/site-core/locations.",
+        remediation: "Remove the project-local proof classifier and declare an explicit defineLocationRouteDecision result.",
+    },
+    {
+        ruleId: "brandlab-config-v3-hardcoded-search-demand",
+        minimumContract: "project-config-v5",
+        surface: "location-quality",
+        pattern: /\bsearchDemand\s*:\s*["']medium["']/,
+        expected: "Search demand is observed from evidence or explicitly unknown.",
+        remediation: "Replace the assumed medium value with unknown or an evidence-backed observed record.",
+    },
+    {
+        ruleId: "brandlab-config-v3-hidden-focusable-content",
+        minimumContract: "project-config-v5",
+        surface: "accessibility",
+        pattern: /\baria-hidden\s*=\s*(?:\{\s*true\s*\}|["']true["'])[\s\S]{0,1200}<\s*(?:a|button|input|select|textarea)\b/i,
+        expected: "Collapsed or aria-hidden content contains no focusable controls.",
+        remediation: "Remove collapsed controls from the DOM or make every descendant unfocusable until the content is visible.",
+    },
     {
         ruleId: "brandlab-config-v3-local-contact-transport",
         surface: "contact",
@@ -193,6 +245,34 @@ const PROTECTED_LOCAL_PATTERNS = [
         pattern: /\b(?:class|function|const|let|var)\s+(?:ContactFormEmail|renderContactEmail)\b/,
         expected: "Contact email rendering is owned by @brandlab-digital/site-next/contact/email.",
     },
+    {
+        ruleId: "brandlab-config-v3-local-google-reviews-fetch",
+        minimumContract: "project-config-v4",
+        surface: "google-reviews",
+        pattern: /\bplaces\.googleapis\.com\/v1\/places\b/,
+        expected: "Google Places fetching is owned by @brandlab-digital/site-next/google-reviews/server.",
+    },
+    {
+        ruleId: "brandlab-config-v3-local-google-reviews-renderer",
+        minimumContract: "project-config-v4",
+        surface: "google-reviews",
+        pattern: /@brandlab-digital\/site-core\/google-reviews[\s\S]{0,12000}\breviews\.map\s*\(/,
+        expected: "Google review content and attribution are rendered by the shared policy-complete UI.",
+    },
+    {
+        ruleId: "brandlab-config-v3-hardcoded-google-review-total",
+        minimumContract: "project-config-v4",
+        surface: "google-reviews",
+        pattern: /["'`][^"'`\n]{0,100}\b\d{1,6}\s+Google\s+(?:reviews?|ratings?)\b/i,
+        expected: "Rendered Google rating and review totals come from a live no-store shared snapshot.",
+    },
+    {
+        ruleId: "brandlab-config-v3-public-google-review-cache",
+        minimumContract: "project-config-v4",
+        surface: "google-reviews",
+        pattern: /\b(?:googleReviews?|userRatingCount)\b[\s\S]{0,2000}\b(?:s-maxage|stale-while-revalidate)\b|\b(?:s-maxage|stale-while-revalidate)\b[\s\S]{0,2000}\b(?:googleReviews?|userRatingCount)\b/i,
+        expected: "Google Places content is returned with private no-store headers and is never publicly cached.",
+    },
     {
         ruleId: "brandlab-config-v3-local-lead-event",
         surface: "analytics",
@@ -207,7 +287,8 @@ const PROTECTED_LOCAL_PATTERNS = [
         expected: "Breadcrumb labels and hierarchy derive from the semantic route catalog.",
     },
 ];
-export function inspectBrandlabConfigV3(root) {
+export function inspectBrandlabConfigV3(root, options = {}) {
+    const contractVersion = options.contractVersion ?? "project-config-v5";
     const issues = [];
     const configPath = join(root, "brandlab.config.ts");
     const usage = collectProjectImports(root, issues);
@@ -280,11 +361,11 @@ export function inspectBrandlabConfigV3(root) {
         }));
         return { ...usage, config: null, issues };
     }
-    const config = validateConfigValue(value, issues);
+    const config = validateConfigValue(value, issues, contractVersion);
     if (config) {
-        addImportContractIssues(root, config, usage, issues);
+        addImportContractIssues(root, config, usage, issues, contractVersion);
     }
-    addProtectedImplementationIssues(root, issues);
+    addProtectedImplementationIssues(root, issues, contractVersion);
     return {
         config,
         imports,
@@ -382,7 +463,7 @@ function propertyName(name) {
     }
     return null;
 }
-function validateConfigValue(value, issues) {
+function validateConfigValue(value, issues, contractVersion) {
     if (!isRecord(value)) {
         issues.push(configIssue({
             ruleId: "brandlab-config-v3-object",
@@ -537,7 +618,7 @@ function validateConfigValue(value, issues) {
         }));
     }
     else {
-        validateCapabilities(capabilities, issues);
+        validateCapabilities(capabilities, issues, contractVersion);
     }
     validateSitemap(value.sitemap, issues);
     validateExceptions(value.exceptions, issues);
@@ -549,6 +630,13 @@ function validateConfigValue(value, issues) {
     const locations = isRecord(safeCapabilities.locations) ? safeCapabilities.locations : null;
     const reviews = isRecord(safeCapabilities.reviews) ? safeCapabilities.reviews : null;
     const reviewsProvider = typeof reviews?.provider === "string" ? reviews.provider : null;
+    const reviewsMode = typeof reviews?.mode === "string" ? reviews.mode : null;
+    const reviewsRouteIds = Array.isArray(reviews?.routeIds)
+        ? reviews.routeIds.filter((entry) => typeof entry === "string")
+        : [];
+    const reviewsMonthlyRequestLimit = typeof reviews?.monthlyRequestLimit === "number"
+        ? reviews.monthlyRequestLimit
+        : null;
     if (reviewsProvider === "google-places" && !families.includes("legal")) {
         issues.push(configIssue({
             ruleId: "brandlab-config-v3-google-places-legal-family",
@@ -571,6 +659,9 @@ function validateConfigValue(value, issues) {
             contactEnabled: contact !== null,
             locationStrategy: typeof locations?.strategy === "string" ? locations.strategy : null,
             reviewsProvider,
+            reviewsMode,
+            reviewsRouteIds,
+            reviewsMonthlyRequestLimit,
         },
     };
 }
@@ -647,7 +738,7 @@ function validateAliases(value, issues) {
         }));
     }
 }
-function validateCapabilities(capabilities, issues) {
+function validateCapabilities(capabilities, issues, contractVersion) {
     addUnknownKeyIssues(capabilities, new Set(["blog", "contact", "locations", "reviews"]), new Set(), "capabilities", issues);
     if (capabilities.blog !== undefined) {
         if (!isRecord(capabilities.blog)) {
@@ -717,7 +808,10 @@ function validateCapabilities(capabilities, issues) {
             addShapeIssue("reviews", issues);
         }
         else {
-            addUnknownKeyIssues(capabilities.reviews, new Set(["provider"]), new Set(), "capabilities.reviews", issues);
+            addUnknownKeyIssues(capabilities.reviews, capabilities.reviews.provider === "google-places" &&
+                contractVersion !== "project-config-v3"
+                ? new Set(["provider", "mode", "routeIds", "monthlyRequestLimit"])
+                : new Set(["provider"]), new Set(), "capabilities.reviews", issues);
             if (typeof capabilities.reviews.provider !== "string" ||
                 !REVIEWS_PROVIDERS.has(capabilities.reviews.provider)) {
                 issues.push(configIssue({
@@ -728,6 +822,64 @@ function validateCapabilities(capabilities, issues) {
                     path: "brandlab.config.ts",
                 }));
             }
+            if (capabilities.reviews.provider === "google-places" &&
+                contractVersion !== "project-config-v3") {
+                if (typeof capabilities.reviews.mode !== "string" ||
+                    !GOOGLE_REVIEWS_MODES.has(capabilities.reviews.mode)) {
+                    issues.push(configIssue({
+                        ruleId: "brandlab-config-v3-google-reviews-mode",
+                        expected: `One Google reviews mode: ${[...GOOGLE_REVIEWS_MODES].join(", ")}.`,
+                        actual: `reviews.mode is ${JSON.stringify(capabilities.reviews.mode)}.`,
+                        remediation: "Select link-only, summary or full explicitly.",
+                        path: "brandlab.config.ts",
+                    }));
+                }
+                const routeIds = Array.isArray(capabilities.reviews.routeIds)
+                    ? capabilities.reviews.routeIds.filter((entry) => typeof entry === "string")
+                    : [];
+                if (!Array.isArray(capabilities.reviews.routeIds) ||
+                    routeIds.length === 0 ||
+                    routeIds.length !== capabilities.reviews.routeIds.length ||
+                    routeIds.some((routeId) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(routeId))) {
+                    issues.push(configIssue({
+                        ruleId: "brandlab-config-v3-google-reviews-routes",
+                        expected: "At least one unique lowercase kebab-case review placement route ID.",
+                        actual: `reviews.routeIds is ${JSON.stringify(capabilities.reviews.routeIds)}.`,
+                        remediation: "Declare only the route IDs where Google review proof is intentionally displayed.",
+                        path: "brandlab.config.ts",
+                    }));
+                }
+                else {
+                    addDuplicateIssue(routeIds, "brandlab-config-v3-google-reviews-route-duplicate", "reviews.routeIds", issues);
+                }
+                if (capabilities.reviews.mode === "link-only") {
+                    if (capabilities.reviews.monthlyRequestLimit !== undefined) {
+                        issues.push(configIssue({
+                            ruleId: "brandlab-config-v3-google-reviews-link-only-quota",
+                            expected: "No API request limit for link-only review proof.",
+                            actual: "reviews.monthlyRequestLimit is configured for link-only mode.",
+                            remediation: "Remove monthlyRequestLimit because link-only mode never calls Places.",
+                            path: "brandlab.config.ts",
+                        }));
+                    }
+                }
+                else if (capabilities.reviews.mode === "summary" ||
+                    capabilities.reviews.mode === "full") {
+                    const limit = capabilities.reviews.monthlyRequestLimit;
+                    if (typeof limit !== "number" ||
+                        !Number.isSafeInteger(limit) ||
+                        limit < 1 ||
+                        limit > MAXIMUM_GOOGLE_REVIEWS_MONTHLY_REQUEST_LIMIT) {
+                        issues.push(configIssue({
+                            ruleId: "brandlab-config-v3-google-reviews-quota",
+                            expected: `monthlyRequestLimit from 1 to ${MAXIMUM_GOOGLE_REVIEWS_MONTHLY_REQUEST_LIMIT}.`,
+                            actual: `reviews.monthlyRequestLimit is ${JSON.stringify(limit)}.`,
+                            remediation: "Set an explicit project-level monthly request ceiling.",
+                            path: "brandlab.config.ts",
+                        }));
+                    }
+                }
+            }
         }
     }
 }
@@ -905,7 +1057,7 @@ function isIsoDate(value) {
         return false;
     return !Number.isNaN(Date.parse(value));
 }
-function addImportContractIssues(root, config, usage, issues) {
+function addImportContractIssues(root, config, usage, issues, contractVersion) {
     if (config.profile === "legacy-php") {
         const nextEvidence = detectNextPackageBackedEvidence(root, usage);
         if (nextEvidence.length === 0)
@@ -935,7 +1087,7 @@ function addImportContractIssues(root, config, usage, issues) {
         requireStrictUsage({
             moduleName: "@brandlab-digital/site-core/locations",
             surface: "location-proof",
-            exports: ["defineLocationRouteQuality"],
+            exports: ["defineLocationRouteDecision", "defineLocationRouteQuality"],
         }, usage, issues);
     }
     const contactEvidence = detectContactSurfaceEvidence(root, usage);
@@ -962,16 +1114,30 @@ function addImportContractIssues(root, config, usage, issues) {
         }));
     }
     if (contactRequired) {
-        requireStrictUsage({
-            moduleName: "@brandlab-digital/site-next/contact/production",
-            surface: "contact-production",
-            exports: ["createBrandlabProductionContactRuntime"],
-        }, usage, issues);
-        requireStrictUsage({
-            moduleName: "@brandlab-digital/site-next/contact/client",
-            surface: "contact-client",
-            exports: ["createContactHttpSubmissionController"],
-        }, usage, issues);
+        requireAnyStrictUsage([
+            {
+                moduleName: "@brandlab-digital/site-next/contact/server",
+                surface: "contact-production",
+                exports: ["createBrandlabProductionContactRuntime"],
+            },
+            {
+                moduleName: "@brandlab-digital/site-next/contact/production",
+                surface: "contact-production",
+                exports: ["createBrandlabProductionContactRuntime"],
+            },
+        ], usage, issues);
+        requireAnyStrictUsage([
+            {
+                moduleName: "@brandlab-digital/site-next/contact",
+                surface: "contact-client",
+                exports: ["createContactHttpSubmissionController"],
+            },
+            {
+                moduleName: "@brandlab-digital/site-next/contact/client",
+                surface: "contact-client",
+                exports: ["createContactHttpSubmissionController"],
+            },
+        ], usage, issues);
     }
     if (config.capabilities.blogAdapter && config.capabilities.blogAdapter !== "none") {
         const adapterExport = config.capabilities.blogAdapter === "mdx"
@@ -984,16 +1150,37 @@ function addImportContractIssues(root, config, usage, issues) {
         }, usage, issues);
     }
     if (config.capabilities.reviewsProvider === "google-places") {
-        requireStrictUsage({
-            moduleName: "@brandlab-digital/site-next/google-reviews",
-            surface: "google-reviews-route",
-            exports: ["createGooglePlaceReviewsRouteResponse"],
-        }, usage, issues);
-        requireStrictUsage({
-            moduleName: "@brandlab-digital/site-next/google-reviews",
-            surface: "google-reviews-display",
-            exports: ["GooglePlaceReviews"],
-        }, usage, issues);
+        if (contractVersion === "project-config-v3") {
+            requireStrictUsage({
+                moduleName: "@brandlab-digital/site-next/google-reviews",
+                surface: "google-reviews-route",
+                exports: ["createGooglePlaceReviewsRouteResponse"],
+            }, usage, issues);
+            requireStrictUsage({
+                moduleName: "@brandlab-digital/site-next/google-reviews",
+                surface: "google-reviews-display",
+                exports: ["GooglePlaceReviews"],
+            }, usage, issues);
+        }
+        else if (config.capabilities.reviewsMode === "link-only") {
+            requireStrictUsage({
+                moduleName: "@brandlab-digital/site-next/google-reviews/ui",
+                surface: "google-reviews-link",
+                exports: ["GoogleReviewsLink"],
+            }, usage, issues);
+        }
+        else {
+            requireStrictUsage({
+                moduleName: "@brandlab-digital/site-next/google-reviews/server",
+                surface: "google-reviews-production",
+                exports: ["createBrandlabGooglePlaceReviewsProductionRuntime"],
+            }, usage, issues);
+            requireStrictUsage({
+                moduleName: "@brandlab-digital/site-next/google-reviews/client",
+                surface: "google-reviews-display",
+                exports: ["GooglePlaceReviewsClient"],
+            }, usage, issues);
+        }
     }
     else if (config.capabilities.reviewsProvider === "project-owned") {
         requireStrictUsage({
@@ -1002,7 +1189,7 @@ function addImportContractIssues(root, config, usage, issues) {
             exports: ["preparePublicReviews"],
         }, usage, issues);
     }
-    else if (usage.imports.has("@brandlab-digital/site-next/google-reviews")) {
+    else if ([...usage.imports].some((name) => name.startsWith("@brandlab-digital/site-next/google-reviews"))) {
         issues.push(configIssue({
             ruleId: "brandlab-config-v3-google-reviews-capability",
             surface: "google-reviews",
@@ -1069,7 +1256,8 @@ function detectNextPackageBackedEvidence(root, usage) {
 function detectContactSurfaceEvidence(root, usage) {
     const evidence = new Set();
     for (const moduleName of usage.imports) {
-        if (moduleName.startsWith("@brandlab-digital/site-next/contact/")) {
+        if (moduleName === "@brandlab-digital/site-next/contact" ||
+            moduleName.startsWith("@brandlab-digital/site-next/contact/")) {
             evidence.add(`shared contact import ${moduleName}`);
         }
     }
@@ -1153,6 +1341,13 @@ function requireStrictUsage(requirement, usage, issues) {
         }));
     }
 }
+function requireAnyStrictUsage(requirements, usage, issues) {
+    const selected = requirements.find((requirement) => usage.imports.has(requirement.moduleName)) ??
+        requirements[0];
+    if (!selected)
+        return;
+    requireStrictUsage(selected, usage, issues);
+}
 function frameworkOwnerExpectation(owner) {
     if (owner === "metadata") {
         return "The strict metadata builder reaches metadata or generateMetadata in an App Router page or layout entrypoint.";
@@ -1328,7 +1523,8 @@ function collectProjectImports(root, issues) {
                 return;
             executableImports.add(binding.moduleName);
             addExportUsage(executableExports, binding.moduleName, binding.exportName);
-            const isSharedContactClientController = binding.moduleName === "@brandlab-digital/site-next/contact/client" &&
+            const isSharedContactClientController = (binding.moduleName === "@brandlab-digital/site-next/contact" ||
+                binding.moduleName === "@brandlab-digital/site-next/contact/client") &&
                 binding.exportName === "createContactHttpSubmissionController";
             if (isOutputOwned(node) ||
                 (isSharedContactClientController && isContactClientRuntimeOwned(node))) {
@@ -2752,11 +2948,14 @@ function isRuntimeIdentifierReference(identifier) {
     }
     return true;
 }
-function addProtectedImplementationIssues(root, issues) {
+function addProtectedImplementationIssues(root, issues, contractVersion) {
     for (const file of walkProjectRuntimeFiles(root)) {
         const relativePath = normalizePath(relative(root, file));
         const source = readFileSync(file, "utf8");
         for (const rule of PROTECTED_LOCAL_PATTERNS) {
+            if ("minimumContract" in rule &&
+                !configurationContractIncludes(contractVersion, rule.minimumContract))
+                continue;
             const match = rule.pattern.exec(source);
             if (!match || match.index === undefined)
                 continue;
@@ -2766,9 +2965,11 @@ function addProtectedImplementationIssues(root, issues) {
                 surface: rule.surface,
                 expected: rule.expected,
                 actual: `A protected local implementation was found in ${relativePath}.`,
-                remediation: rule.ruleId === "brandlab-config-v3-url-derived-breadcrumbs"
-                    ? "Use BrandlabRouteBreadcrumbs with the typed route catalog; keep path labels only as a development fallback."
-                    : "Keep only the thin project binding and consume the shared runtime.",
+                remediation: "remediation" in rule
+                    ? rule.remediation
+                    : rule.ruleId === "brandlab-config-v3-url-derived-breadcrumbs"
+                        ? "Use BrandlabRouteBreadcrumbs with the typed route catalog; keep path labels only as a development fallback."
+                        : "Keep only the thin project binding and consume the shared runtime.",
                 severity: "severity" in rule ? rule.severity : "blocker",
                 path: relativePath,
                 line,
@@ -2776,6 +2977,14 @@ function addProtectedImplementationIssues(root, issues) {
         }
     }
 }
+function configurationContractIncludes(actual, minimum) {
+    const order = {
+        "project-config-v3": 3,
+        "project-config-v4": 4,
+        "project-config-v5": 5,
+    };
+    return order[actual] >= order[minimum];
+}
 function walkSourceFiles(root) {
     if (!existsSync(root))
         return [];