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

package/dist/project.js

@@ -2,12 +2,14 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { evaluateSharedPackageVersionSpecs, findForbiddenBrandlabPatterns, } from "./vitest.js";
 import { DEFAULT_BRANDLAB_RELEASE_CATALOG, } from "./release-catalog.js";
-import { BRANDLAB_CONFIG_V3_RULESET_ID, inspectBrandlabConfigV3, } from "./project-config-v3.js";
+import { BRANDLAB_CONFIG_V3_RULESET_ID, BRANDLAB_CONFIG_V4_RULESET_ID, BRANDLAB_CONFIG_V5_RULESET_ID, inspectBrandlabConfigV3, } from "./project-config-v3.js";
 import { BRANDLAB_CONFIG_V2_RULESET_ID, inspectBrandlabConfigV2 as inspectImmutableBrandlabConfigV2, } from "./project-config-v2-contract.js";
 import { BRANDLAB_DEPRECATED_SCHEMA_SOURCE_PATTERNS, BRANDLAB_SCHEMA_HYGIENE_V3_RULESET_ID, } from "./schema-hygiene.js";
 import { BRANDLAB_SOURCE_SAFETY_V2_PATTERNS, BRANDLAB_SOURCE_SAFETY_V2_RULESET_ID, sourceSafetyRulesetForArchitecture, targetOnlySourceSafetyPatterns, } from "./source-safety-contracts.js";
 import { inspectLegacyArchitectureContract, legacyArchitectureRulesetId, targetOnlyLegacyArchitectureIssues, } from "./legacy-architecture-contracts.js";
 import { BRANDLAB_SHARED_PACKAGE_NAMES, compareBrandlabSemver, digestBrandlabAuthority, isBrandlabSemver, validateBrandlabReleaseCatalog, validateBrandlabRuntimeReleaseCatalog, validateBrandlabRuntimeReleaseManifestSubsetAgainstCatalog, validateBrandlabSupportPolicy, } from "./release-manifest.js";
+import { BRANDLAB_PROJECT_DOCUMENTATION_RULESET_ID, inspectBrandlabProjectDocumentation, } from "./project-documentation.js";
+import { BRANDLAB_ANALYTICS_V3_RULESET_ID, inspectBrandlabAnalyticsV3, } from "./analytics-contract.js";
 export const BRANDLAB_CONFORMANCE_SCHEMA_VERSION = "brandlab.conformance.v1";
 export const BRANDLAB_CONFORMANCE_EVALUATOR_VERSION = "control-plane-v1";
 export const BRANDLAB_ARCHITECTURE_DISPATCH_RULESET_ID = "version-aware-architecture-dispatch-v1";
@@ -15,7 +17,19 @@ const LEGACY_ARCHITECTURE_EVALUATOR_CONTRACT = "architecture-v2";
 const LEGACY_CONFIGURATION_CONTRACT = "legacy-config-v1";
 const CONFIGURATION_V2_CONTRACT = "project-config-v2";
 const CONFIGURATION_V3_CONTRACT = "project-config-v3";
+const CONFIGURATION_V4_CONTRACT = "project-config-v4";
+const CONFIGURATION_V5_CONTRACT = "project-config-v5";
 const SEO_V3_CONTRACT = "seo-v3";
+const SEO_V4_CONTRACT = "seo-v4";
+const ARCHITECTURE_V5_CONTRACT = "architecture-v5";
+const ANALYTICS_V3_CONTRACT = "analytics-v3";
+const ANALYTICS_V4_CONTRACT = "analytics-v4";
+function isSeoV3Compatible(contract) {
+    return contract === SEO_V3_CONTRACT || contract === SEO_V4_CONTRACT;
+}
+function isAnalyticsV3Compatible(contract) {
+    return contract === ANALYTICS_V3_CONTRACT || contract === ANALYTICS_V4_CONTRACT;
+}
 const RUNTIME_PACKAGE_FIELDS = [
     ["next", "next"],
     ["react", "react"],
@@ -79,6 +93,35 @@ export function evaluateBrandlabProject(options) {
         targetRelease,
         architecture: options.architecture,
     });
+    const documentationFingerprint = evaluateApplicableProjectDocumentationContracts({
+        root,
+        findings,
+        installedManifest,
+        targetManifest,
+    });
+    const analyticsFingerprint = evaluateApplicableAnalyticsContracts({
+        root,
+        findings,
+        installedManifest,
+        targetManifest,
+    });
+    if (installedManifest) {
+        addContactUploadFilenameFindings({
+            root,
+            findings,
+            manifest: installedManifest,
+            classification: "maintenance",
+        });
+    }
+    if (targetManifest &&
+        targetManifest.releaseVersion !== installedManifest?.releaseVersion) {
+        addContactUploadFilenameFindings({
+            root,
+            findings,
+            manifest: targetManifest,
+            classification: "migration",
+        });
+    }
     const sourceRoot = join(root, "src");
     const installedSourceSafety = sourceSafetyRulesetForArchitecture(installedManifest?.contracts.architecture);
     const targetSourceSafety = sourceSafetyRulesetForArchitecture(targetManifest?.contracts.architecture);
@@ -140,17 +183,17 @@ export function evaluateBrandlabProject(options) {
                 },
             });
         }
-        if (installedManifest?.contracts.seo === SEO_V3_CONTRACT) {
+        if (isSeoV3Compatible(installedManifest?.contracts.seo)) {
             addSourcePatternFindings({
                 root,
                 sourceRoot,
                 findings,
                 patterns: BRANDLAB_DEPRECATED_SCHEMA_SOURCE_PATTERNS,
                 classification: "maintenance",
-                contract: { name: "seo", version: SEO_V3_CONTRACT },
+                contract: { name: "seo", version: installedManifest.contracts.seo },
             });
         }
-        if (targetManifest?.contracts.seo === SEO_V3_CONTRACT &&
+        if (isSeoV3Compatible(targetManifest?.contracts.seo) &&
             targetManifest.releaseVersion !== installedManifest?.releaseVersion) {
             addSourcePatternFindings({
                 root,
@@ -158,7 +201,7 @@ export function evaluateBrandlabProject(options) {
                 findings,
                 patterns: BRANDLAB_DEPRECATED_SCHEMA_SOURCE_PATTERNS,
                 classification: "migration",
-                contract: { name: "seo", version: SEO_V3_CONTRACT },
+                contract: { name: "seo", version: targetManifest.contracts.seo },
             });
         }
     }
@@ -175,11 +218,21 @@ export function evaluateBrandlabProject(options) {
         rulesets: {
             configurationV2: BRANDLAB_CONFIG_V2_RULESET_ID,
             configurationV3: BRANDLAB_CONFIG_V3_RULESET_ID,
+            configurationV4: BRANDLAB_CONFIG_V4_RULESET_ID,
+            configurationV5: BRANDLAB_CONFIG_V5_RULESET_ID,
             seoV3: BRANDLAB_SCHEMA_HYGIENE_V3_RULESET_ID,
             installedSourceSafety: installedSourceSafety?.id ?? null,
             targetSourceSafety: targetSourceSafety?.id ?? null,
             installedLegacyArchitecture: legacyArchitectureRulesetId(installedManifest?.contracts.architecture),
             targetLegacyArchitecture: legacyArchitectureRulesetId(targetManifest?.contracts.architecture),
+            projectDocumentation: installedManifest?.contracts.architecture === ARCHITECTURE_V5_CONTRACT ||
+                targetManifest?.contracts.architecture === ARCHITECTURE_V5_CONTRACT
+                ? BRANDLAB_PROJECT_DOCUMENTATION_RULESET_ID
+                : null,
+            analyticsV3: isAnalyticsV3Compatible(installedManifest?.contracts.analytics) ||
+                isAnalyticsV3Compatible(targetManifest?.contracts.analytics)
+                ? BRANDLAB_ANALYTICS_V3_RULESET_ID
+                : null,
         },
     });
     const implementationFingerprint = digestBrandlabAuthority({
@@ -187,6 +240,8 @@ export function evaluateBrandlabProject(options) {
         packageLock: packageLock.fingerprint,
         brandlabConfig: readOptionalText(join(root, "brandlab.config.ts")),
         architecture: architectureFingerprint,
+        documentation: documentationFingerprint,
+        analytics: analyticsFingerprint,
         evidence: sortedFindings.map(({ ruleId, classification, severity, path, line }) => ({
             ruleId,
             classification,
@@ -210,6 +265,85 @@ export function evaluateBrandlabProject(options) {
         advisory: summarize(sortedFindings, "advisory"),
     };
 }
+function evaluateApplicableProjectDocumentationContracts(options) {
+    const installedArchitecture = options.installedManifest?.contracts.architecture ?? null;
+    const targetArchitecture = options.targetManifest?.contracts.architecture ?? null;
+    if (installedArchitecture !== ARCHITECTURE_V5_CONTRACT &&
+        targetArchitecture !== ARCHITECTURE_V5_CONTRACT) {
+        return null;
+    }
+    const report = inspectBrandlabProjectDocumentation(options.root);
+    if (installedArchitecture === ARCHITECTURE_V5_CONTRACT) {
+        for (const issue of report.issues) {
+            options.findings.push(mapProjectDocumentationIssue(issue, "maintenance"));
+        }
+    }
+    else if (targetArchitecture === ARCHITECTURE_V5_CONTRACT) {
+        for (const issue of report.issues) {
+            options.findings.push(mapProjectDocumentationIssue(issue, "migration"));
+        }
+    }
+    return {
+        rulesetId: report.rulesetId,
+        files: report.files,
+        applicableRuleIds: report.issues.map((issue) => issue.ruleId).sort(),
+    };
+}
+function mapProjectDocumentationIssue(issue, classification) {
+    return {
+        ruleId: issue.ruleId,
+        surface: issue.surface,
+        classification,
+        severity: issue.severity,
+        contract: { name: "architecture", version: ARCHITECTURE_V5_CONTRACT },
+        evidenceKind: issue.evidenceKind,
+        ...(issue.path ? { path: issue.path } : {}),
+        ...(issue.line ? { line: issue.line } : {}),
+        expected: issue.expected,
+        actual: issue.actual,
+        remediation: issue.remediation,
+    };
+}
+function evaluateApplicableAnalyticsContracts(options) {
+    const installedAnalytics = options.installedManifest?.contracts.analytics ?? null;
+    const targetAnalytics = options.targetManifest?.contracts.analytics ?? null;
+    if (!isAnalyticsV3Compatible(installedAnalytics) &&
+        !isAnalyticsV3Compatible(targetAnalytics)) {
+        return null;
+    }
+    const inspection = inspectBrandlabAnalyticsV3(options.root);
+    if (isAnalyticsV3Compatible(installedAnalytics)) {
+        for (const issue of inspection.issues) {
+            options.findings.push(mapAnalyticsV3Issue(issue, "maintenance", installedAnalytics));
+        }
+    }
+    else if (isAnalyticsV3Compatible(targetAnalytics)) {
+        for (const issue of inspection.issues) {
+            options.findings.push(mapAnalyticsV3Issue(issue, "migration", targetAnalytics));
+        }
+    }
+    return {
+        rulesetId: inspection.rulesetId,
+        websiteCallsDeclared: inspection.websiteCallsDeclared,
+        leadDiagnosticsDeclared: inspection.leadDiagnosticsDeclared,
+        applicableRuleIds: inspection.issues.map((issue) => issue.ruleId).sort(),
+    };
+}
+function mapAnalyticsV3Issue(issue, classification, contractVersion) {
+    return {
+        ruleId: issue.ruleId,
+        surface: issue.surface,
+        classification,
+        severity: issue.severity,
+        contract: { name: "analytics", version: contractVersion },
+        evidenceKind: issue.evidenceKind,
+        ...(issue.path ? { path: issue.path } : {}),
+        ...(issue.line ? { line: issue.line } : {}),
+        expected: issue.expected,
+        actual: issue.actual,
+        remediation: issue.remediation,
+    };
+}
 function addSourcePatternFindings(options) {
     for (const match of findForbiddenBrandlabPatterns({
         roots: [options.sourceRoot],
@@ -674,6 +808,13 @@ function addInstalledRuntimeFindings(options) {
             path: "package.json",
         }));
     }
+    addSharpRuntimeFindings({
+        findings: options.findings,
+        packageJson: options.packageJson,
+        packageLock: options.packageLock,
+        manifest: options.manifest,
+        classification: "maintenance",
+    });
 }
 function addTargetRuntimeFindings(options) {
     if (!options.packageJson)
@@ -713,6 +854,16 @@ function addTargetRuntimeFindings(options) {
     if (options.packageJson.packageManager !== options.targetManifest.runtime.packageManager) {
         runtimeMismatches.push(`packageManager(expected=${options.targetManifest.runtime.packageManager},actual=${options.packageJson.packageManager ?? "missing"})`);
     }
+    const targetSharp = options.targetManifest.runtime.sharp;
+    if (targetSharp) {
+        const actualOverride = options.packageJson.overrides?.sharp ?? null;
+        const sharpResolutions = options.packageLock.sharpResolutions;
+        if (actualOverride !== targetSharp ||
+            sharpResolutions.length !== 1 ||
+            sharpResolutions[0]?.version !== targetSharp) {
+            runtimeMismatches.push(`sharp(expected=${targetSharp},override=${actualOverride ?? "missing"},resolutions=${formatSharpResolutions(sharpResolutions)})`);
+        }
+    }
     if (runtimeMismatches.length > 0) {
         options.findings.push(migrationRuntimeFinding({
             ruleId: "brandlab-migration-runtime-baseline",
@@ -722,6 +873,64 @@ function addTargetRuntimeFindings(options) {
         }));
     }
 }
+function addSharpRuntimeFindings(options) {
+    const expected = options.manifest.runtime.sharp;
+    if (!expected)
+        return;
+    const actualOverride = options.packageJson.overrides?.sharp ?? null;
+    if (actualOverride !== expected) {
+        options.findings.push(runtimeFinding({
+            ruleId: "brandlab-runtime-sharp-override",
+            expected: `overrides.sharp=${expected}`,
+            actual: `overrides.sharp=${actualOverride ?? "missing"}.`,
+            remediation: "Add the release-owned Sharp override so Next.js and site-next use one security-patched native runtime.",
+            path: "package.json",
+        }));
+    }
+    if (options.packageLock.state !== "valid")
+        return;
+    if (options.packageLock.sharpResolutions.length !== 1 ||
+        options.packageLock.sharpResolutions[0]?.version !== expected) {
+        options.findings.push(runtimeFinding({
+            ruleId: "brandlab-runtime-sharp-resolution",
+            expected: `one sharp@${expected} lockfile resolution`,
+            actual: formatSharpResolutions(options.packageLock.sharpResolutions),
+            remediation: "Regenerate package-lock.json after applying the exact release-owned Sharp override.",
+            path: "package-lock.json",
+        }));
+    }
+}
+function addContactUploadFilenameFindings(options) {
+    if (!options.manifest.capabilities.includes("client-safe-contact-upload-filenames")) {
+        return;
+    }
+    const path = "src/lib/contact/imageUploads.ts";
+    const source = readOptionalText(join(options.root, path));
+    // Raw File objects already retain their reviewed names. This rule is only
+    // relevant when a project owns a client-side image processing adapter.
+    if (!source || /\bnormalizeContactUploadFile\s*\(/.test(source))
+        return;
+    options.findings.push({
+        ruleId: "brandlab-contact-upload-filename-normalization",
+        surface: "contact",
+        classification: options.classification,
+        severity: "blocker",
+        contract: {
+            name: "contact",
+            version: options.manifest.contracts.contact,
+        },
+        evidenceKind: "static",
+        path,
+        expected: "Compressed contact images are wrapped with normalizeContactUploadFile before FormData submission.",
+        actual: "The contact upload module does not use the shared filename normalizer.",
+        remediation: "Use normalizeContactUploadFile(original, processed) from @brandlab-digital/site-next/contact/client so anonymous browser Blobs retain a valid reviewed filename.",
+    });
+}
+function formatSharpResolutions(resolutions) {
+    return resolutions.length === 0
+        ? "none"
+        : resolutions.map((entry) => `${entry.path}=${entry.version ?? "missing"}`).join(", ");
+}
 function runtimeFinding(options) {
     return {
         ruleId: options.ruleId,
@@ -760,10 +969,14 @@ function evaluateApplicableArchitectureContracts(options) {
         configV2Inspection ??= inspectImmutableBrandlabConfigV2(options.root);
         return configV2Inspection;
     };
-    let configV3Inspection = null;
-    const inspectConfigV3 = () => {
-        configV3Inspection ??= inspectBrandlabConfigV3(options.root);
-        return configV3Inspection;
+    const configV3Inspections = new Map();
+    const inspectConfigV3 = (contractVersion) => {
+        const cached = configV3Inspections.get(contractVersion);
+        if (cached)
+            return cached;
+        const inspection = inspectBrandlabConfigV3(options.root, { contractVersion });
+        configV3Inspections.set(contractVersion, inspection);
+        return inspection;
     };
     const legacyInspections = new Map();
     let legacyArchitectureInput;
@@ -793,7 +1006,19 @@ function evaluateApplicableArchitectureContracts(options) {
         }
     }
     else if (installedConfiguration === CONFIGURATION_V3_CONTRACT) {
-        const inspection = inspectConfigV3();
+        const inspection = inspectConfigV3(CONFIGURATION_V3_CONTRACT);
+        for (const issue of inspection.issues) {
+            options.findings.push(mapConfigIssue(issue, "maintenance", options.installedManifest?.contracts));
+        }
+    }
+    else if (installedConfiguration === CONFIGURATION_V4_CONTRACT) {
+        const inspection = inspectConfigV3(CONFIGURATION_V4_CONTRACT);
+        for (const issue of inspection.issues) {
+            options.findings.push(mapConfigIssue(issue, "maintenance", options.installedManifest?.contracts));
+        }
+    }
+    else if (installedConfiguration === CONFIGURATION_V5_CONTRACT) {
+        const inspection = inspectConfigV3(CONFIGURATION_V5_CONTRACT);
         for (const issue of inspection.issues) {
             options.findings.push(mapConfigIssue(issue, "maintenance", options.installedManifest?.contracts));
         }
@@ -826,9 +1051,9 @@ function evaluateApplicableArchitectureContracts(options) {
         // supported target release is explicitly selected.
         const configSource = readOptionalText(join(options.root, "brandlab.config.ts"));
         if (/\bdefineBrandlabProject\s*\(/.test(configSource ?? "")) {
-            for (const issue of inspectConfigV3().issues) {
+            for (const issue of inspectConfigV3(CONFIGURATION_V5_CONTRACT).issues) {
                 options.findings.push(mapConfigIssue(issue, "advisory", {
-                    configuration: CONFIGURATION_V3_CONTRACT,
+                    configuration: CONFIGURATION_V5_CONTRACT,
                 }));
             }
         }
@@ -846,7 +1071,17 @@ function evaluateApplicableArchitectureContracts(options) {
         }
     }
     else if (hasDistinctTarget && targetConfiguration === CONFIGURATION_V3_CONTRACT) {
-        for (const issue of inspectConfigV3().issues) {
+        for (const issue of inspectConfigV3(CONFIGURATION_V3_CONTRACT).issues) {
+            options.findings.push(mapConfigIssue(issue, "migration", options.targetManifest?.contracts));
+        }
+    }
+    else if (hasDistinctTarget && targetConfiguration === CONFIGURATION_V4_CONTRACT) {
+        for (const issue of inspectConfigV3(CONFIGURATION_V4_CONTRACT).issues) {
+            options.findings.push(mapConfigIssue(issue, "migration", options.targetManifest?.contracts));
+        }
+    }
+    else if (hasDistinctTarget && targetConfiguration === CONFIGURATION_V5_CONTRACT) {
+        for (const issue of inspectConfigV3(CONFIGURATION_V5_CONTRACT).issues) {
             options.findings.push(mapConfigIssue(issue, "migration", options.targetManifest?.contracts));
         }
     }
@@ -867,7 +1102,9 @@ function evaluateApplicableArchitectureContracts(options) {
         }
     }
     const inspectedConfigV2 = configV2Inspection;
-    const inspectedConfigV3 = configV3Inspection;
+    const inspectedConfigV3 = (configV3Inspections.get(CONFIGURATION_V4_CONTRACT) ??
+        configV3Inspections.get(CONFIGURATION_V3_CONTRACT) ??
+        null);
     return {
         evaluator: BRANDLAB_ARCHITECTURE_DISPATCH_RULESET_ID,
         installedContract: options.installedManifest?.contracts.architecture ?? null,
@@ -1050,7 +1287,7 @@ function readPackageLock(root) {
     const rootDevDependencies = stringRecord(rootPackage.devDependencies);
     const rootEngines = stringRecord(rootPackage.engines);
     const resolvedPackages = new Map();
-    for (const packageName of [...BRANDLAB_SHARED_PACKAGE_NAMES, ...RUNTIME_PACKAGE_FIELDS.map(([name]) => name)]) {
+    for (const packageName of [...BRANDLAB_SHARED_PACKAGE_NAMES, ...RUNTIME_PACKAGE_FIELDS.map(([name]) => name), "sharp"]) {
         const entry = parsed.packages[`node_modules/${packageName}`];
         if (!isObjectRecord(entry))
             continue;
@@ -1061,6 +1298,13 @@ function readPackageLock(root) {
             linked: entry.link === true,
         });
     }
+    const sharpResolutions = Object.entries(parsed.packages)
+        .filter(([packagePath]) => packagePath === "node_modules/sharp" || packagePath.endsWith("/node_modules/sharp"))
+        .map(([packagePath, entry]) => ({
+        path: packagePath,
+        version: isObjectRecord(entry) && typeof entry.version === "string" ? entry.version : null,
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
     return {
         state: "valid",
         lockfileVersion,
@@ -1068,6 +1312,7 @@ function readPackageLock(root) {
         rootDevDependencies,
         rootEngines,
         resolvedPackages,
+        sharpResolutions,
         fingerprint: {
             state: "valid",
             lockfileVersion,
@@ -1080,6 +1325,7 @@ function readPackageLock(root) {
                         rootDevDependencies,
                         rootEngines,
                         resolvedPackages,
+                        sharpResolutions,
                         fingerprint: {},
                     }, packageName)])),
                 node: rootEngines.node ?? null,
@@ -1088,6 +1334,7 @@ function readPackageLock(root) {
                 packageName,
                 { version: entry.version, linked: entry.linked },
             ])),
+            sharp: sharpResolutions,
         },
     };
 }
@@ -1099,6 +1346,7 @@ function emptyPackageLockInspection(state, extra = {}) {
         rootDevDependencies: {},
         rootEngines: {},
         resolvedPackages: new Map(),
+        sharpResolutions: [],
         fingerprint: { state, ...extra },
     };
 }