create-ailk 0.30.0 → 0.32.0

package/dist/lib/render-comparison.d.ts

@@ -0,0 +1,251 @@
+/** The two viewports every page is compared at. */
+export declare const VIEWPORTS: readonly [{
+    readonly name: "desktop";
+    readonly width: 1440;
+    readonly height: 900;
+}, {
+    readonly name: "mobile";
+    readonly width: 390;
+    readonly height: 844;
+}];
+/** Requests in flight at once, for a sweep or a crawl. */
+export declare const IN_FLIGHT = 4;
+/** The page's words: `main`'s rendered text, else `body`'s. */
+export declare const TEXT_EXPRESSION = "(() => { const root = document.querySelector(\"main\") ?? document.body; return root ? root.innerText : \"\"; })()";
+/** Every JSON-LD script's text, in document order. */
+export declare const JSONLD_EXPRESSION = "Array.from(document.querySelectorAll('script[type=\"application/ld+json\"]'), (s) => s.textContent ?? \"\")";
+/**
+ * A Language item #10734's kind pull lists on /faq or /glossary after the pins,
+ * which step 1 reported as a top-up: removed from the after side only.
+ */
+export interface ExcludedItem {
+    kind: "faq" | "term";
+    slug: string;
+    /** The question or term the read renders it with. */
+    name: string;
+}
+/** `removed` names every excluded key; `refused` says why nothing was excluded. */
+export type Exclusion = {
+    removed: string[];
+} | {
+    refused: string;
+};
+/**
+ * Plain JS run in the after page, so no transform reaches it. Under the kind
+ * pull's position rule (#10734 D3) it removes exactly the reported items, or
+ * removes nothing and answers why: FAQs are the tail of the last `faq`
+ * section's items, matched by question; terms are the tail of their letter
+ * group in the last `glossary-index` section, matched by slug, and a letter
+ * group they leave empty goes with its nav link. A reason never carries an
+ * item's words.
+ */
+export declare const EXCLUDE_SOURCE = "function (document, exclude) {\n  var norm = function (s) { return String(s).replace(/\\s+/g, \" \").trim(); };\n  var firstLine = function (el) {\n    var lines = String(el.innerText || \"\").split(\"\\n\");\n    for (var i = 0; i < lines.length; i++) if (norm(lines[i]) !== \"\") return norm(lines[i]);\n    return \"\";\n  };\n  var last = function (selector) {\n    var all = document.querySelectorAll(selector);\n    return all.length === 0 ? null : all[all.length - 1];\n  };\n  var byTestId = function (root, id) {\n    return Array.from(root.querySelectorAll(\"[data-testid]\")).filter(function (el) { return el.getAttribute(\"data-testid\") === id; });\n  };\n  var faqs = exclude.filter(function (t) { return t.kind === \"faq\"; });\n  var terms = exclude.filter(function (t) { return t.kind === \"term\"; });\n  var items = [];\n  if (faqs.length > 0) {\n    var faq = last('[data-section=\"faq\"]');\n    if (faq === null) return { refused: \"no faq section\" };\n    var all = Array.from(faq.querySelectorAll('[data-testid=\"faq-item-expanded\"], [data-testid=\"faq-item-accordion\"], [data-testid=\"faq-item-grid\"]'));\n    var left = faqs.slice();\n    for (var i = Math.max(0, all.length - faqs.length); i < all.length; i++) {\n      var line = firstLine(all[i]);\n      var at = left.findIndex(function (t) { return norm(t.name) === line; });\n      if (at < 0) return { refused: \"item \" + (i + 1) + \" of \" + all.length + \" in the last faq section is not a reported top-up\" };\n      left.splice(at, 1);\n      items.push(all[i]);\n    }\n    if (left.length > 0) return { refused: \"the last faq section has \" + all.length + \" item(s), fewer than its \" + faqs.length + \" top-up(s)\" };\n  }\n  var glossary = null;\n  var termItems = [];\n  if (terms.length > 0) {\n    glossary = last('[data-section=\"glossary-index\"]');\n    if (glossary === null) return { refused: \"no glossary-index section\" };\n    for (var j = 0; j < terms.length; j++) {\n      var links = byTestId(glossary, \"glossary-index-term-\" + terms[j].slug);\n      var li = links.length === 1 ? links[0].closest(\"li\") : null;\n      if (li === null) return { refused: \"term \" + terms[j].slug + \" is not shown once in the last glossary-index section\" };\n      termItems.push(li);\n    }\n    for (var k = 0; k < terms.length; k++) {\n      var siblings = Array.from(termItems[k].parentElement.children);\n      var later = siblings.slice(siblings.indexOf(termItems[k]) + 1);\n      if (later.some(function (el) { return termItems.indexOf(el) < 0; })) {\n        return { refused: \"term \" + terms[k].slug + \" is not at the tail of its letter group\" };\n      }\n    }\n  }\n  items.forEach(function (el) { el.remove(); });\n  var lists = [];\n  termItems.forEach(function (el) {\n    if (lists.indexOf(el.parentElement) < 0) lists.push(el.parentElement);\n    el.remove();\n  });\n  lists.forEach(function (ul) {\n    if (ul.children.length > 0) return;\n    var group = ul.closest(\"section[data-letter]\");\n    if (group === null) return;\n    var link = byTestId(glossary, \"glossary-index-letter-\" + group.getAttribute(\"data-letter\"))[0];\n    group.remove();\n    if (link === undefined) return;\n    var nav = link.closest(\"nav\");\n    link.remove();\n    if (nav !== null && nav.children.length === 0) nav.remove();\n  });\n  return { removed: exclude.map(function (t) { return t.kind + \"/\" + t.slug; }) };\n}";
+/** The expression the after page evaluates: `EXCLUDE_SOURCE` called on a JSON literal. */
+export declare function exclusionExpression(exclude: readonly ExcludedItem[]): string;
+/**
+ * The after side's JSON-LD without the top-ups' nodes: per kind, the one array
+ * holding a matching node (a `Question` by `name`, a `DefinedTerm` by
+ * `termCode`) must end in exactly those nodes and keep one other. The script
+ * that changed is re-serialized with `serializeJsonLd`'s rule
+ * (`packages/schema/src/json-ld.ts`, restated: no runtime import); every other
+ * keeps its string. Anything else is `refused`, with the scripts untouched.
+ */
+export declare function excludeJsonLd(scripts: readonly string[], exclude: readonly ExcludedItem[]): {
+    scripts: string[];
+} | {
+    refused: string;
+};
+/** An image as 8-bit RGBA, row-major. */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+export type DecodedPng = {
+    ok: true;
+    image: RgbaImage;
+} | {
+    ok: false;
+    reason: "unsupported-png";
+};
+/**
+ * An 8-bit RGB or RGBA, non-interlaced PNG as RGBA, every scanline filter
+ * undone. Anything else — another depth or colour type, interlacing, a
+ * truncated or corrupt stream — is `unsupported-png`.
+ */
+export declare function decodePng(png: Buffer): DecodedPng;
+/** How many pixels differ in any channel, or `size-differs`. */
+export declare function diffPixels(a: RgbaImage, b: RgbaImage): number | "size-differs";
+export type TextVerdict = {
+    verdict: "same";
+} | {
+    verdict: "differs";
+    line: number;
+    before: string;
+    after: string;
+} | {
+    verdict: "not-compared";
+};
+export type JsonLdVerdict = {
+    verdict: "same";
+} | {
+    verdict: "differs";
+    index: number;
+    before: string | null;
+    after: string | null;
+} | {
+    verdict: "not-compared";
+};
+export type PixelVerdict = {
+    verdict: "same" | "within-tolerance" | "differs";
+    differing: number;
+    total: number;
+} | {
+    verdict: "size-differs" | "unsupported-png" | "not-compared";
+};
+/** Whitespace runs collapsed, then line for line; `differs` names the first differing line (1-based). */
+export declare function compareText(before: string, after: string): TextVerdict;
+/** `same` only when the two arrays are equal string for string — never after a parse. */
+export declare function compareJsonLd(before: readonly string[], after: readonly string[]): JsonLdVerdict;
+/** The slice of a Playwright `Page` the comparison uses. */
+export interface ComparisonPage {
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    goto(url: string, options: {
+        waitUntil: "load";
+        timeout: number;
+    }): Promise<{
+        status(): number;
+    } | null>;
+    url(): string;
+    evaluate(expression: string): Promise<unknown>;
+    screenshot(options: {
+        fullPage: true;
+        animations: "disabled";
+    }): Promise<Buffer>;
+}
+export interface ViewportComparison {
+    viewport: string;
+    /** `ok`, or why that side did not render. */
+    render: {
+        before: string;
+        after: string;
+    };
+    text: TextVerdict;
+    jsonLd: JsonLdVerdict;
+    /** Absent when the comparison takes no screenshots (the verify step). */
+    pixels?: PixelVerdict;
+    /** `afterFull`: the after page before its exclusion, for the eye read. */
+    shots?: {
+        before: string;
+        after: string;
+        afterFull?: string;
+    };
+    /** Present only on a page with top-ups whose after side rendered (#10753). */
+    exclusion?: Exclusion;
+}
+export interface PageComparison {
+    path: string;
+    n: number;
+    pass: boolean;
+    viewports: ViewportComparison[];
+    /** The excluded top-ups' keys, when every viewport removed them (#10753). */
+    excluded?: string[];
+}
+interface Side {
+    origin: string;
+    page: ComparisonPage;
+}
+export interface ComparePageOptions {
+    path: string;
+    /** The page's number in the run, naming its screenshots. */
+    n: number;
+    before: Side;
+    after: Side;
+    /** The share of pixels that may differ; `0` is exact. */
+    tolerance: number;
+    screenshots: boolean;
+    /** Stores one screenshot under `shots/<name>`. */
+    writeShot: (name: string, png: Buffer) => void;
+    /** The top-ups removed from the after side before it is read (#10753); `[]` is none. */
+    exclude?: readonly ExcludedItem[];
+}
+/** One frozen URL at every viewport, before against after. */
+export declare function comparePage(o: ComparePageOptions): Promise<PageComparison>;
+/** `fn` over `items`, at most `limit` at once; results in input order. */
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+export interface SweepResult {
+    pass: boolean;
+    /** One row per path, in the order given; `status` 0 for a network failure. */
+    results: {
+        path: string;
+        status: number;
+    }[];
+}
+/** Every path on `origin` must answer 200 directly; a redirect is not a 200. */
+export declare function sweep(o: {
+    origin: string;
+    paths: readonly string[];
+    fetch: typeof globalThis.fetch;
+    headers?: Record<string, string>;
+}): Promise<SweepResult>;
+export interface ComparisonReport {
+    before: string;
+    after: string;
+    pages: PageComparison[];
+    sweep: SweepResult;
+}
+/** The eye-read table: one row per URL and viewport, linking its screenshot pair. */
+export declare function comparisonMarkdown(report: ComparisonReport): string;
+/** `comparison.json` and `comparison.md` in `dir`; the screenshots are already in `dir/shots`. */
+export declare function writeComparisonEvidence(dir: string, report: ComparisonReport): void;
+/** The slice of a Playwright route the header scoping uses. */
+interface RouteLike {
+    request(): {
+        url(): string;
+        headers(): Record<string, string>;
+    };
+    continue(options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+}
+/** The slice of Playwright's `chromium` the comparison launches. */
+export interface ChromiumLike {
+    launch(): Promise<{
+        newContext(): Promise<{
+            newPage(): Promise<ComparisonPage & {
+                route(url: string, handler: (route: RouteLike) => Promise<void>): Promise<void>;
+            }>;
+        }>;
+        close(): Promise<void>;
+    }>;
+}
+export declare const PLAYWRIGHT_INSTALL_HINT = "pnpm add -D @playwright/test && pnpm exec playwright install chromium";
+/** `chromium` from `playwright` or `@playwright/test`, resolved from each dir in turn. */
+export declare function loadChromium(dirs: readonly string[]): ChromiumLike | undefined;
+export interface RunComparisonOptions {
+    chromium: ChromiumLike;
+    before: string;
+    after: string;
+    /** Headers the `after` origin's requests carry (a preview's protection bypass). */
+    afterHeaders?: Record<string, string>;
+    /** The frozen page paths compared in the browser. */
+    pages: readonly string[];
+    /** Every frozen path swept on `after`. */
+    sweepPaths: readonly string[];
+    tolerance: number;
+    screenshots: boolean;
+    /** Where `comparison.json`, `comparison.md` and `shots/` go. */
+    dir: string;
+    fetch: typeof globalThis.fetch;
+    onLine?: (line: string) => void;
+    /** Per frozen page path, the top-ups its after side leaves out (#10753). */
+    exclude?: Readonly<Record<string, readonly ExcludedItem[]>>;
+}
+/** Every page compared, the sweep run, the evidence written; `pass` gates the step. */
+export declare function runComparison(o: RunComparisonOptions): Promise<ComparisonReport & {
+    pass: boolean;
+}>;
+export {};