@brandlab-digital/conformance 3.7.0 → 3.8.0

package/dist/site-system/rules/shell/proof-numbers.js

@@ -0,0 +1,81 @@
+import { closest, collapseWhitespace } from "./html.js";
+import { elementAt } from "./page.js";
+import { failFinding, passFinding, sampledPages } from "./types.js";
+/**
+ * T4: no hard-coded rating or review numbers. A number that reads as a rating ("4.9 stars", "5.0 rating", "4.8 out of
+ * 5") or a review count ("from 132 reviews") has to sit inside an element the Google feed renders: a `data-bl="stars"`
+ * element, the `summary` slot of the reviews section, a `data-bl-source="feed"` marker, or a customer's own review
+ * text. Anything else is typed by hand.
+ */
+/** Words that, straight after "out of 5", show the number counts something other than a rating ("3 out of 5 leaks"). */
+const NOT_AFTER_OUT_OF_FIVE = "(?!\\s+(?!(?:stars?|reviews?|ratings?|google|customers?|clients?|homeowners?|people|users)\\b)[a-z]{3,}s\\b)";
+/** What may follow "rated 4" or "rating of 4.9": the end of the phrase, "out of 5", "stars" or a place it was rated. */
+const AFTER_RATED_NUMBER = "(?=\\s*(?:$|[.,;:!?)\\]]|\\/\\s*5|out\\b|stars?\\b|on\\b|from\\b|by\\b|at\\b|across\\b|with\\b|and\\b|in\\b))";
+const RATING_PATTERNS = [
+    new RegExp(`(?<![\\d.])[1-5](?:\\.\\d)?\\s*(?:\\/\\s*5|out\\s+of\\s+5)\\b${NOT_AFTER_OUT_OF_FIVE}`, "gi"),
+    /(?<![\d.])[1-5](?:\.\d)?[\s-]*(?:stars?|star[- ]rat(?:ed|ing))\b/gi,
+    /(?<![\d.])[1-5](?:\.\d)?\s*(?:rating|rated)\b/gi,
+    new RegExp(`\\b(?:rated|rating(?:\\s+of)?|scores?|scored)\\s*[:-]?\\s*[1-5](?:\\.\\d)?\\b${AFTER_RATED_NUMBER}`, "gi"),
+    /(?<![\d,.$])\d{1,3}(?:,\d{3})*\+?\s+(?:(?:five|5)[- ]star\s+)?(?:(?:google|verified|customer|client)\s+)*(?:reviews?|ratings?)\b/gi,
+    /[\u2605\u2b50]\s*[1-5](?:\.\d)?\b|\b[1-5](?:\.\d)?\s*[\u2605\u2b50]/gu,
+];
+/** Star ratings that rate a product or a supply, not the business: energy and water labels, phases, solar. */
+const NOT_A_REVIEW_RATING = /\b(?:energy|wels|nathers|water[- ]efficien\w*|appliances?|phase|solar|inverters?|kw|kva)\b/i;
+const REVIEW_WORDS = /\b(?:google|reviews?|customers?|clients?|testimonials?)\b/i;
+const CUSTOMER_TEXT_SLOTS = new Set(["list", "item", "review", "text", "body", "quote", "author"]);
+/** Whether the element is rendered from the feed, or is a customer's own words. */
+export function isFeedRendered(element) {
+    return closest(element, (candidate) => {
+        if (candidate.attrs["data-bl"] === "stars" || candidate.attrs["data-bl-source"] === "feed")
+            return true;
+        if (candidate.tag === "blockquote" || candidate.attrs.itemprop === "reviewBody")
+            return true;
+        const slot = candidate.attrs["data-slot"];
+        if (slot === undefined)
+            return false;
+        const inReviews = closest(candidate, (ancestor) => ancestor.attrs["data-bl-section"] === "reviews") !== null;
+        return inReviews && (slot === "summary" || CUSTOMER_TEXT_SLOTS.has(slot));
+    }) !== null;
+}
+/** The stretches of text that read as a rating or review count, overlapping matches merged. */
+function ratingRanges(text) {
+    const ranges = RATING_PATTERNS.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => ({ start: match.index, end: match.index + match[0].length })))
+        .sort((left, right) => left.start - right.start || right.end - left.end);
+    const merged = [];
+    const counts = (range) => {
+        const own = text.slice(range.start, range.end);
+        if (REVIEW_WORDS.test(own))
+            return true;
+        return !NOT_A_REVIEW_RATING.test(text.slice(Math.max(0, range.start - 30), range.end + 30));
+    };
+    for (const range of ranges) {
+        const last = merged[merged.length - 1];
+        if (last && range.start <= last.end)
+            last.end = Math.max(last.end, range.end);
+        else
+            merged.push({ ...range });
+    }
+    return merged.filter(counts);
+}
+export function checkProofNumbers(pages) {
+    const findings = [];
+    for (const page of pages) {
+        const quotes = new Set();
+        for (const unit of [...page.units, ...page.attributeCopy]) {
+            for (const range of ratingRanges(unit.text)) {
+                if (!isFeedRendered(elementAt(unit, range.start)))
+                    quotes.add(collapseWhitespace(unit.text.slice(range.start, range.end)));
+            }
+        }
+        for (const text of page.metadata) {
+            for (const range of ratingRanges(text))
+                quotes.add(collapseWhitespace(text.slice(range.start, range.end)));
+        }
+        if (quotes.size > 0) {
+            const shown = [...quotes].slice(0, 3).map((quote) => `"${quote}"`).join(", ");
+            findings.push(failFinding("T4", page.path, `The page ${page.path} shows a rating or review number typed by hand (${shown}) outside the Google feed.`));
+        }
+    }
+    return findings.length > 0 ? findings : [passFinding("T4", `No hard-coded rating or review numbers on ${sampledPages(pages.length)}; every one comes from the feed.`)];
+}
+//# sourceMappingURL=proof-numbers.js.map

package/dist/site-system/rules/shell/proof-numbers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-numbers.js","sourceRoot":"","sources":["../../../../src/site-system/rules/shell/proof-numbers.ts"],"names":[],"mappings":"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","sourcesContent":["import { closest, collapseWhitespace, type HtmlElement } from \"./html.js\";\nimport { elementAt, type ShellPage } from \"./page.js\";\nimport { failFinding, passFinding, sampledPages, type ShellFinding } from \"./types.js\";\n\n/**\n * T4: no hard-coded rating or review numbers. A number that reads as a rating (\"4.9 stars\", \"5.0 rating\", \"4.8 out of\n * 5\") or a review count (\"from 132 reviews\") has to sit inside an element the Google feed renders: a `data-bl=\"stars\"`\n * element, the `summary` slot of the reviews section, a `data-bl-source=\"feed\"` marker, or a customer's own review\n * text. Anything else is typed by hand.\n */\n\n/** Words that, straight after \"out of 5\", show the number counts something other than a rating (\"3 out of 5 leaks\"). */\nconst NOT_AFTER_OUT_OF_FIVE = \"(?!\\\\s+(?!(?:stars?|reviews?|ratings?|google|customers?|clients?|homeowners?|people|users)\\\\b)[a-z]{3,}s\\\\b)\";\n/** What may follow \"rated 4\" or \"rating of 4.9\": the end of the phrase, \"out of 5\", \"stars\" or a place it was rated. */\nconst AFTER_RATED_NUMBER = \"(?=\\\\s*(?:$|[.,;:!?)\\\\]]|\\\\/\\\\s*5|out\\\\b|stars?\\\\b|on\\\\b|from\\\\b|by\\\\b|at\\\\b|across\\\\b|with\\\\b|and\\\\b|in\\\\b))\";\n\nconst RATING_PATTERNS: readonly RegExp[] = [\n  new RegExp(`(?<![\\\\d.])[1-5](?:\\\\.\\\\d)?\\\\s*(?:\\\\/\\\\s*5|out\\\\s+of\\\\s+5)\\\\b${NOT_AFTER_OUT_OF_FIVE}`, \"gi\"),\n  /(?<![\\d.])[1-5](?:\\.\\d)?[\\s-]*(?:stars?|star[- ]rat(?:ed|ing))\\b/gi,\n  /(?<![\\d.])[1-5](?:\\.\\d)?\\s*(?:rating|rated)\\b/gi,\n  new RegExp(`\\\\b(?:rated|rating(?:\\\\s+of)?|scores?|scored)\\\\s*[:-]?\\\\s*[1-5](?:\\\\.\\\\d)?\\\\b${AFTER_RATED_NUMBER}`, \"gi\"),\n  /(?<![\\d,.$])\\d{1,3}(?:,\\d{3})*\\+?\\s+(?:(?:five|5)[- ]star\\s+)?(?:(?:google|verified|customer|client)\\s+)*(?:reviews?|ratings?)\\b/gi,\n  /[\\u2605\\u2b50]\\s*[1-5](?:\\.\\d)?\\b|\\b[1-5](?:\\.\\d)?\\s*[\\u2605\\u2b50]/gu,\n];\n\n/** Star ratings that rate a product or a supply, not the business: energy and water labels, phases, solar. */\nconst NOT_A_REVIEW_RATING = /\\b(?:energy|wels|nathers|water[- ]efficien\\w*|appliances?|phase|solar|inverters?|kw|kva)\\b/i;\nconst REVIEW_WORDS = /\\b(?:google|reviews?|customers?|clients?|testimonials?)\\b/i;\n\nconst CUSTOMER_TEXT_SLOTS = new Set([\"list\", \"item\", \"review\", \"text\", \"body\", \"quote\", \"author\"]);\n\n/** Whether the element is rendered from the feed, or is a customer's own words. */\nexport function isFeedRendered(element: HtmlElement): boolean {\n  return closest(element, (candidate) => {\n    if (candidate.attrs[\"data-bl\"] === \"stars\" || candidate.attrs[\"data-bl-source\"] === \"feed\") return true;\n    if (candidate.tag === \"blockquote\" || candidate.attrs.itemprop === \"reviewBody\") return true;\n    const slot = candidate.attrs[\"data-slot\"];\n    if (slot === undefined) return false;\n    const inReviews = closest(candidate, (ancestor) => ancestor.attrs[\"data-bl-section\"] === \"reviews\") !== null;\n    return inReviews && (slot === \"summary\" || CUSTOMER_TEXT_SLOTS.has(slot));\n  }) !== null;\n}\n\n/** The stretches of text that read as a rating or review count, overlapping matches merged. */\nfunction ratingRanges(text: string): { start: number; end: number }[] {\n  const ranges = RATING_PATTERNS.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => ({ start: match.index, end: match.index + match[0].length })))\n    .sort((left, right) => left.start - right.start || right.end - left.end);\n  const merged: { start: number; end: number }[] = [];\n  const counts = (range: { start: number; end: number }) => {\n    const own = text.slice(range.start, range.end);\n    if (REVIEW_WORDS.test(own)) return true;\n    return !NOT_A_REVIEW_RATING.test(text.slice(Math.max(0, range.start - 30), range.end + 30));\n  };\n  for (const range of ranges) {\n    const last = merged[merged.length - 1];\n    if (last && range.start <= last.end) last.end = Math.max(last.end, range.end);\n    else merged.push({ ...range });\n  }\n  return merged.filter(counts);\n}\n\nexport function checkProofNumbers(pages: readonly ShellPage[]): ShellFinding[] {\n  const findings: ShellFinding[] = [];\n  for (const page of pages) {\n    const quotes = new Set<string>();\n    for (const unit of [...page.units, ...page.attributeCopy]) {\n      for (const range of ratingRanges(unit.text)) {\n        if (!isFeedRendered(elementAt(unit, range.start))) quotes.add(collapseWhitespace(unit.text.slice(range.start, range.end)));\n      }\n    }\n    for (const text of page.metadata) {\n      for (const range of ratingRanges(text)) quotes.add(collapseWhitespace(text.slice(range.start, range.end)));\n    }\n    if (quotes.size > 0) {\n      const shown = [...quotes].slice(0, 3).map((quote) => `\"${quote}\"`).join(\", \");\n      findings.push(failFinding(\"T4\", page.path, `The page ${page.path} shows a rating or review number typed by hand (${shown}) outside the Google feed.`));\n    }\n  }\n  return findings.length > 0 ? findings : [passFinding(\"T4\", `No hard-coded rating or review numbers on ${sampledPages(pages.length)}; every one comes from the feed.`)];\n}\n"]}

package/dist/site-system/rules/shell/types.d.ts

@@ -0,0 +1,80 @@
+import type { SiteSystemCheckId, SiteSystemFinding } from "../../checks.js";
+import type { SiteSystemSettings } from "../../config.js";
+/** What a rendered runner receives: the sampled pages' server HTML and where the project lives. */
+export interface ShellRenderedInput {
+    /** The origin the pages were fetched from; first-party means this host. */
+    baseUrl: string;
+    pages: readonly {
+        path: string;
+        html: string;
+    }[];
+    projectRoot: string;
+    /** The gate's parsed `siteSystem` settings (null when not declared); read from brandlab.config.ts when absent. */
+    siteSystem?: SiteSystemSettings | null;
+}
+/** The runner shape `brandlab-ready` calls (the same as the gate's `SiteSystemRenderedRunner`). */
+export type ShellRenderedRunner = (input: ShellRenderedInput) => Promise<readonly SiteSystemFinding[]>;
+/**
+ * A finding, optionally marked as a warning. A warning is reported with status "pass" because the finding type has
+ * no warning status: it advises and never blocks.
+ */
+export interface ShellFinding extends SiteSystemFinding {
+    readonly severity?: "warning";
+}
+export interface ShellLicenceFact {
+    name: string;
+    identifier: string;
+    jurisdiction?: string;
+    /** The licensee, when the licence record names one that differs from the trading name. */
+    holder?: string;
+    /** ISO dates, judged by site-core's licenceRenderState: an expired licence never renders. */
+    expiresOn?: string;
+    checkedOn?: string;
+}
+/** The parts of the project's business facts the shell rules compare the pages against. */
+export interface ShellProjectFacts {
+    tradingName?: string;
+    phone?: {
+        display: string;
+        e164: string;
+        telHref: string;
+    };
+    licences: readonly ShellLicenceFact[];
+    /** Why the licence data could not be read, when it exists but is not plain data: T3 then does not run. */
+    licencesUnreadable?: string;
+    /** Project-relative files the facts were read from. */
+    sources: readonly string[];
+}
+/** Reads the bytes behind a URL the page references: a script, a stylesheet or the hero image. */
+export type ShellAssetReader = (url: URL, context: {
+    projectRoot: string;
+    baseUrl: string;
+}) => Promise<Uint8Array | undefined>;
+export interface ShellRuleOptions {
+    /** The business facts, when the caller has them; otherwise they are read from `src/data` in the project. */
+    facts?: ShellProjectFacts | null;
+    /** Test override of `siteSystem.labels`: quote labels the project records beyond the closed list (C5). */
+    labels?: readonly string[];
+    /** Test override of `siteSystem.freeQuotes`: "Get a free quote" when true, "Get a quote" when false (C5). */
+    freeQuotes?: boolean;
+    /** Test override of `siteSystem.thirdParties`: hosts (or kinds) the project records a decision for (B1). */
+    recordedThirdParties?: readonly string[];
+    /** Claims the claims register holds evidence for: a pattern id such as "since-year" or the phrase itself (E8). No config home yet. */
+    recordedClaims?: readonly string[];
+    /** Test override of `siteSystem.phones`: further numbers the business records, such as a second line (C10). */
+    recordedPhones?: readonly string[];
+    /** The date licences are judged on (T3), default now. */
+    asOf?: Date;
+    /** Page paths that advertise no licensed work, beyond the legal and utility pages (T3). */
+    licenceExemptPaths?: readonly string[];
+    /** Replaces the default asset reader (project build output, then the base URL) for B1. */
+    readAsset?: ShellAssetReader;
+}
+export type ShellCheckId = Extract<SiteSystemCheckId, "N2" | "K7" | "C5" | "C9" | "C10" | "E2" | "E8" | "T3" | "T4" | "B1" | "L10-hero">;
+export declare function passFinding(checkId: ShellCheckId, message: string, target?: string): ShellFinding;
+export declare function warningFinding(checkId: ShellCheckId, message: string, target?: string): ShellFinding;
+export declare function failFinding(checkId: ShellCheckId, target: string, message: string): ShellFinding;
+export declare function notApplicableFinding(checkId: ShellCheckId, message: string): ShellFinding;
+/** "1 sampled page" or "3 sampled pages". */
+export declare function sampledPages(count: number): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/site-system/rules/shell/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/site-system/rules/shell/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,kHAAkH;IAClH,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACxC;AAED,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;AAEvG;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,iBAAiB;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,0GAA0G;IAC1G,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;AAEhI,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,0GAA0G;IAC1G,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,6GAA6G;IAC7G,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4GAA4G;IAC5G,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,sIAAsI;IACtI,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+GAA+G;IAC/G,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yDAAyD;IACzD,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,2FAA2F;IAC3F,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,0FAA0F;IAC1F,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,iBAAiB,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,UAAU,CAAC,CAAC;AAEzI,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAEjG;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAEpG;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAEhG;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAEzF;AAED,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/site-system/rules/shell/types.js

@@ -0,0 +1,17 @@
+export function passFinding(checkId, message, target) {
+    return target === undefined ? { checkId, status: "pass", message } : { checkId, status: "pass", target, message };
+}
+export function warningFinding(checkId, message, target) {
+    return { ...passFinding(checkId, message, target), severity: "warning" };
+}
+export function failFinding(checkId, target, message) {
+    return { checkId, status: "fail", target, message };
+}
+export function notApplicableFinding(checkId, message) {
+    return { checkId, status: "not-applicable", message };
+}
+/** "1 sampled page" or "3 sampled pages". */
+export function sampledPages(count) {
+    return `${count} sampled page${count === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/site-system/rules/shell/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/site-system/rules/shell/types.ts"],"names":[],"mappings":"AAwEA,MAAM,UAAU,WAAW,CAAC,OAAqB,EAAE,OAAe,EAAE,MAAe;IACjF,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACpH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAqB,EAAE,OAAe,EAAE,MAAe;IACpF,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAqB,EAAE,MAAc,EAAE,OAAe;IAChF,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAqB,EAAE,OAAe;IACzE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC;AACxD,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,GAAG,KAAK,gBAAgB,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC1D,CAAC","sourcesContent":["import type { SiteSystemCheckId, SiteSystemFinding } from \"../../checks.js\";\nimport type { SiteSystemSettings } from \"../../config.js\";\n\n/** What a rendered runner receives: the sampled pages' server HTML and where the project lives. */\nexport interface ShellRenderedInput {\n  /** The origin the pages were fetched from; first-party means this host. */\n  baseUrl: string;\n  pages: readonly { path: string; html: string }[];\n  projectRoot: string;\n  /** The gate's parsed `siteSystem` settings (null when not declared); read from brandlab.config.ts when absent. */\n  siteSystem?: SiteSystemSettings | null;\n}\n\n/** The runner shape `brandlab-ready` calls (the same as the gate's `SiteSystemRenderedRunner`). */\nexport type ShellRenderedRunner = (input: ShellRenderedInput) => Promise<readonly SiteSystemFinding[]>;\n\n/**\n * A finding, optionally marked as a warning. A warning is reported with status \"pass\" because the finding type has\n * no warning status: it advises and never blocks.\n */\nexport interface ShellFinding extends SiteSystemFinding {\n  readonly severity?: \"warning\";\n}\n\nexport interface ShellLicenceFact {\n  name: string;\n  identifier: string;\n  jurisdiction?: string;\n  /** The licensee, when the licence record names one that differs from the trading name. */\n  holder?: string;\n  /** ISO dates, judged by site-core's licenceRenderState: an expired licence never renders. */\n  expiresOn?: string;\n  checkedOn?: string;\n}\n\n/** The parts of the project's business facts the shell rules compare the pages against. */\nexport interface ShellProjectFacts {\n  tradingName?: string;\n  phone?: { display: string; e164: string; telHref: string };\n  licences: readonly ShellLicenceFact[];\n  /** Why the licence data could not be read, when it exists but is not plain data: T3 then does not run. */\n  licencesUnreadable?: string;\n  /** Project-relative files the facts were read from. */\n  sources: readonly string[];\n}\n\n/** Reads the bytes behind a URL the page references: a script, a stylesheet or the hero image. */\nexport type ShellAssetReader = (url: URL, context: { projectRoot: string; baseUrl: string }) => Promise<Uint8Array | undefined>;\n\nexport interface ShellRuleOptions {\n  /** The business facts, when the caller has them; otherwise they are read from `src/data` in the project. */\n  facts?: ShellProjectFacts | null;\n  /** Test override of `siteSystem.labels`: quote labels the project records beyond the closed list (C5). */\n  labels?: readonly string[];\n  /** Test override of `siteSystem.freeQuotes`: \"Get a free quote\" when true, \"Get a quote\" when false (C5). */\n  freeQuotes?: boolean;\n  /** Test override of `siteSystem.thirdParties`: hosts (or kinds) the project records a decision for (B1). */\n  recordedThirdParties?: readonly string[];\n  /** Claims the claims register holds evidence for: a pattern id such as \"since-year\" or the phrase itself (E8). No config home yet. */\n  recordedClaims?: readonly string[];\n  /** Test override of `siteSystem.phones`: further numbers the business records, such as a second line (C10). */\n  recordedPhones?: readonly string[];\n  /** The date licences are judged on (T3), default now. */\n  asOf?: Date;\n  /** Page paths that advertise no licensed work, beyond the legal and utility pages (T3). */\n  licenceExemptPaths?: readonly string[];\n  /** Replaces the default asset reader (project build output, then the base URL) for B1. */\n  readAsset?: ShellAssetReader;\n}\n\nexport type ShellCheckId = Extract<SiteSystemCheckId, \"N2\" | \"K7\" | \"C5\" | \"C9\" | \"C10\" | \"E2\" | \"E8\" | \"T3\" | \"T4\" | \"B1\" | \"L10-hero\">;\n\nexport function passFinding(checkId: ShellCheckId, message: string, target?: string): ShellFinding {\n  return target === undefined ? { checkId, status: \"pass\", message } : { checkId, status: \"pass\", target, message };\n}\n\nexport function warningFinding(checkId: ShellCheckId, message: string, target?: string): ShellFinding {\n  return { ...passFinding(checkId, message, target), severity: \"warning\" };\n}\n\nexport function failFinding(checkId: ShellCheckId, target: string, message: string): ShellFinding {\n  return { checkId, status: \"fail\", target, message };\n}\n\nexport function notApplicableFinding(checkId: ShellCheckId, message: string): ShellFinding {\n  return { checkId, status: \"not-applicable\", message };\n}\n\n/** \"1 sampled page\" or \"3 sampled pages\". */\nexport function sampledPages(count: number): string {\n  return `${count} sampled page${count === 1 ? \"\" : \"s\"}`;\n}\n"]}

package/dist/site-system/runners.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The rule-module interface of the ready gate. Each module under ./rules/ exports a runner, listed in
+ * ./rule-modules.ts; `brandlab-ready` calls every runner with the sampled pages and merges what they find. Static
+ * rules use the same shape and read the project through `projectRoot`. Every runner is called even when no page
+ * could be read: static rules still run, and rendered rules return not-applicable for an empty page list (the gate
+ * fails the run itself when home or the contact page is missing).
+ */
+import { type SiteSystemFinding } from "./checks.js";
+import type { SiteSystemSettings } from "./config.js";
+import type { SiteSystemPage } from "./samples.js";
+export interface SiteSystemRenderedInput {
+    /** The running site's base URL with --base-url; empty when the pages were read from the build output. */
+    readonly baseUrl: string;
+    readonly pages: readonly SiteSystemPage[];
+    /** Planned sample paths with no HTML, so rules can say what they could not check. */
+    readonly missing: readonly string[];
+    /** The project directory, for rules that read its data files. */
+    readonly projectRoot: string;
+    /**
+     * The gate's parsed `siteSystem` settings from brandlab.config.ts (null when the site declares none). Rules use these
+     * rather than reading the config themselves; a caller that leaves it out lets each rule read the config.
+     */
+    readonly siteSystem?: SiteSystemSettings | null;
+}
+/** A rule module: one finding per check result (pass, fail or not-applicable), never a throw for a failing site. */
+export type SiteSystemRenderedRunner = (input: SiteSystemRenderedInput) => Promise<readonly SiteSystemFinding[]>;
+/**
+ * Runs each runner in turn. A runner that throws, or returns a finding for an unknown check, is reported as a
+ * problem; the checks it would have covered then show as not run, which fails them where they block.
+ */
+export declare function runSiteSystemRenderedRunners(runners: readonly SiteSystemRenderedRunner[], input: SiteSystemRenderedInput): Promise<{
+    findings: SiteSystemFinding[];
+    problems: string[];
+}>;
+/** A finding with a known check id, a known status and a message; anything else is ignored. */
+export declare function isSiteSystemFinding(value: unknown): value is SiteSystemFinding;
+//# sourceMappingURL=runners.d.ts.map

package/dist/site-system/runners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runners.d.ts","sourceRoot":"","sources":["../../src/site-system/runners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,uBAAuB;IACtC,yGAAyG;IACzG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACjD;AAED,oHAAoH;AACpH,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;AAIjH;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,SAAS,wBAAwB,EAAE,EAC5C,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC;IAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAkBhE;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAW9E"}

package/dist/site-system/runners.js

@@ -0,0 +1,48 @@
+/**
+ * The rule-module interface of the ready gate. Each module under ./rules/ exports a runner, listed in
+ * ./rule-modules.ts; `brandlab-ready` calls every runner with the sampled pages and merges what they find. Static
+ * rules use the same shape and read the project through `projectRoot`. Every runner is called even when no page
+ * could be read: static rules still run, and rendered rules return not-applicable for an empty page list (the gate
+ * fails the run itself when home or the contact page is missing).
+ */
+import { SITE_SYSTEM_CHECKS } from "./checks.js";
+const KNOWN_IDS = new Set(SITE_SYSTEM_CHECKS.map((check) => check.id));
+/**
+ * Runs each runner in turn. A runner that throws, or returns a finding for an unknown check, is reported as a
+ * problem; the checks it would have covered then show as not run, which fails them where they block.
+ */
+export async function runSiteSystemRenderedRunners(runners, input) {
+    const findings = [];
+    const problems = [];
+    for (const runner of runners) {
+        const name = runner.name || "A rule module";
+        let results;
+        try {
+            results = await runner(input);
+        }
+        catch (error) {
+            problems.push(`${name} stopped with an error (${error instanceof Error ? error.message : String(error)}), so its checks did not run.`);
+            continue;
+        }
+        for (const finding of results) {
+            if (isSiteSystemFinding(finding))
+                findings.push(finding);
+            else
+                problems.push(`${name} returned a result for an unknown check or with an unknown status, so it was ignored.`);
+        }
+    }
+    return { findings, problems };
+}
+/** A finding with a known check id, a known status and a message; anything else is ignored. */
+export function isSiteSystemFinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const finding = value;
+    return (typeof finding.checkId === "string" &&
+        KNOWN_IDS.has(finding.checkId) &&
+        (finding.status === "pass" || finding.status === "fail" || finding.status === "not-applicable") &&
+        typeof finding.message === "string" &&
+        (finding.target === undefined || typeof finding.target === "string") &&
+        (finding.severity === undefined || finding.severity === "warning"));
+}
+//# sourceMappingURL=runners.js.map

package/dist/site-system/runners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runners.js","sourceRoot":"","sources":["../../src/site-system/runners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAA0B,MAAM,aAAa,CAAC;AAsBzE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAS,kBAAkB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;AAE/E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAA4C,EAC5C,KAA8B;IAE9B,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,eAAe,CAAC;QAC5C,IAAI,OAAqC,CAAC;QAC1C,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,2BAA2B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;YACvI,SAAS;QACX,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,mBAAmB,CAAC,OAAO,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;;gBACpD,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,uFAAuF,CAAC,CAAC;QACrH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,MAAM,OAAO,GAAG,KAAgC,CAAC;IACjD,OAAO,CACL,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QACnC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC;QAC9B,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,gBAAgB,CAAC;QAC/F,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QACnC,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC;QACpE,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CACnE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The rule-module interface of the ready gate. Each module under ./rules/ exports a runner, listed in\n * ./rule-modules.ts; `brandlab-ready` calls every runner with the sampled pages and merges what they find. Static\n * rules use the same shape and read the project through `projectRoot`. Every runner is called even when no page\n * could be read: static rules still run, and rendered rules return not-applicable for an empty page list (the gate\n * fails the run itself when home or the contact page is missing).\n */\nimport { SITE_SYSTEM_CHECKS, type SiteSystemFinding } from \"./checks.js\";\nimport type { SiteSystemSettings } from \"./config.js\";\nimport type { SiteSystemPage } from \"./samples.js\";\n\nexport interface SiteSystemRenderedInput {\n  /** The running site's base URL with --base-url; empty when the pages were read from the build output. */\n  readonly baseUrl: string;\n  readonly pages: readonly SiteSystemPage[];\n  /** Planned sample paths with no HTML, so rules can say what they could not check. */\n  readonly missing: readonly string[];\n  /** The project directory, for rules that read its data files. */\n  readonly projectRoot: string;\n  /**\n   * The gate's parsed `siteSystem` settings from brandlab.config.ts (null when the site declares none). Rules use these\n   * rather than reading the config themselves; a caller that leaves it out lets each rule read the config.\n   */\n  readonly siteSystem?: SiteSystemSettings | null;\n}\n\n/** A rule module: one finding per check result (pass, fail or not-applicable), never a throw for a failing site. */\nexport type SiteSystemRenderedRunner = (input: SiteSystemRenderedInput) => Promise<readonly SiteSystemFinding[]>;\n\nconst KNOWN_IDS = new Set<string>(SITE_SYSTEM_CHECKS.map((check) => check.id));\n\n/**\n * Runs each runner in turn. A runner that throws, or returns a finding for an unknown check, is reported as a\n * problem; the checks it would have covered then show as not run, which fails them where they block.\n */\nexport async function runSiteSystemRenderedRunners(\n  runners: readonly SiteSystemRenderedRunner[],\n  input: SiteSystemRenderedInput,\n): Promise<{ findings: SiteSystemFinding[]; problems: string[] }> {\n  const findings: SiteSystemFinding[] = [];\n  const problems: string[] = [];\n  for (const runner of runners) {\n    const name = runner.name || \"A rule module\";\n    let results: readonly SiteSystemFinding[];\n    try {\n      results = await runner(input);\n    } catch (error) {\n      problems.push(`${name} stopped with an error (${error instanceof Error ? error.message : String(error)}), so its checks did not run.`);\n      continue;\n    }\n    for (const finding of results) {\n      if (isSiteSystemFinding(finding)) findings.push(finding);\n      else problems.push(`${name} returned a result for an unknown check or with an unknown status, so it was ignored.`);\n    }\n  }\n  return { findings, problems };\n}\n\n/** A finding with a known check id, a known status and a message; anything else is ignored. */\nexport function isSiteSystemFinding(value: unknown): value is SiteSystemFinding {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n  const finding = value as Record<string, unknown>;\n  return (\n    typeof finding.checkId === \"string\" &&\n    KNOWN_IDS.has(finding.checkId) &&\n    (finding.status === \"pass\" || finding.status === \"fail\" || finding.status === \"not-applicable\") &&\n    typeof finding.message === \"string\" &&\n    (finding.target === undefined || typeof finding.target === \"string\") &&\n    (finding.severity === undefined || finding.severity === \"warning\")\n  );\n}\n"]}

package/dist/site-system/samples.d.ts

@@ -0,0 +1,43 @@
+export { resolveStreamedHtml } from "./streamed-html.js";
+export interface SiteSystemPage {
+    /** Root-relative path, for example `/services/roofing`. */
+    readonly path: string;
+    readonly html: string;
+}
+/** The fetch subset the loader uses, so tests can stand in for a site. */
+export type SiteSystemFetch = (url: string, init: {
+    headers: Record<string, string>;
+    redirect: "follow";
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+export interface SiteSystemPageLoad {
+    readonly pages: readonly SiteSystemPage[];
+    /** Planned paths with no HTML: no prerendered file, or no 200 HTML answer from the base URL. */
+    readonly missing: readonly string[];
+    /** Where the HTML came from. */
+    readonly source: "base-url" | "build";
+    readonly problems: readonly string[];
+}
+/** Sample paths in a stable order, without duplicates. `prerenderManifest` is `.next/prerender-manifest.json`. */
+export declare function planSiteSystemSamplePaths(input: {
+    representativeRoutes: Readonly<Record<string, string>>;
+    samples?: readonly string[];
+    prerenderManifest?: unknown;
+}): string[];
+/** The prerendered HTML file Next writes for a path. */
+export declare function builtPageFile(buildDir: string, path: string): string;
+export declare function loadSiteSystemPages(input: {
+    paths: readonly string[];
+    /** Absolute build directory (`.next`). */
+    buildDir: string;
+    baseUrl?: string;
+    fetch?: SiteSystemFetch;
+}): Promise<SiteSystemPageLoad>;
+//# sourceMappingURL=samples.d.ts.map

package/dist/site-system/samples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"samples.d.ts","sourceRoot":"","sources":["../../src/site-system/samples.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAChF,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AAEtH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,gGAAgG;IAChG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAMD,kHAAkH;AAClH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,MAAM,EAAE,CA4BX;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsC9B"}

package/dist/site-system/samples.js

@@ -0,0 +1,99 @@
+/**
+ * The pages the rendered checks read: home, the contact page, the other representative routes, one page for each
+ * other route of the production build (the first path Next prerendered for it, which comes from the route
+ * catalogue) and the site's `siteSystem.samples`. With a base URL they are fetched from the running site;
+ * otherwise their prerendered HTML is read from the build output (`.next/server/app/<path>.html`). Either way the
+ * streamed Suspense segments are put in place first (`resolveStreamedHtml`), so every runner reads the content a
+ * browser shows, not the fallback.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveStreamedHtml } from "./streamed-html.js";
+export { resolveStreamedHtml } from "./streamed-html.js";
+const REPRESENTATIVE_ORDER = ["home", "contact", "service", "location", "blog"];
+const INTERNAL_ROUTES = new Set(["/_not-found", "/_global-error", "/404", "/500"]);
+const FETCH_TIMEOUT_MS = 30_000;
+/** Sample paths in a stable order, without duplicates. `prerenderManifest` is `.next/prerender-manifest.json`. */
+export function planSiteSystemSamplePaths(input) {
+    const paths = ["/"];
+    const representative = Object.entries(input.representativeRoutes).sort(([left], [right]) => rank(left) - rank(right) || left.localeCompare(right));
+    for (const [, path] of representative)
+        paths.push(path);
+    const routes = isRecord(input.prerenderManifest) && isRecord(input.prerenderManifest.routes)
+        ? input.prerenderManifest.routes
+        : {};
+    const appRouteOf = (path) => {
+        const entry = routes[path];
+        return isRecord(entry) && typeof entry.srcRoute === "string" ? entry.srcRoute : undefined;
+    };
+    // A route a representative page or a sample already covers needs no second page.
+    const seenRoutes = new Set([...paths, ...(input.samples ?? [])].flatMap((path) => appRouteOf(path) ?? []));
+    for (const [path, entry] of Object.entries(routes)) {
+        if (!isRecord(entry) || !path.startsWith("/"))
+            continue;
+        const appRoute = typeof entry.srcRoute === "string" ? entry.srcRoute : path;
+        if (INTERNAL_ROUTES.has(appRoute) || seenRoutes.has(appRoute))
+            continue;
+        // Next 15+ marks route handlers (robots, sitemaps, icons); older manifests only show them by their extension.
+        if (entry.routeType !== undefined ? entry.routeType !== "page" : /\.[a-z0-9]+$/i.test(path))
+            continue;
+        seenRoutes.add(appRoute);
+        paths.push(path);
+    }
+    paths.push(...(input.samples ?? []));
+    return [...new Set(paths)];
+}
+/** The prerendered HTML file Next writes for a path. */
+export function builtPageFile(buildDir, path) {
+    return join(buildDir, "server", "app", `${path === "/" ? "/index" : path.replace(/\/+$/, "")}.html`);
+}
+export async function loadSiteSystemPages(input) {
+    const pages = [];
+    const missing = [];
+    const problems = [];
+    if (input.baseUrl) {
+        const fetcher = input.fetch ?? globalThis.fetch;
+        const base = input.baseUrl.replace(/\/+$/, "");
+        for (const path of input.paths) {
+            try {
+                const response = await fetcher(`${base}${path}`, {
+                    headers: { accept: "text/html" },
+                    redirect: "follow",
+                    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+                });
+                const type = response.headers.get("content-type") ?? "";
+                if (response.ok && (!type || type.includes("text/html"))) {
+                    pages.push({ path, html: resolveStreamedHtml(await response.text()) });
+                    continue;
+                }
+                problems.push(response.ok
+                    ? `GET ${path} answered ${type}, not HTML.`
+                    : `GET ${path} answered ${response.status}.`);
+            }
+            catch (error) {
+                problems.push(`GET ${path} failed (${error instanceof Error ? error.message : String(error)}).`);
+            }
+            missing.push(path);
+        }
+        return { pages, missing, source: "base-url", problems };
+    }
+    for (const path of input.paths) {
+        const file = builtPageFile(input.buildDir, path);
+        if (existsSync(file))
+            pages.push({ path, html: resolveStreamedHtml(readFileSync(file, "utf8")) });
+        else
+            missing.push(path);
+    }
+    if (missing.length > 0) {
+        problems.push(`No prerendered HTML in the build for ${missing.join(", ")}; pass --base-url to fetch them from the running site.`);
+    }
+    return { pages, missing, source: "build", problems };
+}
+function rank(name) {
+    const index = REPRESENTATIVE_ORDER.indexOf(name);
+    return index === -1 ? REPRESENTATIVE_ORDER.length : index;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=samples.js.map

package/dist/site-system/samples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"samples.js","sourceRoot":"","sources":["../../src/site-system/samples.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pages the rendered checks read: home, the contact page, the other representative routes, one page for each\n * other route of the production build (the first path Next prerendered for it, which comes from the route\n * catalogue) and the site's `siteSystem.samples`. With a base URL they are fetched from the running site;\n * otherwise their prerendered HTML is read from the build output (`.next/server/app/<path>.html`). Either way the\n * streamed Suspense segments are put in place first (`resolveStreamedHtml`), so every runner reads the content a\n * browser shows, not the fallback.\n */\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { resolveStreamedHtml } from \"./streamed-html.js\";\n\nexport { resolveStreamedHtml } from \"./streamed-html.js\";\n\nexport interface SiteSystemPage {\n  /** Root-relative path, for example `/services/roofing`. */\n  readonly path: string;\n  readonly html: string;\n}\n\n/** The fetch subset the loader uses, so tests can stand in for a site. */\nexport type SiteSystemFetch = (\n  url: string,\n  init: { headers: Record<string, string>; redirect: \"follow\"; signal?: AbortSignal },\n) => Promise<{ ok: boolean; status: number; headers: { get(name: string): string | null }; text(): Promise<string> }>;\n\nexport interface SiteSystemPageLoad {\n  readonly pages: readonly SiteSystemPage[];\n  /** Planned paths with no HTML: no prerendered file, or no 200 HTML answer from the base URL. */\n  readonly missing: readonly string[];\n  /** Where the HTML came from. */\n  readonly source: \"base-url\" | \"build\";\n  readonly problems: readonly string[];\n}\n\nconst REPRESENTATIVE_ORDER = [\"home\", \"contact\", \"service\", \"location\", \"blog\"];\nconst INTERNAL_ROUTES = new Set([\"/_not-found\", \"/_global-error\", \"/404\", \"/500\"]);\nconst FETCH_TIMEOUT_MS = 30_000;\n\n/** Sample paths in a stable order, without duplicates. `prerenderManifest` is `.next/prerender-manifest.json`. */\nexport function planSiteSystemSamplePaths(input: {\n  representativeRoutes: Readonly<Record<string, string>>;\n  samples?: readonly string[];\n  prerenderManifest?: unknown;\n}): string[] {\n  const paths = [\"/\"];\n  const representative = Object.entries(input.representativeRoutes).sort(\n    ([left], [right]) => rank(left) - rank(right) || left.localeCompare(right),\n  );\n  for (const [, path] of representative) paths.push(path);\n  const routes = isRecord(input.prerenderManifest) && isRecord(input.prerenderManifest.routes)\n    ? input.prerenderManifest.routes\n    : {};\n  const appRouteOf = (path: string) => {\n    const entry = routes[path];\n    return isRecord(entry) && typeof entry.srcRoute === \"string\" ? entry.srcRoute : undefined;\n  };\n  // A route a representative page or a sample already covers needs no second page.\n  const seenRoutes = new Set<string>(\n    [...paths, ...(input.samples ?? [])].flatMap((path) => appRouteOf(path) ?? []),\n  );\n  for (const [path, entry] of Object.entries(routes)) {\n    if (!isRecord(entry) || !path.startsWith(\"/\")) continue;\n    const appRoute = typeof entry.srcRoute === \"string\" ? entry.srcRoute : path;\n    if (INTERNAL_ROUTES.has(appRoute) || seenRoutes.has(appRoute)) continue;\n    // Next 15+ marks route handlers (robots, sitemaps, icons); older manifests only show them by their extension.\n    if (entry.routeType !== undefined ? entry.routeType !== \"page\" : /\\.[a-z0-9]+$/i.test(path)) continue;\n    seenRoutes.add(appRoute);\n    paths.push(path);\n  }\n  paths.push(...(input.samples ?? []));\n  return [...new Set(paths)];\n}\n\n/** The prerendered HTML file Next writes for a path. */\nexport function builtPageFile(buildDir: string, path: string): string {\n  return join(buildDir, \"server\", \"app\", `${path === \"/\" ? \"/index\" : path.replace(/\\/+$/, \"\")}.html`);\n}\n\nexport async function loadSiteSystemPages(input: {\n  paths: readonly string[];\n  /** Absolute build directory (`.next`). */\n  buildDir: string;\n  baseUrl?: string;\n  fetch?: SiteSystemFetch;\n}): Promise<SiteSystemPageLoad> {\n  const pages: SiteSystemPage[] = [];\n  const missing: string[] = [];\n  const problems: string[] = [];\n  if (input.baseUrl) {\n    const fetcher = input.fetch ?? (globalThis.fetch as unknown as SiteSystemFetch);\n    const base = input.baseUrl.replace(/\\/+$/, \"\");\n    for (const path of input.paths) {\n      try {\n        const response = await fetcher(`${base}${path}`, {\n          headers: { accept: \"text/html\" },\n          redirect: \"follow\",\n          signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),\n        });\n        const type = response.headers.get(\"content-type\") ?? \"\";\n        if (response.ok && (!type || type.includes(\"text/html\"))) {\n          pages.push({ path, html: resolveStreamedHtml(await response.text()) });\n          continue;\n        }\n        problems.push(response.ok\n          ? `GET ${path} answered ${type}, not HTML.`\n          : `GET ${path} answered ${response.status}.`);\n      } catch (error) {\n        problems.push(`GET ${path} failed (${error instanceof Error ? error.message : String(error)}).`);\n      }\n      missing.push(path);\n    }\n    return { pages, missing, source: \"base-url\", problems };\n  }\n  for (const path of input.paths) {\n    const file = builtPageFile(input.buildDir, path);\n    if (existsSync(file)) pages.push({ path, html: resolveStreamedHtml(readFileSync(file, \"utf8\")) });\n    else missing.push(path);\n  }\n  if (missing.length > 0) {\n    problems.push(`No prerendered HTML in the build for ${missing.join(\", \")}; pass --base-url to fetch them from the running site.`);\n  }\n  return { pages, missing, source: \"build\", problems };\n}\n\nfunction rank(name: string): number {\n  const index = REPRESENTATIVE_ORDER.indexOf(name);\n  return index === -1 ? REPRESENTATIVE_ORDER.length : index;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === \"object\" && !Array.isArray(value);\n}\n"]}

package/dist/site-system/steps.d.ts

@@ -0,0 +1,66 @@
+export interface SiteSystemStep {
+    readonly id: string;
+    readonly summary: string;
+}
+export declare const SITE_SYSTEM_LAUNCH_STEPS: readonly [{
+    readonly id: "T2";
+    readonly summary: "The Business Profile matches the site: name, phone, primary category, services, service area, hours and description.";
+}, {
+    readonly id: "T3-R";
+    readonly summary: "Each licence checked on the NSW register within 30 days and not expired (warning inside 60 days of expiry).";
+}, {
+    readonly id: "C6";
+    readonly summary: "Launch proof: a delivered test enquiry with a photo, the contact_form hit, a test phone tap and the next-day GA4 read; the owner saw it; the test marker kept every hit out of reporting.";
+}, {
+    readonly id: "X3";
+    readonly summary: "The Codex second opinion (codex review --base main); real findings fixed or answered.";
+}, {
+    readonly id: "X4";
+    readonly summary: "Production environment variable names present (values never read) and the domain resolves.";
+}, {
+    readonly id: "X5";
+    readonly summary: "Rollback recorded and the cutover inside the window.";
+}, {
+    readonly id: "X6";
+    readonly summary: "The legacy security sweep is done.";
+}, {
+    readonly id: "X7";
+    readonly summary: "Ads final URLs and the Business Profile's tagged website URL mapped and handed to Codex.";
+}, {
+    readonly id: "X8";
+    readonly summary: "No sentence shared with a related or same-trade client's site, library strings included.";
+}, {
+    readonly id: "X9";
+    readonly summary: "DNS diff before and after cutover (MX, SPF, DKIM, DMARC, verification TXT) and a test email into and out of the client's mailbox.";
+}, {
+    readonly id: "X10";
+    readonly summary: "The sending domain is verified in Resend with SPF and DKIM, and DMARC is present.";
+}];
+export declare const SITE_SYSTEM_HUMAN_STEPS: readonly [{
+    readonly id: "truth-pass";
+    readonly summary: "Truth pass (the builder, 30 to 60 min): the claims and evidence table.";
+}, {
+    readonly id: "trust-carry-over";
+    readonly summary: "Trust carry-over (the builder, 20 min): every old badge, claim, price and review block kept, or held with a reason.";
+}, {
+    readonly id: "usefulness-read";
+    readonly summary: "Head-page usefulness test and 5-page side-by-side read per family (the builder, 20 min per family): pass, or the pages fixed.";
+}, {
+    readonly id: "codex-second-opinion";
+    readonly summary: "Codex second opinion (one run, one fix round): findings, then fixed or answered.";
+}, {
+    readonly id: "launch-proof";
+    readonly summary: "Launch proof (the builder, 10 min): the delivered email timestamp and the captured hits.";
+}, {
+    readonly id: "look-pick";
+    readonly summary: "Look pick and side-by-side packs (Romie, one reply each): A, B, yes or a note.";
+}];
+export type SiteSystemLaunchStepId = (typeof SITE_SYSTEM_LAUNCH_STEPS)[number]["id"];
+export type SiteSystemHumanStepId = (typeof SITE_SYSTEM_HUMAN_STEPS)[number]["id"];
+/** `launch` is docs/ready/launch.json, `human` is docs/ready/human.json. */
+export type SiteSystemRecordFile = "launch" | "human";
+/** Registry checks that are recorded rather than run (K10 harness parity, X1 legacy URLs). */
+export declare const SITE_SYSTEM_RECORDED_CHECK_IDS: readonly string[];
+/** The records file an id is recorded in, or null when the id is not a step or a recorded check. */
+export declare function siteSystemRecordFile(id: string): SiteSystemRecordFile | null;
+//# sourceMappingURL=steps.d.ts.map

package/dist/site-system/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../src/site-system/steps.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYS,CAAC;AAE/C,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;EAOU,CAAC;AAE/C,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AACrF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAEnF,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtD,8FAA8F;AAC9F,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAEjC,CAAC;AAK5B,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAI5E"}

package/dist/site-system/steps.js

@@ -0,0 +1,45 @@
+/**
+ * The launch-day agent steps (§13.3) and the time-boxed human steps (§13.6) the ready report lists.
+ *
+ * Each is recorded with `brandlab-ready record <id> --evidence <ref>`: launch-day steps, and the registry's
+ * `record` checks (K10, X1), go to docs/ready/launch.json; human steps go to docs/ready/human.json. A site is
+ * launch-ready only when every step is recorded; a default run reports missing steps without failing, and
+ * `brandlab-ready --launch` fails until they are all recorded.
+ */
+import { SITE_SYSTEM_CHECKS } from "./checks.js";
+export const SITE_SYSTEM_LAUNCH_STEPS = [
+    { id: "T2", summary: "The Business Profile matches the site: name, phone, primary category, services, service area, hours and description." },
+    { id: "T3-R", summary: "Each licence checked on the NSW register within 30 days and not expired (warning inside 60 days of expiry)." },
+    { id: "C6", summary: "Launch proof: a delivered test enquiry with a photo, the contact_form hit, a test phone tap and the next-day GA4 read; the owner saw it; the test marker kept every hit out of reporting." },
+    { id: "X3", summary: "The Codex second opinion (codex review --base main); real findings fixed or answered." },
+    { id: "X4", summary: "Production environment variable names present (values never read) and the domain resolves." },
+    { id: "X5", summary: "Rollback recorded and the cutover inside the window." },
+    { id: "X6", summary: "The legacy security sweep is done." },
+    { id: "X7", summary: "Ads final URLs and the Business Profile's tagged website URL mapped and handed to Codex." },
+    { id: "X8", summary: "No sentence shared with a related or same-trade client's site, library strings included." },
+    { id: "X9", summary: "DNS diff before and after cutover (MX, SPF, DKIM, DMARC, verification TXT) and a test email into and out of the client's mailbox." },
+    { id: "X10", summary: "The sending domain is verified in Resend with SPF and DKIM, and DMARC is present." },
+];
+export const SITE_SYSTEM_HUMAN_STEPS = [
+    { id: "truth-pass", summary: "Truth pass (the builder, 30 to 60 min): the claims and evidence table." },
+    { id: "trust-carry-over", summary: "Trust carry-over (the builder, 20 min): every old badge, claim, price and review block kept, or held with a reason." },
+    { id: "usefulness-read", summary: "Head-page usefulness test and 5-page side-by-side read per family (the builder, 20 min per family): pass, or the pages fixed." },
+    { id: "codex-second-opinion", summary: "Codex second opinion (one run, one fix round): findings, then fixed or answered." },
+    { id: "launch-proof", summary: "Launch proof (the builder, 10 min): the delivered email timestamp and the captured hits." },
+    { id: "look-pick", summary: "Look pick and side-by-side packs (Romie, one reply each): A, B, yes or a note." },
+];
+/** Registry checks that are recorded rather than run (K10 harness parity, X1 legacy URLs). */
+export const SITE_SYSTEM_RECORDED_CHECK_IDS = SITE_SYSTEM_CHECKS
+    .filter((check) => check.kind === "record")
+    .map((check) => check.id);
+const LAUNCH_IDS = new Set([...SITE_SYSTEM_LAUNCH_STEPS.map((step) => step.id), ...SITE_SYSTEM_RECORDED_CHECK_IDS]);
+const HUMAN_IDS = new Set(SITE_SYSTEM_HUMAN_STEPS.map((step) => step.id));
+/** The records file an id is recorded in, or null when the id is not a step or a recorded check. */
+export function siteSystemRecordFile(id) {
+    if (LAUNCH_IDS.has(id))
+        return "launch";
+    if (HUMAN_IDS.has(id))
+        return "human";
+    return null;
+}
+//# sourceMappingURL=steps.js.map