@brandlab-digital/conformance 3.12.1 → 3.14.0

package/dist/prefetch-probe-cli.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * brandlab-prefetch-probe (3.13.0): measures one page's Next prefetches, run locally against a URL (a local
+ * production build, a protected preview or a live page). For each viewport it lists the pages prefetched on landing
+ * and after a full scroll, with their compressed and decoded bytes and the edge cache result, and says whether the
+ * page would pass W2 (prefetch by link role).
+ *
+ *   npx brandlab-prefetch-probe https://www.example.com.au/areas/hills-district
+ *   npx brandlab-prefetch-probe http://localhost:3000/ --viewport 390x844 --json
+ *
+ * It loads the page once per viewport in headless Chromium (`@playwright/test`, an optional peer) and lets no request
+ * leave for another site, so analytics never counts it. It reads one page; it never crawls.
+ */
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { measurePrefetch } from "./site-system/journeys/prefetch-measure.js";
+import { evaluatePrefetch } from "./site-system/journeys/prefetch-policy.js";
+export const PROBE_DEFAULT_VIEWPORTS = Object.freeze([
+    { width: 390, height: 844 },
+    { width: 1440, height: 900 },
+]);
+const HELP = `brandlab-prefetch-probe <url> [--viewport WIDTHxHEIGHT ...] [--json] [--strict]
+
+Lists the pages one page prefetches on landing and after a full scroll, with bytes, at 390 x 844 and 1440 x 900
+(or the viewports named), and whether it would pass W2. --strict exits 1 when it would not.`;
+const MOBILE_USER_AGENT = "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Mobile Safari/537.36";
+export function parseProbeArgs(argv) {
+    let url;
+    const viewports = [];
+    let json = false;
+    let strict = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--json")
+            json = true;
+        else if (argument === "--strict")
+            strict = true;
+        else if (argument === "--viewport") {
+            const value = argv[++index] ?? "";
+            const match = /^(\d{3,4})x(\d{3,4})$/.exec(value);
+            if (!match)
+                throw new Error(`--viewport takes WIDTHxHEIGHT, for example 390x844 (got ${JSON.stringify(value)}).`);
+            viewports.push({ width: Number(match[1]), height: Number(match[2]) });
+        }
+        else if (argument.startsWith("--"))
+            throw new Error(`Unknown option ${argument}.`);
+        else if (url)
+            throw new Error("Name one page URL.");
+        else
+            url = argument;
+    }
+    if (!url)
+        throw new Error("Name the page URL to probe.");
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${url} is not a full URL; include http:// or https://.`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw new Error(`${url} is not an http or https URL.`);
+    return { url: parsed.href, viewports: viewports.length > 0 ? viewports : [...PROBE_DEFAULT_VIEWPORTS], json, strict };
+}
+function kilobytes(bytes) {
+    return `${Math.round(bytes / 102.4) / 10} KB`;
+}
+/** Edge cache results by count, for example "HIT 3, MISS 9". */
+export function cacheSummary(requests) {
+    const counts = new Map();
+    for (const request of requests)
+        counts.set(request.cache ?? "none", (counts.get(request.cache ?? "none") ?? 0) + 1);
+    return [...counts].map(([cache, count]) => `${cache} ${count}`).join(", ") || "none";
+}
+/** The plain-text report: per viewport, the counts, bytes, pages and the W2 result. */
+export function formatProbeReport(url, results) {
+    const lines = [`Prefetch probe: ${url}`];
+    for (const { viewport, measurement, verdict } of results) {
+        const scrollOnly = measurement.scrolled.filter((page) => !measurement.landing.includes(page));
+        lines.push("", `${viewport}`, `  On landing: ${measurement.landing.length} page(s)${measurement.landing.length ? `: ${measurement.landing.join(", ")}` : ""}`, `  After a full scroll: ${measurement.scrolled.length} page(s)${scrollOnly.length ? `; added ${scrollOnly.join(", ")}` : ""}`, `  Bytes: ${kilobytes(measurement.bytes.prefetchCompressed)} compressed, ${kilobytes(measurement.bytes.prefetchDecoded)} decoded, in ${measurement.requests.length} request(s); the page's HTML ${kilobytes(measurement.bytes.htmlCompressed)} compressed`, `  Edge cache: ${cacheSummary(measurement.requests)}`, verdict.failures.length === 0 ? "  W2: would pass" : `  W2: would fail\n${verdict.failures.map((failure) => `    - ${failure}`).join("\n")}`, ...verdict.warnings.map((warning) => `  ${warning}`));
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** The JSON report: the same results, with each request. */
+export function probeJson(url, results) {
+    return `${JSON.stringify({ url, viewports: results.map(({ viewport, measurement, verdict }) => ({ viewport, ...measurement, verdict })) }, null, 2)}\n`;
+}
+async function loadChromium() {
+    const specifier = "@playwright/test";
+    try {
+        return (await import(specifier)).chromium;
+    }
+    catch {
+        throw new Error("brandlab-prefetch-probe needs @playwright/test with Chromium: npm install --save-dev @playwright/test && npx playwright install chromium");
+    }
+}
+export async function probePrefetch(options, chromium) {
+    const browser = await (chromium ?? (await loadChromium())).launch({ headless: true });
+    const target = new URL(options.url);
+    const results = [];
+    try {
+        for (const viewport of options.viewports) {
+            const mobile = viewport.width < 768;
+            const context = await browser.newContext({
+                viewport: { ...viewport },
+                isMobile: mobile,
+                hasTouch: mobile,
+                serviceWorkers: "block",
+                ...(mobile ? { userAgent: MOBILE_USER_AGENT } : {}),
+            });
+            try {
+                // Only the site under test: analytics, tags and other sites never see the probe.
+                await context.route("**/*", (route) => (new URL(route.request().url()).origin === target.origin ? route.continue() : route.abort()));
+                const page = await context.newPage();
+                const measurement = await measurePrefetch(page, `${target.pathname}${target.search}`, {
+                    open: (opened) => opened.goto(target.href, { waitUntil: "load", timeout: 60_000 }),
+                });
+                const label = `${viewport.width} x ${viewport.height}`;
+                results.push({ viewport: label, measurement, verdict: evaluatePrefetch(measurement, label) });
+            }
+            finally {
+                await context.close();
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return results;
+}
+export async function runPrefetchProbeCli(argv, io, probe = probePrefetch) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        io.stdout(`${HELP}\n`);
+        return argv.length === 0 ? 1 : 0;
+    }
+    try {
+        const options = parseProbeArgs(argv);
+        const results = await probe(options);
+        io.stdout(options.json ? probeJson(options.url, results) : formatProbeReport(options.url, results));
+        return options.strict && results.some((result) => result.verdict.failures.length > 0) ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+function isEntrypoint(moduleUrl, argvPath) {
+    if (!argvPath)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(resolve(argvPath));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntrypoint(import.meta.url, process.argv[1])) {
+    runPrefetchProbeCli(process.argv.slice(2), { stdout: (value) => process.stdout.write(value), stderr: (value) => process.stderr.write(value) }).then((code) => {
+        process.exitCode = code;
+    });
+}
+//# sourceMappingURL=prefetch-probe-cli.js.map

package/dist/prefetch-probe-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch-probe-cli.js","sourceRoot":"","sources":["../src/prefetch-probe-cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n/**\n * brandlab-prefetch-probe (3.13.0): measures one page's Next prefetches, run locally against a URL (a local\n * production build, a protected preview or a live page). For each viewport it lists the pages prefetched on landing\n * and after a full scroll, with their compressed and decoded bytes and the edge cache result, and says whether the\n * page would pass W2 (prefetch by link role).\n *\n *   npx brandlab-prefetch-probe https://www.example.com.au/areas/hills-district\n *   npx brandlab-prefetch-probe http://localhost:3000/ --viewport 390x844 --json\n *\n * It loads the page once per viewport in headless Chromium (`@playwright/test`, an optional peer) and lets no request\n * leave for another site, so analytics never counts it. It reads one page; it never crawls.\n */\nimport { realpathSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { measurePrefetch, type PrefetchMeasureResult } from \"./site-system/journeys/prefetch-measure.js\";\nimport { evaluatePrefetch, type PrefetchVerdict } from \"./site-system/journeys/prefetch-policy.js\";\n\nexport interface ProbeViewport {\n  readonly width: number;\n  readonly height: number;\n}\n\nexport interface ProbeOptions {\n  readonly url: string;\n  readonly viewports: readonly ProbeViewport[];\n  readonly json: boolean;\n  /** Exit 1 when the page would fail W2. */\n  readonly strict: boolean;\n}\n\nexport interface ProbeViewportResult {\n  readonly viewport: string;\n  readonly measurement: PrefetchMeasureResult;\n  readonly verdict: PrefetchVerdict;\n}\n\nexport const PROBE_DEFAULT_VIEWPORTS: readonly ProbeViewport[] = Object.freeze([\n  { width: 390, height: 844 },\n  { width: 1440, height: 900 },\n]);\n\nconst HELP = `brandlab-prefetch-probe <url> [--viewport WIDTHxHEIGHT ...] [--json] [--strict]\n\nLists the pages one page prefetches on landing and after a full scroll, with bytes, at 390 x 844 and 1440 x 900\n(or the viewports named), and whether it would pass W2. --strict exits 1 when it would not.`;\n\nconst MOBILE_USER_AGENT = \"Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Mobile Safari/537.36\";\n\nexport function parseProbeArgs(argv: readonly string[]): ProbeOptions {\n  let url: string | undefined;\n  const viewports: ProbeViewport[] = [];\n  let json = false;\n  let strict = false;\n  for (let index = 0; index < argv.length; index += 1) {\n    const argument = argv[index]!;\n    if (argument === \"--json\") json = true;\n    else if (argument === \"--strict\") strict = true;\n    else if (argument === \"--viewport\") {\n      const value = argv[++index] ?? \"\";\n      const match = /^(\\d{3,4})x(\\d{3,4})$/.exec(value);\n      if (!match) throw new Error(`--viewport takes WIDTHxHEIGHT, for example 390x844 (got ${JSON.stringify(value)}).`);\n      viewports.push({ width: Number(match[1]), height: Number(match[2]) });\n    } else if (argument.startsWith(\"--\")) throw new Error(`Unknown option ${argument}.`);\n    else if (url) throw new Error(\"Name one page URL.\");\n    else url = argument;\n  }\n  if (!url) throw new Error(\"Name the page URL to probe.\");\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    throw new Error(`${url} is not a full URL; include http:// or https://.`);\n  }\n  if (parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") throw new Error(`${url} is not an http or https URL.`);\n  return { url: parsed.href, viewports: viewports.length > 0 ? viewports : [...PROBE_DEFAULT_VIEWPORTS], json, strict };\n}\n\nfunction kilobytes(bytes: number): string {\n  return `${Math.round(bytes / 102.4) / 10} KB`;\n}\n\n/** Edge cache results by count, for example \"HIT 3, MISS 9\". */\nexport function cacheSummary(requests: PrefetchMeasureResult[\"requests\"]): string {\n  const counts = new Map<string, number>();\n  for (const request of requests) counts.set(request.cache ?? \"none\", (counts.get(request.cache ?? \"none\") ?? 0) + 1);\n  return [...counts].map(([cache, count]) => `${cache} ${count}`).join(\", \") || \"none\";\n}\n\n/** The plain-text report: per viewport, the counts, bytes, pages and the W2 result. */\nexport function formatProbeReport(url: string, results: readonly ProbeViewportResult[]): string {\n  const lines = [`Prefetch probe: ${url}`];\n  for (const { viewport, measurement, verdict } of results) {\n    const scrollOnly = measurement.scrolled.filter((page) => !measurement.landing.includes(page));\n    lines.push(\n      \"\",\n      `${viewport}`,\n      `  On landing: ${measurement.landing.length} page(s)${measurement.landing.length ? `: ${measurement.landing.join(\", \")}` : \"\"}`,\n      `  After a full scroll: ${measurement.scrolled.length} page(s)${scrollOnly.length ? `; added ${scrollOnly.join(\", \")}` : \"\"}`,\n      `  Bytes: ${kilobytes(measurement.bytes.prefetchCompressed)} compressed, ${kilobytes(measurement.bytes.prefetchDecoded)} decoded, in ${measurement.requests.length} request(s); the page's HTML ${kilobytes(measurement.bytes.htmlCompressed)} compressed`,\n      `  Edge cache: ${cacheSummary(measurement.requests)}`,\n      verdict.failures.length === 0 ? \"  W2: would pass\" : `  W2: would fail\\n${verdict.failures.map((failure) => `    - ${failure}`).join(\"\\n\")}`,\n      ...verdict.warnings.map((warning) => `  ${warning}`),\n    );\n  }\n  return `${lines.join(\"\\n\")}\\n`;\n}\n\n/** The JSON report: the same results, with each request. */\nexport function probeJson(url: string, results: readonly ProbeViewportResult[]): string {\n  return `${JSON.stringify({ url, viewports: results.map(({ viewport, measurement, verdict }) => ({ viewport, ...measurement, verdict })) }, null, 2)}\\n`;\n}\n\ntype Chromium = typeof import(\"@playwright/test\").chromium;\n\nasync function loadChromium(): Promise<Chromium> {\n  const specifier: string = \"@playwright/test\";\n  try {\n    return ((await import(specifier)) as { chromium: Chromium }).chromium;\n  } catch {\n    throw new Error(\"brandlab-prefetch-probe needs @playwright/test with Chromium: npm install --save-dev @playwright/test && npx playwright install chromium\");\n  }\n}\n\nexport async function probePrefetch(options: ProbeOptions, chromium?: Chromium): Promise<ProbeViewportResult[]> {\n  const browser = await (chromium ?? (await loadChromium())).launch({ headless: true });\n  const target = new URL(options.url);\n  const results: ProbeViewportResult[] = [];\n  try {\n    for (const viewport of options.viewports) {\n      const mobile = viewport.width < 768;\n      const context = await browser.newContext({\n        viewport: { ...viewport },\n        isMobile: mobile,\n        hasTouch: mobile,\n        serviceWorkers: \"block\",\n        ...(mobile ? { userAgent: MOBILE_USER_AGENT } : {}),\n      });\n      try {\n        // Only the site under test: analytics, tags and other sites never see the probe.\n        await context.route(\"**/*\", (route) => (new URL(route.request().url()).origin === target.origin ? route.continue() : route.abort()));\n        const page = await context.newPage();\n        const measurement = await measurePrefetch(page, `${target.pathname}${target.search}`, {\n          open: (opened) => opened.goto(target.href, { waitUntil: \"load\", timeout: 60_000 }),\n        });\n        const label = `${viewport.width} x ${viewport.height}`;\n        results.push({ viewport: label, measurement, verdict: evaluatePrefetch(measurement, label) });\n      } finally {\n        await context.close();\n      }\n    }\n  } finally {\n    await browser.close();\n  }\n  return results;\n}\n\ninterface CliIo {\n  stdout(value: string): void;\n  stderr(value: string): void;\n}\n\nexport async function runPrefetchProbeCli(argv: readonly string[], io: CliIo, probe: typeof probePrefetch = probePrefetch): Promise<number> {\n  if (argv.length === 0 || argv.includes(\"--help\") || argv.includes(\"-h\")) {\n    io.stdout(`${HELP}\\n`);\n    return argv.length === 0 ? 1 : 0;\n  }\n  try {\n    const options = parseProbeArgs(argv);\n    const results = await probe(options);\n    io.stdout(options.json ? probeJson(options.url, results) : formatProbeReport(options.url, results));\n    return options.strict && results.some((result) => result.verdict.failures.length > 0) ? 1 : 0;\n  } catch (error) {\n    io.stderr(`${error instanceof Error ? error.message : String(error)}\\n`);\n    return 1;\n  }\n}\n\nfunction isEntrypoint(moduleUrl: string, argvPath: string | undefined): boolean {\n  if (!argvPath) return false;\n  try {\n    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(resolve(argvPath));\n  } catch {\n    return false;\n  }\n}\n\nif (isEntrypoint(import.meta.url, process.argv[1])) {\n  runPrefetchProbeCli(process.argv.slice(2), { stdout: (value) => process.stdout.write(value), stderr: (value) => process.stderr.write(value) }).then((code) => {\n    process.exitCode = code;\n  });\n}\n"]}

package/dist/project.d.ts

@@ -38,11 +38,24 @@ export interface BrandlabConformanceResult {
     implementationFingerprint: string;
     mode: BrandlabConformanceMode;
     installedRelease: string | null;
+    /**
+     * Set only when all four packages are one canary prerelease (`X.Y.Z-canary.N`). A canary is never an
+     * installed release: `installedRelease` stays null, so it cannot stand as release evidence.
+     */
+    canaryRelease?: BrandlabCanaryRelease;
     findings: BrandlabFinding[];
     operationalFindings: BrandlabOperationalFinding[];
     verification: BrandlabVerificationResult;
     summary: ConformanceSummary;
 }
+export interface BrandlabCanaryRelease {
+    /** The canary version, e.g. `3.14.0-canary.2`. */
+    version: string;
+    /** The release line it previews, e.g. `3.14.0`. */
+    line: string;
+    /** `embedded`: checked against this checker's contract for the line; `not-cut`: the line has no contract yet. */
+    contract: "embedded" | "not-cut";
+}
 export interface EvaluateBrandlabProjectOptions {
     packedReleaseReceipt?: string;
     root: string;
@@ -62,6 +75,13 @@ interface ProjectPackageJsonLike {
 export declare function evaluateBrandlabProject(options: EvaluateBrandlabProjectOptions): BrandlabConformanceResult;
 export declare function shouldFailBrandlabConformance(result: BrandlabConformanceResult): boolean;
 export declare function detectInstalledBrandlabRelease(packageJson: ProjectPackageJsonLike | null): string | null;
+/**
+ * Reads one canary prerelease across all four packages, pinned exactly (`3.14.0-canary.2`) or installed from
+ * the packed tarball (`file:.canary/brandlab-digital-site-core-3.14.0-canary.2.tgz`). A canary previews the line
+ * `X.Y.Z`: it is checked against that line's contract when this checker carries it, and is otherwise reported
+ * as a canary notice. Lines older than the checker's release are not supported. Never a published release.
+ */
+export declare function detectBrandlabCanaryRelease(packageJson: ProjectPackageJsonLike | null, release?: Pick<BrandlabRuntimeReleaseContract, "releaseVersion">): BrandlabCanaryRelease | null;
 /** Variable names documented in an env example file (`KEY=`, `export KEY=`); values are ignored. */
 export declare function parseEnvironmentKeys(text: string): Set<string>;
 export type { BrandlabContractVersions };

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"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"}

package/dist/project.js

@@ -160,7 +160,10 @@ export function evaluateBrandlabProject(options) {
         ? verifyPackedPreflight(root, resolve(options.packedReleaseReceipt)) : undefined;
     const detectedRelease = packedPreflight?.version ?? detectInstalledBrandlabRelease(packageJson);
     const installedRelease = options.installedRelease === undefined ? detectedRelease : options.installedRelease;
-    const manifest = release.releaseVersion === installedRelease ? release : null;
+    const canary = !detectedRelease && options.installedRelease === undefined
+        ? detectBrandlabCanaryRelease(packageJson, release)
+        : null;
+    const manifest = release.releaseVersion === installedRelease || canary?.contract === "embedded" ? release : null;
     const attestation = options.releaseManifest?.releaseVersion === installedRelease
         ? options.releaseManifest
         : null;
@@ -174,6 +177,8 @@ export function evaluateBrandlabProject(options) {
         packageLock,
         installedRelease,
         detectedRelease,
+        canary,
+        releaseVersion: release.releaseVersion,
         manifest,
         attestation,
         packedPreflight,
@@ -225,6 +230,7 @@ export function evaluateBrandlabProject(options) {
         implementationFingerprint,
         mode,
         installedRelease,
+        ...(canary ? { canaryRelease: canary } : {}),
         findings: operationalFindings,
         operationalFindings,
         verification: policyResult.verification,
@@ -234,16 +240,88 @@ export function evaluateBrandlabProject(options) {
 export function shouldFailBrandlabConformance(result) {
     return result.verification.summary.blockers > 0;
 }
+const CANARY_VERSION_PATTERN = /^((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))-canary\.(?:0|[1-9]\d*)$/;
 export function detectInstalledBrandlabRelease(packageJson) {
     if (!packageJson)
         return null;
     const versions = BRANDLAB_SHARED_PACKAGE_NAMES.map((packageName) => packageJson.dependencies?.[packageName] ??
         packageJson.devDependencies?.[packageName] ??
         null);
-    if (versions.some((version) => !version || !isBrandlabSemver(version)))
+    // A canary (X.Y.Z-canary.N) is never an installed release; detectBrandlabCanaryRelease reads it.
+    if (versions.some((version) => !version || !isBrandlabSemver(version) || CANARY_VERSION_PATTERN.test(version))) {
         return null;
+    }
     return new Set(versions).size === 1 ? versions[0] : null;
 }
+/**
+ * Reads one canary prerelease across all four packages, pinned exactly (`3.14.0-canary.2`) or installed from
+ * the packed tarball (`file:.canary/brandlab-digital-site-core-3.14.0-canary.2.tgz`). A canary previews the line
+ * `X.Y.Z`: it is checked against that line's contract when this checker carries it, and is otherwise reported
+ * as a canary notice. Lines older than the checker's release are not supported. Never a published release.
+ */
+export function detectBrandlabCanaryRelease(packageJson, release = BRANDLAB_CURRENT_RUNTIME_RELEASE) {
+    if (!packageJson)
+        return null;
+    const versions = BRANDLAB_SHARED_PACKAGE_NAMES.map((packageName) => {
+        const spec = packageJson.dependencies?.[packageName] ?? packageJson.devDependencies?.[packageName];
+        if (!spec)
+            return null;
+        if (CANARY_VERSION_PATTERN.test(spec))
+            return spec;
+        if (!spec.startsWith("file:"))
+            return null;
+        const tarballPrefix = `brandlab-digital-${packageName.split("/")[1]}-`;
+        const fileName = spec.slice("file:".length).split("/").at(-1) ?? "";
+        if (!fileName.startsWith(tarballPrefix) || !fileName.endsWith(".tgz"))
+            return null;
+        const version = fileName.slice(tarballPrefix.length, -".tgz".length);
+        return CANARY_VERSION_PATTERN.test(version) ? version : null;
+    });
+    const [version] = versions;
+    if (!version || versions.some((candidate) => candidate !== version))
+        return null;
+    const line = CANARY_VERSION_PATTERN.exec(version)[1];
+    const contract = line === release.releaseVersion ? "embedded" : "not-cut";
+    return { version, line, contract };
+}
+function inspectCanary(options) {
+    const { canary } = options;
+    recordEvaluation(options.evaluations, "release", "brandlab-release-unsupported");
+    if (compareBrandlabSemver(canary.line, options.release) < 0) {
+        options.findings.push(releaseFinding("brandlab-release-unsupported", `A published release, or a canary of ${options.release} or later`, `${canary.version} is a canary of an older line than ${options.release}.`, "Install the published release or a current canary."));
+        return;
+    }
+    recordEvaluation(options.evaluations, "release", "brandlab-release-canary");
+    options.findings.push({
+        ...releaseFinding("brandlab-release-canary", "A published Brandlab release", canary.contract === "embedded"
+            ? `${canary.version} is a canary of ${canary.line}, not a published release; it was checked against the ${canary.line} contract.`
+            : `${canary.version} is a canary of ${canary.line}, not a published release; ${canary.line} has no release contract yet.`, `Install the published ${canary.line} before release or launch.`, "package.json"),
+        severity: "warning",
+    });
+    recordEvaluation(options.evaluations, "release", "brandlab-release-package-lock");
+    if (options.packageLock.state !== "valid") {
+        options.findings.push(releaseFinding(`brandlab-release-package-lock-${options.packageLock.state}`, "A valid npm lockfile v2 or v3", `package-lock.json state is ${options.packageLock.state}.`, "Regenerate the lockfile from the exact package declarations.", "package-lock.json"));
+        return;
+    }
+    recordEvaluation(options.evaluations, "release", "brandlab-release-package-pin-mismatch");
+    for (const packageName of BRANDLAB_SHARED_PACKAGE_NAMES) {
+        const declared = declaredPackageSpec(options.packageJson, packageName);
+        const locked = lockedRootSpec(options.packageLock, packageName);
+        const resolved = options.packageLock.resolvedPackages.get(packageName);
+        if (locked !== declared || resolved?.version !== canary.version || resolved.linked) {
+            options.findings.push(releaseFinding("brandlab-release-package-pin-mismatch", `${packageName}@${canary.version} declared once and locked exactly`, `package.json=${declared ?? "missing"}; lockfile=${locked ?? "missing"}; resolved=${resolved?.version ?? "missing"}.`, "Reinstall the four canary packages together and regenerate the lockfile.", "package.json"));
+        }
+    }
+    if (options.manifest) {
+        inspectRuntime({
+            findings: options.findings,
+            evaluations: options.evaluations,
+            packageJson: options.packageJson,
+            packageLock: options.packageLock,
+            manifest: options.manifest,
+        });
+    }
+}
 function inspectRelease(options) {
     recordEvaluation(options.evaluations, "release", "brandlab-release-package-json-missing");
     if (!options.packageJson) {
@@ -251,6 +329,18 @@ function inspectRelease(options) {
         return;
     }
     recordEvaluation(options.evaluations, "release", "brandlab-release-installed-version-unresolved");
+    if (!options.installedRelease && options.canary) {
+        inspectCanary({
+            findings: options.findings,
+            evaluations: options.evaluations,
+            packageJson: options.packageJson,
+            packageLock: options.packageLock,
+            canary: options.canary,
+            release: options.releaseVersion,
+            manifest: options.manifest,
+        });
+        return;
+    }
     if (!options.installedRelease) {
         options.findings.push(releaseFinding("brandlab-release-installed-version-unresolved", "All four Brandlab packages pinned to one exact release", "The installed Brandlab release could not be resolved.", "Pin all four packages to one exact supported version."));
         return;