@brandlab-digital/conformance 1.0.0-rc.11 → 1.0.0-rc.13

package/dist/project-config-v3.d.ts

@@ -1,4 +1,6 @@
 export declare const BRANDLAB_CONFIG_V3_RULESET_ID = "project-config-v3@1.0.0-rc.2";
+export declare const BRANDLAB_CONFIG_V4_RULESET_ID = "project-config-v4@1.0.0-rc.12";
+export type BrandlabInspectableConfigurationContract = "project-config-v3" | "project-config-v4";
 export declare const BRANDLAB_CONFIG_V3_PROFILES: readonly ["next-local-service", "next-root-level", "next-static-legacy", "legacy-php"];
 export interface InspectedBrandlabProjectConfig {
     projectId: string;
@@ -14,6 +16,9 @@ export interface InspectedBrandlabProjectConfig {
         contactEnabled: boolean;
         locationStrategy: string | null;
         reviewsProvider: string | null;
+        reviewsMode: string | null;
+        reviewsRouteIds: readonly string[];
+        reviewsMonthlyRequestLimit: number | null;
     };
 }
 export interface BrandlabConfigV3Issue {
@@ -37,7 +42,9 @@ export interface BrandlabConfigV3Inspection {
     frameworkOwnedExports: ReadonlyMap<string, ReadonlySet<string>>;
     issues: BrandlabConfigV3Issue[];
 }
-export declare function inspectBrandlabConfigV3(root: string): BrandlabConfigV3Inspection;
+export declare function inspectBrandlabConfigV3(root: string, options?: {
+    contractVersion?: BrandlabInspectableConfigurationContract;
+}): BrandlabConfigV3Inspection;
 /** SHA-256 evidence for the exact canonical serializer output produced at runtime. */
 export declare function digestBrandlabPlatformContractSerialization(serialized: string): string;
 //# sourceMappingURL=project-config-v3.d.ts.map

package/dist/project-config-v3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-config-v3.d.ts","sourceRoot":"","sources":["../src/project-config-v3.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,6BAA6B,iCAAiC,CAAC;AAE5E,eAAO,MAAM,2BAA2B,wFAK9B,CAAC;AA6CX,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,EAAE;QACN,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7B,CAAC;IACF,mBAAmB,EAAE;QACnB,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACxD,CAAC;IACF,YAAY,EAAE;QACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,cAAc,EAAE,OAAO,CAAC;QACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACzC,YAAY,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAC;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AA2JD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,CA4GhF;AAs4FD,sFAAsF;AACtF,wBAAgB,2CAA2C,CAAC,UAAU,EAAE,MAAM,UAe7E"}
+{"version":3,"file":"project-config-v3.d.ts","sourceRoot":"","sources":["../src/project-config-v3.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,6BAA6B,iCAAiC,CAAC;AAC5E,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAC7E,MAAM,MAAM,wCAAwC,GAChD,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,eAAO,MAAM,2BAA2B,wFAK9B,CAAC;AA+CX,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,EAAE;QACN,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7B,CAAC;IACF,mBAAmB,EAAE;QACnB,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACxD,CAAC;IACF,YAAY,EAAE;QACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,cAAc,EAAE,OAAO,CAAC;QACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3C,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACzC,YAAY,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAC;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAuLD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,wCAAwC,CAAA;CAAO,GAC3E,0BAA0B,CA6G5B;AA6/FD,sFAAsF;AACtF,wBAAgB,2CAA2C,CAAC,UAAU,EAAE,MAAM,UAe7E"}

package/dist/project-config-v3.js

@@ -7,6 +7,7 @@ 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_V3_PROFILES = [
     "next-local-service",
     "next-root-level",
@@ -32,6 +33,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",
@@ -193,6 +196,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 +238,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-v4";
     const issues = [];
     const configPath = join(root, "brandlab.config.ts");
     const usage = collectProjectImports(root, issues);
@@ -280,11 +312,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 +414,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 +569,7 @@ function validateConfigValue(value, issues) {
         }));
     }
     else {
-        validateCapabilities(capabilities, issues);
+        validateCapabilities(capabilities, issues, contractVersion);
     }
     validateSitemap(value.sitemap, issues);
     validateExceptions(value.exceptions, issues);
@@ -549,6 +581,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 +610,9 @@ function validateConfigValue(value, issues) {
             contactEnabled: contact !== null,
             locationStrategy: typeof locations?.strategy === "string" ? locations.strategy : null,
             reviewsProvider,
+            reviewsMode,
+            reviewsRouteIds,
+            reviewsMonthlyRequestLimit,
         },
     };
 }
@@ -647,7 +689,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 +759,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-v4"
+                ? 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 +773,64 @@ function validateCapabilities(capabilities, issues) {
                     path: "brandlab.config.ts",
                 }));
             }
+            if (capabilities.reviews.provider === "google-places" &&
+                contractVersion === "project-config-v4") {
+                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 +1008,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)
@@ -984,16 +1087,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 +1126,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",
@@ -2752,11 +2876,15 @@ 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 &&
+                rule.minimumContract === "project-config-v4" &&
+                contractVersion !== "project-config-v4")
+                continue;
             const match = rule.pattern.exec(source);
             if (!match || match.index === undefined)
                 continue;