@speedkit/cli 4.26.0 → 4.27.1

package/dist/services/prewarm/csv-reader.spec.js

@@ -0,0 +1,75 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { CsvReader } from "./csv-reader.js";
+function write(content) {
+    const file = join(mkdtempSync(join(tmpdir(), "sk-csv-")), "urls.csv");
+    writeFileSync(file, content, "utf8");
+    return file;
+}
+/** The urls of a list, for the cases that say nothing about variations. */
+function read(content) {
+    return readList(content).map(({ url }) => url);
+}
+function readList(content) {
+    return new CsvReader().readList(write(content));
+}
+describe("CsvReader", () => {
+    it("should read a bare list of urls", () => {
+        expect(read("https://a.de/\nhttps://b.de/\n")).to.deep.equal([
+            "https://a.de/",
+            "https://b.de/",
+        ]);
+    });
+    it("should read quoted urls", () => {
+        expect(read('"https://a.de/"\n"https://b.de/"')).to.deep.equal([
+            "https://a.de/",
+            "https://b.de/",
+        ]);
+    });
+    it("should take only the first column", () => {
+        // What `sk query prewarm --execute` writes: url and hit count.
+        expect(read('"url","hits"\n"https://a.de/",12\n"https://b.de/",3')).to.deep.eq(["https://a.de/", "https://b.de/"]);
+    });
+    it("should skip a header row", () => {
+        expect(read("url\nhttps://a.de/")).to.deep.equal(["https://a.de/"]);
+    });
+    it("should keep a comma inside a quoted url", () => {
+        expect(read('"https://a.de/?list=1,2",7')).to.deep.equal([
+            "https://a.de/?list=1,2",
+        ]);
+    });
+    it("should read a doubled quote as one quote", () => {
+        expect(read('"https://a.de/?q=""x"""')).to.deep.equal([
+            'https://a.de/?q="x"',
+        ]);
+    });
+    it("should drop empty lines", () => {
+        expect(read("https://a.de/\n\n\nhttps://b.de/\n")).to.have.lengthOf(2);
+    });
+    it("should read the variation of a split list", () => {
+        // What `sk query prewarm --device desktop,mobile --execute` writes.
+        expect(readList('"url","variation","hits"\n"https://a.de/","mobile",12\n"https://a.de/","desktop",3')).to.deep.equal([
+            { url: "https://a.de/", variation: "mobile" },
+            { url: "https://a.de/", variation: "desktop" },
+        ]);
+    });
+    it("should not read a hit count as a variation", () => {
+        expect(readList('"url","hits"\n"https://a.de/",12')).to.deep.equal([
+            { url: "https://a.de/" },
+        ]);
+    });
+    it("should not read a second column of a headerless list", () => {
+        expect(readList('"https://a.de/","mobile"')).to.deep.equal([
+            { url: "https://a.de/" },
+        ]);
+    });
+    it("should keep a comma inside a quoted url of a split list", () => {
+        expect(readList('url,variation\n"https://a.de/?list=1,2",mobile')).to.deep.equal([{ url: "https://a.de/?list=1,2", variation: "mobile" }]);
+    });
+    it("should read a plain list of values", () => {
+        expect(new CsvReader().readValues(write("desktop\nmobile\n"))).to.deep.equal(["desktop", "mobile"]);
+    });
+});

package/dist/services/prewarm/index.d.ts

@@ -2,3 +2,4 @@ export * from "./pre-warm-service.js";
 export * from "./pre-warm-factory.js";
 export * from "./auto-pre-warm-factory.js";
 export * from "./pre-warm-model.js";
+export * from "./prewarm-targets.js";

package/dist/services/prewarm/index.js

@@ -2,3 +2,4 @@ export * from "./pre-warm-service.js";
 export * from "./pre-warm-factory.js";
 export * from "./auto-pre-warm-factory.js";
 export * from "./pre-warm-model.js";
+export * from "./prewarm-targets.js";

package/dist/services/prewarm/pre-warm-factory.d.ts

@@ -4,8 +4,6 @@ export declare class PreWarmFactory {
     private context;
     constructor(context: PreWarmContext);
     getService(): Promise<PreWarmService>;
-    private getUrls;
-    private getVariations;
 }
 /**
  * Resolve the list of variations to prewarm: a `variationPath` CSV takes

package/dist/services/prewarm/pre-warm-factory.js

@@ -1,5 +1,5 @@
 import { CliContext, CliServiceFactory } from "../cli/index.js";
-import { DEFAULT_VARIATION, PreWarmService, VARIATION_SEPARATOR, } from "./index.js";
+import { DEFAULT_VARIATION, PreWarmService, toPrewarmTargets, VARIATION_SEPARATOR, } from "./index.js";
 import { AssetApiClient } from "./assets/asset-api-client.js";
 import { CsvReader } from "./csv-reader.js";
 import { ConfigApiContext, ConfigApiServiceFactory, } from "../config-api/index.js";
@@ -14,15 +14,12 @@ export class PreWarmFactory {
         const entityManager = await configApi.client.getEntityManager();
         const csvReader = new CsvReader();
         const assetApiClient = new AssetApiClient(entityManager.token, this.context.app, this.context.keepParameterSorting);
-        const urls = this.getUrls(csvReader);
-        const variations = this.getVariations(csvReader);
-        return new PreWarmService(assetApiClient, cli, urls, variations, this.context.verbose);
-    }
-    getUrls(csvReader) {
-        return csvReader.readPath(this.context.path);
-    }
-    getVariations(csvReader) {
-        return resolveVariations(csvReader, this.context.variation, this.context.variationPath);
+        const rows = csvReader.readList(this.context.path);
+        const named = this.context.variation ?? this.context.variationPath;
+        if (named && rows.some((row) => row.variation)) {
+            cli.writeWarning(`The list names a variation for every url, so ${named} is not used`);
+        }
+        return new PreWarmService(assetApiClient, cli, toPrewarmTargets(rows, resolveVariations(csvReader, this.context.variation, this.context.variationPath)), this.context.verbose);
     }
 }
 /**
@@ -37,7 +34,7 @@ export function resolveVariations(csvReader, variation, variationPath) {
         variations = variation.split(VARIATION_SEPARATOR);
     }
     if (variationPath) {
-        variations = csvReader.readPath(variationPath);
+        variations = csvReader.readValues(variationPath);
     }
     return variations;
 }

package/dist/services/prewarm/pre-warm-model.d.ts

@@ -8,6 +8,20 @@ export declare class PreWarmContext {
     readonly verbose: boolean;
     constructor(app: string, path: string, variation?: string, variationPath?: string, keepParameterSorting?: boolean, quiet?: boolean, verbose?: boolean);
 }
+/**
+ * One url to warm, in one variation. A pre-warm list is a list of these: the
+ * variation is a fact about the url, not a dimension crossed over the whole
+ * list, so a url seen only on phones is warmed only as `mobile`.
+ */
+export interface PrewarmTarget {
+    readonly url: string;
+    readonly variation: string;
+}
+/** A row of a pre-warm list, which may or may not name a variation yet. */
+export interface PrewarmRow {
+    readonly url: string;
+    readonly variation?: string;
+}
 export interface AssetItemInterface {
     done(): void;
     error?: Error;
@@ -36,4 +50,3 @@ export declare const TIMING_HEADER_KEY = "server-timing";
 export declare const PROGRESS_BAR_FORMAT = "[{bar}] {percentage}% | ETA: {eta_formatted}s | {value}/{total} | error:{errors} | rate: {rate} | retry: {retry} | batchDur: {batchDuration}";
 export declare const VARIATION_SEPARATOR = ",";
 export declare const DEFAULT_VARIATION: string[];
-export declare const DEFAULT_VARIATIONS: string[];

package/dist/services/prewarm/pre-warm-model.js

@@ -36,4 +36,3 @@ export const TIMING_HEADER_KEY = "server-timing";
 export const PROGRESS_BAR_FORMAT = "[{bar}] {percentage}% | ETA: {eta_formatted}s | {value}/{total} | error:{errors} | rate: {rate} | retry: {retry} | batchDur: {batchDuration}";
 export const VARIATION_SEPARATOR = ",";
 export const DEFAULT_VARIATION = ["default"];
-export const DEFAULT_VARIATIONS = ["mobile", "tablet", "tv"];

package/dist/services/prewarm/pre-warm-service.d.ts

@@ -1,19 +1,24 @@
 import { CliServiceInterface } from "../cli/index.js";
-import { AssetItemInterface } from "./index.js";
+import { AssetItemInterface, PrewarmTarget } from "./index.js";
 import { AssetApiClient } from "./assets/asset-api-client.js";
 export declare class PreWarmService {
     private assetClient;
     private cli;
-    private urls;
-    private variations;
+    private targets;
     private verbose;
     private requestsSend;
-    constructor(assetClient: AssetApiClient, cli: CliServiceInterface, urls: string[], variations: string[], verbose: boolean);
+    constructor(assetClient: AssetApiClient, cli: CliServiceInterface, targets: readonly PrewarmTarget[], verbose: boolean);
     handleAsset(assetClient: AssetApiClient, entry: AssetItemInterface): Promise<void>;
     run(): Promise<void>;
     private fetchAssetList;
     private handleProgress;
     private fetchUrls;
+    /**
+     * The request list, in the order the targets were given. The order is the
+     * caller's to decide — a list built by device interleaves the variations, so
+     * that a run cut short has warmed the busiest entries of each rather than
+     * all of one and none of the next.
+     */
     private generateAssetRequestList;
     private printSummary;
     private startProgressBar;

package/dist/services/prewarm/pre-warm-service.js

@@ -5,15 +5,13 @@ import { AssetList } from "./assets/asset-list.js";
 export class PreWarmService {
     assetClient;
     cli;
-    urls;
-    variations;
+    targets;
     verbose;
     requestsSend = 0;
-    constructor(assetClient, cli, urls, variations, verbose) {
+    constructor(assetClient, cli, targets, verbose) {
         this.assetClient = assetClient;
         this.cli = cli;
-        this.urls = urls;
-        this.variations = variations;
+        this.targets = targets;
         this.verbose = verbose;
     }
     async handleAsset(assetClient, entry) {
@@ -49,7 +47,7 @@ export class PreWarmService {
         entry.setError(new Error(`status: ${response.status}, sk-error: ${serverTimingErrorCode}`));
     }
     async run() {
-        const assetList = this.generateAssetRequestList(this.urls);
+        const assetList = this.generateAssetRequestList(this.targets);
         await this.fetchUrls(assetList);
         await this.printSummary(assetList);
         if (assetList.getRetryCount() === 0) {
@@ -58,10 +56,12 @@ export class PreWarmService {
         this.cli.write("Retry rateLimited requests.");
         // reset for minimal output
         this.requestsSend = 0;
-        const urlsToRetry = assetList
+        // Rebuilt from the items themselves: they already carry the variation they
+        // were rate-limited in, and crossing their urls with anything else would
+        // both re-expand the list and lose that pairing.
+        const retryList = this.generateAssetRequestList(assetList
             .getByStatus(ItemStatus.RETRY)
-            .map((entry) => entry.url);
-        const retryList = this.generateAssetRequestList(urlsToRetry);
+            .map(({ url, variation }) => ({ url, variation })));
         this.assetClient.setIsRetry();
         await this.fetchUrls(retryList);
         await this.printSummary(retryList);
@@ -109,12 +109,16 @@ export class PreWarmService {
         await this.fetchAssetList(assetList);
         this.stopProgressBar();
     }
-    generateAssetRequestList(urls) {
+    /**
+     * The request list, in the order the targets were given. The order is the
+     * caller's to decide — a list built by device interleaves the variations, so
+     * that a run cut short has warmed the busiest entries of each rather than
+     * all of one and none of the next.
+     */
+    generateAssetRequestList(targets) {
         const assetList = new AssetList();
-        for (const variation of this.variations) {
-            for (const url of urls) {
-                assetList.addItem(new AssetItem(url, variation));
-            }
+        for (const { url, variation } of targets) {
+            assetList.addItem(new AssetItem(url, variation));
         }
         return assetList;
     }

package/dist/services/prewarm/prewarm-targets.d.ts

@@ -0,0 +1,12 @@
+import { PrewarmRow, PrewarmTarget } from "./pre-warm-model.js";
+/**
+ * The (url, variation) pairs to warm.
+ *
+ * A list that already names a variation per url is taken as it stands — its
+ * order is the one whoever built it chose, and every pair in it was actually
+ * requested. A list of bare urls is crossed with the variations the caller
+ * named, url-major: each url is warmed in every variation before the next url
+ * is touched, so a run cut short has warmed whole pages rather than one
+ * variation of all of them.
+ */
+export declare function toPrewarmTargets(rows: readonly PrewarmRow[], variations: readonly string[]): PrewarmTarget[];

package/dist/services/prewarm/prewarm-targets.js

@@ -0,0 +1,18 @@
+/**
+ * The (url, variation) pairs to warm.
+ *
+ * A list that already names a variation per url is taken as it stands — its
+ * order is the one whoever built it chose, and every pair in it was actually
+ * requested. A list of bare urls is crossed with the variations the caller
+ * named, url-major: each url is warmed in every variation before the next url
+ * is touched, so a run cut short has warmed whole pages rather than one
+ * variation of all of them.
+ */
+export function toPrewarmTargets(rows, variations) {
+    if (rows.some((row) => row.variation)) {
+        return rows
+            .filter((row) => row.variation)
+            .map(({ url, variation }) => ({ url, variation }));
+    }
+    return rows.flatMap(({ url }) => variations.map((variation) => ({ url, variation })));
+}

package/dist/services/prewarm/prewarm-targets.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/prewarm/prewarm-targets.spec.js

@@ -0,0 +1,29 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { toPrewarmTargets } from "./prewarm-targets.js";
+describe("toPrewarmTargets", () => {
+    it("should keep a paired list in the order it was given", () => {
+        // The order is the query's interleaving of the variations by hit count:
+        // grouping or sorting it here would undo the point of the split.
+        const rows = [
+            { url: "https://a.de/", variation: "mobile" },
+            { url: "https://b.de/", variation: "desktop" },
+            { url: "https://a.de/", variation: "desktop" },
+        ];
+        expect(toPrewarmTargets(rows, ["default"])).to.deep.equal(rows);
+    });
+    it("should not cross a paired list with the variations", () => {
+        expect(toPrewarmTargets([{ url: "https://a.de/", variation: "mobile" }], ["men", "women"])).to.have.lengthOf(1);
+    });
+    it("should cross a bare list url-major", () => {
+        expect(toPrewarmTargets([{ url: "https://a.de/" }, { url: "https://b.de/" }], ["desktop", "mobile"])).to.deep.equal([
+            { url: "https://a.de/", variation: "desktop" },
+            { url: "https://a.de/", variation: "mobile" },
+            { url: "https://b.de/", variation: "desktop" },
+            { url: "https://b.de/", variation: "mobile" },
+        ]);
+    });
+    it("should warm nothing when there is no variation to warm in", () => {
+        expect(toPrewarmTargets([{ url: "https://a.de/" }], [])).to.deep.equal([]);
+    });
+});

package/dist/services/query-builder/error/match-matches-nothing-error.d.ts

@@ -0,0 +1,11 @@
+import ApplicationError from "../../error-handling/error/application-error.js";
+/**
+ * A `--match` pattern the config can never let through.
+ *
+ * The query would be valid and return nothing, after a full Athena scan. This
+ * stops before the query is sent.
+ */
+export declare class MatchMatchesNothingError extends ApplicationError {
+    readonly code = "MATCH_MATCHES_NOTHING";
+    constructor(reason: string);
+}

package/dist/services/query-builder/error/match-matches-nothing-error.js

@@ -0,0 +1,17 @@
+import ApplicationError from "../../error-handling/error/application-error.js";
+/**
+ * A `--match` pattern the config can never let through.
+ *
+ * The query would be valid and return nothing, after a full Athena scan. This
+ * stops before the query is sent.
+ */
+export class MatchMatchesNothingError extends ApplicationError {
+    code = "MATCH_MATCHES_NOTHING";
+    constructor(reason) {
+        super(`--match ${reason}`);
+        this.suggestions = [
+            "the pattern is matched against the url without its scheme, e.g. www.shop.de/p/1",
+            "check the pattern against the config's enabledSites, disabledSites and blacklist",
+        ];
+    }
+}

package/dist/services/query-builder/queries/device.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The device classes a pre-warm list can be split by.
+ *
+ * These are the variation names Speed Kit computes from the user agent, not
+ * the values `rum.pi` records — see {@link DEVICE_COLUMN_VALUES} for the
+ * translation. `Robot` is not one of them: a query never counts bots.
+ *
+ * A custom variation (`desktop-pdp-a`, `abtest_b`, `men`) can never be derived
+ * from a device, so it cannot be a value here — `--variation` puts those into
+ * the list by hand.
+ */
+export declare const DEVICE_VARIATIONS: readonly ["desktop", "mobile", "tablet"];
+export type DeviceVariation = (typeof DEVICE_VARIATIONS)[number];
+/** How `rum.pi` spells each of them in its `device` column. */
+export declare const DEVICE_COLUMN_VALUES: Record<DeviceVariation, string>;
+/**
+ * The requested devices in the canonical order, without duplicates — so the
+ * same request always produces the same SQL, whatever order the flag was
+ * given in.
+ */
+export declare function normalizeDevices(devices: readonly string[] | undefined): DeviceVariation[];

package/dist/services/query-builder/queries/device.js

@@ -0,0 +1,26 @@
+/**
+ * The device classes a pre-warm list can be split by.
+ *
+ * These are the variation names Speed Kit computes from the user agent, not
+ * the values `rum.pi` records — see {@link DEVICE_COLUMN_VALUES} for the
+ * translation. `Robot` is not one of them: a query never counts bots.
+ *
+ * A custom variation (`desktop-pdp-a`, `abtest_b`, `men`) can never be derived
+ * from a device, so it cannot be a value here — `--variation` puts those into
+ * the list by hand.
+ */
+export const DEVICE_VARIATIONS = ["desktop", "mobile", "tablet"];
+/** How `rum.pi` spells each of them in its `device` column. */
+export const DEVICE_COLUMN_VALUES = {
+    desktop: "Desktop",
+    mobile: "Mobile",
+    tablet: "Tablet",
+};
+/**
+ * The requested devices in the canonical order, without duplicates — so the
+ * same request always produces the same SQL, whatever order the flag was
+ * given in.
+ */
+export function normalizeDevices(devices) {
+    return DEVICE_VARIATIONS.filter((device) => devices?.includes(device));
+}

package/dist/services/query-builder/queries/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./device.js";
+export * from "./page-filter.js";
+export * from "./parameter-query.js";
+export * from "./pops-query.js";
+export * from "./prewarm-query.js";
+export * from "./query-model.js";

package/dist/services/query-builder/queries/index.js

@@ -0,0 +1,6 @@
+export * from "./device.js";
+export * from "./page-filter.js";
+export * from "./parameter-query.js";
+export * from "./pops-query.js";
+export * from "./prewarm-query.js";
+export * from "./query-model.js";

package/dist/services/query-builder/queries/page-filter.d.ts

@@ -0,0 +1,39 @@
+import { Predicate } from "../sql/index.js";
+import { RuleNote, RuleSubjectExpressions } from "../rules/index.js";
+import { QueryInput } from "./query-model.js";
+export interface RuleFilter {
+    readonly approximated: RuleNote[];
+    readonly dropped: RuleNote[];
+    /** Findings about the config itself, worth reporting on their own. */
+    readonly findings: RuleNote[];
+    readonly predicate: Predicate;
+    /** Rules left out because another rule already decides their pages. */
+    readonly reduced: RuleNote[];
+    readonly warnings: string[];
+}
+/**
+ * Which page impressions a query counts at all: the app's own traffic in the
+ * requested window, without the noise the caller asked to leave out.
+ *
+ * Bots are always excluded — a crawler requests pages no real user asks for,
+ * and neither pre-warming nor a parameter analysis should be driven by them.
+ * Naming the device classes to keep subsumes that: `Robot` is not one of them,
+ * and `in` leaves out a null device the same way `<> 'Robot'` does.
+ */
+export declare function buildRowFilter(input: QueryInput): Predicate;
+/**
+ * Which of those pages Speed Kit accelerates.
+ *
+ * The rule sets are combined the way the runtime evaluates them:
+ * `enabledSites` decides first and an empty set means every page, then
+ * `disabledSites` takes pages away; `whitelist` and `blacklist` do the same
+ * for the document as a resource. `disabledScopes` takes away whatever the
+ * service worker never claims in the first place.
+ *
+ * Before that, the sets are ruled against each other. Each set loses the rules
+ * a sibling already covers, and the two excluding sets additionally lose every
+ * rule that excludes pages the including sets never let through — which is
+ * most of a real blacklist, since it guards paths `enabledSites` never
+ * allowed. What remains is the part of the config the data can actually see.
+ */
+export declare function buildRuleFilter(input: QueryInput, subjects: RuleSubjectExpressions): RuleFilter;

package/dist/services/query-builder/queries/page-filter.js

@@ -0,0 +1,135 @@
+import { and, call, column, equals, FALSE, greaterOrEqual, inValues, leaf, literal, not, notEquals, TRUE, } from "../sql/index.js";
+import { absorbRules, asPathWithSearchRule, buildMatchRule, dropUnreachableRules, findShadowedRules, keepRelevantRules, reductionBudget, translateRules, } from "../rules/index.js";
+import { MatchMatchesNothingError } from "../error/match-matches-nothing-error.js";
+import { DEVICE_COLUMN_VALUES, normalizeDevices } from "./device.js";
+import { sinceDate } from "./query-model.js";
+/** The navigation types that are a full document load. */
+const HARD_NAVIGATION_TYPES = ["NAVIGATE", "RELOAD", "BACK_FORWARD"];
+/**
+ * Which page impressions a query counts at all: the app's own traffic in the
+ * requested window, without the noise the caller asked to leave out.
+ *
+ * Bots are always excluded — a crawler requests pages no real user asks for,
+ * and neither pre-warming nor a parameter analysis should be driven by them.
+ * Naming the device classes to keep subsumes that: `Robot` is not one of them,
+ * and `in` leaves out a null device the same way `<> 'Robot'` does.
+ */
+export function buildRowFilter(input) {
+    const devices = normalizeDevices(input.devices);
+    return and(equals(column("app"), literal(input.app)), greaterOrEqual(column("date"), literal(sinceDate(input.days, input.now))), devices.length > 0
+        ? inValues(column("device"), devices.map((device) => DEVICE_COLUMN_VALUES[device]))
+        : notEquals(column("device"), literal("Robot")), input.hardNavigationsOnly
+        ? inValues(column("navigationtype"), HARD_NAVIGATION_TYPES)
+        : TRUE, input.excludeSuspicious ? not(isSet("suspicious")) : TRUE, input.excludeNoindex ? not(isSet("noindex")) : TRUE);
+}
+/**
+ * Which of those pages Speed Kit accelerates.
+ *
+ * The rule sets are combined the way the runtime evaluates them:
+ * `enabledSites` decides first and an empty set means every page, then
+ * `disabledSites` takes pages away; `whitelist` and `blacklist` do the same
+ * for the document as a resource. `disabledScopes` takes away whatever the
+ * service worker never claims in the first place.
+ *
+ * Before that, the sets are ruled against each other. Each set loses the rules
+ * a sibling already covers, and the two excluding sets additionally lose every
+ * rule that excludes pages the including sets never let through — which is
+ * most of a real blacklist, since it guards paths `enabledSites` never
+ * allowed. What remains is the part of the config the data can actually see.
+ */
+export function buildRuleFilter(input, subjects) {
+    const { ruleSets } = input;
+    const approximated = [];
+    const dropped = [];
+    const reduced = [];
+    const warnings = [];
+    // One budget for the whole build, so the reductions cannot add up.
+    const budget = reductionBudget();
+    /** The rules of a set that can apply to a page impression at all. */
+    const relevant = (rules) => {
+        const result = keepRelevantRules(rules, { hosts: input.hosts });
+        approximated.push(...result.approximated);
+        dropped.push(...result.dropped);
+        return result.rules;
+    };
+    /** What a sibling rule already covers, dropped. */
+    const absorb = (rules) => {
+        const absorbed = absorbRules(rules, budget);
+        reduced.push(...absorbed.notes);
+        return absorbed.rules;
+    };
+    const translate = (rules, whenEmpty) => {
+        const translation = translateRules(rules, subjects, { whenEmpty });
+        warnings.push(...translation.warnings);
+        return translation.predicate;
+    };
+    const whitelist = absorb(relevant(ruleSets.whitelist));
+    const enabledSites = absorb(relevant(ruleSets.enabledSites));
+    // An empty including set lets everything through, so it constrains nothing.
+    const reachable = [enabledSites, whitelist].filter((set) => set.length > 0);
+    /**
+     * Reachability first, absorption second.
+     *
+     * Both shorten the query, but dropping what can never fire is the reduction
+     * that carries a real config — most of a blacklist guards pages
+     * `enabledSites` never allowed — while absorbing a sibling is cosmetic and
+     * costs a comparison for every pair of entries. Spending the budget in that
+     * order means a config that runs out of it still got the reduction worth
+     * having, and absorption then works on fewer entries.
+     */
+    const exclude = (rules) => {
+        const reachableOnly = dropUnreachableRules(rules, reachable, budget);
+        reduced.push(...reachableOnly.notes);
+        return absorb(reachableOnly.rules);
+    };
+    const excluding = [
+        relevant(ruleSets.blacklist),
+        relevant(ruleSets.disabledSites),
+        relevant(ruleSets.disabledScopes),
+    ];
+    /**
+     * The narrowing the caller asked for, held against what the config takes
+     * away.
+     *
+     * A pattern the excluding rules already cover would build a valid query,
+     * scan the whole window and return nothing, so it is refused before the
+     * query is handed over. The rules are the ones the query frame leaves, not
+     * the ones the reduction leaves: an entry dropped below because
+     * `enabledSites` never lets its pages through still says that a pattern
+     * aimed at them has nothing to warm.
+     *
+     * The comparison gets a budget of its own. It costs one comparison per
+     * excluding rule, and sharing the build's budget would mean a config large
+     * enough to spend it first is silently not checked at all.
+     */
+    const match = buildMatchRule(input.match);
+    if (match) {
+        const [shadowed] = findShadowedRules([match], excluding.flat().map(asPathWithSearchRule).filter(Boolean), reductionBudget());
+        if (shadowed) {
+            throw new MatchMatchesNothingError(shadowed.reason);
+        }
+    }
+    const [blacklist, disabledSites, disabledScopes] = excluding.map(exclude);
+    const predicate = and(translate(whitelist, TRUE), not(translate(blacklist, FALSE)), translate(enabledSites, TRUE), not(translate(disabledSites, FALSE)), 
+    // A page inside a disabled scope is served by an empty service worker, so
+    // Speed Kit never sees it at all.
+    not(translate(disabledScopes, FALSE)), 
+    // Last, so the query reads as the config's filter with the caller's
+    // narrowing applied to it.
+    match ? translate([match], TRUE) : TRUE);
+    return {
+        approximated,
+        dropped,
+        findings: findShadowedRules(enabledSites, [...disabledScopes, ...disabledSites, ...blacklist], budget),
+        predicate,
+        reduced,
+        warnings,
+    };
+}
+/**
+ * A boolean column that may be null. `not column` would drop the null rows
+ * along with the true ones, which is not what excluding a flag means.
+ */
+function isSet(name) {
+    return leaf(call("coalesce", column(name), literal(false)), true);
+}

package/dist/services/query-builder/queries/page-source.d.ts

@@ -0,0 +1,30 @@
+import { RuleSubjectExpressions } from "../rules/index.js";
+import { QueryInput } from "./query-model.js";
+/** The relation every query reads from. */
+export declare const PAGE_IMPRESSIONS = "live.rum.pi";
+/** The name of the common table expression the queries select from. */
+export declare const PAGE_SOURCE = "pages";
+export interface PageSource {
+    /** The `pages as (…)` common table expression, without the `with`. */
+    readonly cte: string;
+    /** The expressions rule conditions are matched against. */
+    readonly subjects: RuleSubjectExpressions;
+}
+export interface PageSourceOptions {
+    /**
+     * Columns of the relation to carry through, beyond `url`. Each query asks
+     * for what it reads: `createdat` is only needed where example urls are
+     * picked, `responsecause` only where 404s are filtered out.
+     */
+    readonly columns?: readonly string[];
+}
+/**
+ * The rows a query works on: the app's page impressions in the requested
+ * window, with everything a rule matches against projected once.
+ *
+ * Deriving host and path per condition would repeat the same
+ * `url_extract_path(url)` a dozen times in a single `where` clause. Naming
+ * them here keeps the query readable — which matters, because these queries
+ * are read and adjusted by hand in the Athena console.
+ */
+export declare function buildPageSource(input: QueryInput, options?: PageSourceOptions): PageSource;