@speedkit/cli 4.26.0 → 4.27.0

package/dist/services/query-builder/rules/rule-relevance.js

@@ -0,0 +1,69 @@
+import { testCondition } from "@speedkit/rules";
+import { DOCUMENT_CONTENT_TYPES } from "./rule-model.js";
+/**
+ * Rules the query cannot possibly be affected by, removed.
+ *
+ * This is the first half of ruling the rule sets against each other: not rule
+ * against rule yet, but every rule against the frame the query already sets —
+ * documents, on this app's origins. A `contentType: ['image']` blacklist entry
+ * or a rule for a third-party host says nothing about a page impression, and
+ * keeping it only narrows the result for no reason.
+ *
+ * Nothing is dropped silently: every decision comes back in `dropped` or
+ * `approximated` so it can be reported.
+ */
+export function keepRelevantRules(rules, context = {}) {
+    const contentTypes = context.contentTypes ?? DOCUMENT_CONTENT_TYPES;
+    const hosts = context.hosts ?? [];
+    const approximated = [];
+    const dropped = [];
+    const kept = [];
+    for (const rule of rules) {
+        const appliesTo = rule.contentTypes;
+        if (appliesTo && !appliesTo.some((type) => contentTypes.includes(type))) {
+            dropped.push({
+                reason: `applies to ${appliesTo.join(", ")} only, not to documents`,
+                source: rule.source,
+            });
+            continue;
+        }
+        if (rule.conditions.length === 0 && rule.criteriaOutsideTheUrl.length > 0) {
+            dropped.push({
+                reason: `matches on ${rule.criteriaOutsideTheUrl.join(", ")} only, which a page impression does not carry`,
+                source: rule.source,
+            });
+            continue;
+        }
+        if (hosts.length > 0 && !matchesAnyHost(rule, hosts)) {
+            dropped.push({
+                reason: `its host condition matches none of the queried origins (${hosts.join(", ")})`,
+                source: rule.source,
+            });
+            continue;
+        }
+        if (rule.criteriaOutsideTheUrl.length > 0) {
+            approximated.push({
+                reason: `also requires ${rule.criteriaOutsideTheUrl.join(", ")}, which a page impression does not carry — the filter is wider than the rule`,
+                source: rule.source,
+            });
+        }
+        kept.push(rule);
+    }
+    return { approximated, dropped, rules: kept };
+}
+/**
+ * True unless the rule has a host condition that provably matches none of the
+ * given hosts. A rule without a host condition always passes.
+ *
+ * The condition is evaluated with `testCondition` from `@speedkit/rules` —
+ * the very function the runtime uses — so this decision cannot drift from the
+ * browser's.
+ */
+function matchesAnyHost(rule, hosts) {
+    const condition = rule.conditions.find(({ subject }) => subject === "host");
+    if (!condition) {
+        return true;
+    }
+    const patterns = condition.patterns.map((pattern) => pattern.value);
+    return hosts.some((host) => testCondition(host, patterns, rule.ruleSetVersion));
+}

package/dist/services/query-builder/rules/rule-to-sql.d.ts

@@ -0,0 +1,51 @@
+import { Predicate, SqlExpression } from "../sql/index.js";
+import { NormalizedRule } from "./rule-model.js";
+/**
+ * The expressions a rule condition is matched against. The query decides how
+ * it provides them — inline over the `url` column, or as columns of a CTE that
+ * computes them once.
+ */
+export interface RuleSubjectExpressions {
+    readonly host: SqlExpression;
+    /** The path without the query string — what version 2 matches. */
+    readonly path: SqlExpression;
+    /** The path with the query string appended — what version 1 matches. */
+    readonly pathWithSearch: SqlExpression;
+    readonly url: SqlExpression;
+}
+export interface RuleTranslation {
+    readonly predicate: Predicate;
+    /** Constructs whose meaning may differ in Athena. See `toAthenaRegex`. */
+    readonly warnings: string[];
+}
+export interface TranslateRulesOptions {
+    /**
+     * What an empty rule list means. `enabledSites: []` accelerates every page,
+     * `blacklist: []` excludes nothing — both are `TRUE` for the set's own
+     * question, but the caller decides how the result is combined.
+     */
+    readonly whenEmpty?: Predicate;
+}
+/**
+ * Derives the subject expressions from a URL expression, the way
+ * `@speedkit/rules` derives them from a request in the browser.
+ *
+ * Three of those derivations are easy to get wrong:
+ *
+ * - A `url` condition is matched against the URL *without its scheme and
+ *   fragment* (`stripForRules`), so `www.shop.de/p/1`, not
+ *   `https://www.shop.de/p/1#reviews`.
+ * - A version 1 `pathname` condition is matched against `pathname + search`,
+ *   so a pattern anchored with `$` sees the query string too.
+ * - `new URL('https://shop.de').pathname` is `/`, while `url_extract_path`
+ *   returns nothing for the same URL.
+ */
+export declare function urlSubjects(url: SqlExpression): RuleSubjectExpressions;
+/**
+ * Translates a list of rules into the predicate that holds when any of them
+ * matches — rules are OR'd, the conditions of a rule are AND'd, and the
+ * entries of a condition are OR'd again.
+ */
+export declare function translateRules(rules: readonly NormalizedRule[], subjects: RuleSubjectExpressions, options?: TranslateRulesOptions): RuleTranslation;
+/** Translates one rule: every one of its conditions has to match. */
+export declare function translateRule(rule: NormalizedRule, subjects: RuleSubjectExpressions): RuleTranslation;

package/dist/services/query-builder/rules/rule-to-sql.js

@@ -0,0 +1,75 @@
+import { and, call, concat, equalsIgnoreCase, FALSE, literal, or, regexpLike, startsWith, toAthenaRegex, TRUE, } from "../sql/index.js";
+import { matchesExactly, resolvedSubject, } from "./rule-model.js";
+/**
+ * Derives the subject expressions from a URL expression, the way
+ * `@speedkit/rules` derives them from a request in the browser.
+ *
+ * Three of those derivations are easy to get wrong:
+ *
+ * - A `url` condition is matched against the URL *without its scheme and
+ *   fragment* (`stripForRules`), so `www.shop.de/p/1`, not
+ *   `https://www.shop.de/p/1#reviews`.
+ * - A version 1 `pathname` condition is matched against `pathname + search`,
+ *   so a pattern anchored with `$` sees the query string too.
+ * - `new URL('https://shop.de').pathname` is `/`, while `url_extract_path`
+ *   returns nothing for the same URL.
+ */
+export function urlSubjects(url) {
+    const query = call("url_extract_query", url);
+    const path = call("coalesce", call("nullif", call("url_extract_path", url), literal("")), literal("/"));
+    return {
+        // `url_extract_host` drops a port the runtime would keep, which only
+        // matters for a host condition naming one.
+        host: call("url_extract_host", url),
+        path,
+        pathWithSearch: concat(path, call("coalesce", call("nullif", concat(literal("?"), query), literal("?")), literal(""))),
+        url: call("regexp_replace", call("regexp_replace", url, literal("#.*"), literal("")), literal(String.raw `^(\w+:)?//`), literal("")),
+    };
+}
+/**
+ * Translates a list of rules into the predicate that holds when any of them
+ * matches — rules are OR'd, the conditions of a rule are AND'd, and the
+ * entries of a condition are OR'd again.
+ */
+export function translateRules(rules, subjects, options = {}) {
+    if (rules.length === 0) {
+        return { predicate: options.whenEmpty ?? TRUE, warnings: [] };
+    }
+    const translations = rules.map((rule) => translateRule(rule, subjects));
+    return {
+        predicate: or(...translations.map(({ predicate }) => predicate)),
+        warnings: translations.flatMap(({ warnings }) => warnings),
+    };
+}
+/** Translates one rule: every one of its conditions has to match. */
+export function translateRule(rule, subjects) {
+    // A rule with no condition, or with a condition nothing satisfies.
+    if (rule.matchesNothing) {
+        return { predicate: FALSE, warnings: [] };
+    }
+    const warnings = [];
+    const predicates = rule.conditions.map((condition) => translateCondition(condition, rule, subjects, warnings));
+    // Conditions the query cannot express were taken out by the relevance pass,
+    // which is why a rule can arrive here with none left: it then matches every
+    // row of a query that is already restricted to documents.
+    return { predicate: and(...predicates), warnings };
+}
+function translateCondition(condition, rule, subjects, warnings) {
+    const subject = subjectExpression(condition.subject, rule, subjects);
+    return or(...condition.patterns.map((pattern) => translatePattern(pattern, subject, rule, warnings)));
+}
+function translatePattern(pattern, subject, rule, warnings) {
+    if (pattern.kind === "regexp") {
+        const { pattern: athenaPattern, warnings: regexWarnings } = toAthenaRegex(pattern.value);
+        warnings.push(...regexWarnings.map((warning) => `${rule.source}: ${warning}`));
+        return regexpLike(subject, athenaPattern);
+    }
+    // A string condition is case-insensitive on both sides, and it is a prefix
+    // under version 1 while version 2 compares it exactly.
+    return matchesExactly(rule.ruleSetVersion)
+        ? equalsIgnoreCase(subject, pattern.value)
+        : startsWith(subject, pattern.value);
+}
+function subjectExpression(subject, rule, subjects) {
+    return subjects[resolvedSubject(subject, rule.ruleSetVersion)];
+}

package/dist/services/query-builder/rules/spec/pattern-language.spec.d.ts

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

package/dist/services/query-builder/rules/spec/pattern-language.spec.js

@@ -0,0 +1,90 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { conditionLanguage, isInside, languagesDisjoint, outsideOf, } from "../pattern-language.js";
+function condition(...patterns) {
+    return {
+        patterns: patterns.map((value) => typeof value === "string"
+            ? { kind: "string", value }
+            : { kind: "regexp", value }),
+        subject: "pathname",
+    };
+}
+function languageOf(pattern, bound, version = 2) {
+    return conditionLanguage(condition(pattern), version, bound);
+}
+/** Whether the first pattern's matches all fall inside the second's. */
+function inside(narrower, wider, version = 2) {
+    const atLeast = languageOf(narrower, "atLeast", version);
+    const atMost = languageOf(wider, "atMost", version);
+    if (!atLeast || !atMost) {
+        return undefined;
+    }
+    const outside = outsideOf(atMost);
+    return outside && isInside(atLeast, outside);
+}
+function disjoint(left, right, version = 2) {
+    const first = languageOf(left, "atLeast", version);
+    const second = languageOf(right, "atLeast", version);
+    return first && second ? languagesDisjoint(first, second) : undefined;
+}
+describe("pattern languages", () => {
+    it("should see an anchored pattern inside a shorter one", () => {
+        expect(inside(/^\/p\/shoes\//i, /^\/p\//i)).to.equal(true);
+        expect(inside(/^\/p\//i, /^\/p\/shoes\//i)).to.equal(false);
+    });
+    it("should see disjoint prefixes as disjoint", () => {
+        expect(disjoint(/^\/p\//i, /^\/checkout/i)).to.equal(true);
+    });
+    it("should not call overlapping patterns disjoint", () => {
+        expect(disjoint(/^\/p\//i, /shoes/i)).to.equal(false);
+    });
+    it("should read an unanchored pattern as matching anywhere", () => {
+        expect(inside(/^\/a\/b/i, /b/i)).to.equal(true);
+        expect(disjoint(/^\/a\/b/i, /b/i)).to.equal(false);
+    });
+    it("should respect the case of a pattern without the i flag", () => {
+        expect(disjoint(/^\/Shop/, /^\/shop/)).to.equal(true);
+        expect(disjoint(/^\/Shop/i, /^\/shop/)).to.equal(false);
+    });
+    it("should read a string as a prefix under version 1 and exactly under 2", () => {
+        expect(inside("/shop/nike", "/shop", 1)).to.equal(true);
+        expect(inside("/shop/nike", "/shop", 2)).to.equal(false);
+    });
+    it("should ignore the case of a string condition", () => {
+        expect(disjoint("/SHOP", "/shop", 2)).to.equal(false);
+    });
+    it("should union the entries of a condition", () => {
+        const language = conditionLanguage(condition(/^\/a/, /^\/b/), 2, "atLeast");
+        const outside = language && outsideOf(language);
+        const a = languageOf(/^\/a\/1/, "atLeast");
+        expect(outside && a && isInside(a, outside)).to.equal(true);
+    });
+});
+describe("pattern languages with an assertion", () => {
+    // `(\/|$)` and `\b` have no automaton, so each bound approximates — and the
+    // two bounds have to fall on opposite sides of the truth.
+    it("should read an assertion as widely as possible for atLeast", () => {
+        // /^\/shop(\/|$)/ widened means "starts with /shop", which covers /shopx.
+        expect(disjoint(/^\/shop(\/|$)/, /^\/shopx/)).to.equal(false);
+    });
+    it("should read an assertion as narrowly as possible for atMost", () => {
+        // Narrowed, the same pattern covers only /shop/… — not /shop itself.
+        expect(inside(/^\/shop$/, /^\/shop(\/|$)/)).to.equal(false);
+    });
+    it("should still place a widened pattern inside a wider one", () => {
+        expect(inside(/\bshop\b/i, /shop/i)).to.equal(true);
+    });
+});
+describe("patterns without any automaton", () => {
+    // A back reference to a single character is expressible as a union and
+    // `refa` resolves it; one to a group of any length is not.
+    it("should resolve a back reference to a single character", () => {
+        expect(languageOf(/(\w)\1/, "atLeast")).to.not.equal(undefined);
+    });
+    it("should give up on a back reference it cannot resolve", () => {
+        expect(languageOf(/(\w+)\1/, "atLeast")).to.equal(undefined);
+    });
+    it("should give up on the whole condition when one entry has none", () => {
+        expect(conditionLanguage(condition(/^\/a/, /(\w+)\1/), 2, "atLeast")).to.equal(undefined);
+    });
+});

package/dist/services/query-builder/rules/spec/rule-parser.spec.d.ts

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

package/dist/services/query-builder/rules/spec/rule-parser.spec.js

@@ -0,0 +1,150 @@
+import * as vm from "node:vm";
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { parseCondition, parseRuleSets, parseRuleSetVersion, parseStripQueryParams, } from "../rule-parser.js";
+describe("parseRuleSetVersion", () => {
+    it("should default to version 1", () => {
+        expect(parseRuleSetVersion({})).to.equal(1);
+    });
+    it("should read the declared version", () => {
+        expect(parseRuleSetVersion({ ruleSetConfig: { version: 2 } })).to.equal(2);
+    });
+    it("should read a version given as a string", () => {
+        expect(parseRuleSetVersion({ ruleSetConfig: { version: "2" } })).to.equal(2);
+    });
+    it("should fall back for an unusable version", () => {
+        expect(parseRuleSetVersion({ ruleSetConfig: { version: "x" } })).to.equal(1);
+    });
+});
+describe("parseCondition", () => {
+    it("should wrap a single string", () => {
+        expect(parseCondition("/shop")).to.deep.equal([
+            { kind: "string", value: "/shop" },
+        ]);
+    });
+    it("should wrap a single regular expression", () => {
+        const pattern = /^\/p\//i;
+        expect(parseCondition(pattern)).to.deep.equal([
+            { kind: "regexp", value: pattern },
+        ]);
+    });
+    it("should keep the order of a mixed array", () => {
+        expect(parseCondition(["/a", /b/]).map(({ kind }) => kind)).to.deep.equal([
+            "string",
+            "regexp",
+        ]);
+    });
+    it("should return nothing for a missing condition", () => {
+        expect(parseCondition(undefined)).to.deep.equal([]);
+    });
+    it("should recognise a regular expression from another realm", () => {
+        // The config is evaluated with `vm.runInNewContext`, so its regular
+        // expressions are not `instanceof RegExp` here. Reading them as strings
+        // would drop every pattern of every rule.
+        const foreign = vm.runInNewContext("/^\\/p\\//i");
+        expect(foreign instanceof RegExp).to.equal(false);
+        const [pattern] = parseCondition(foreign);
+        expect(pattern.kind).to.equal("regexp");
+        expect(pattern.value).to.be.instanceOf(RegExp);
+        expect(String(pattern.value)).to.equal("/^\\/p\\//i");
+    });
+});
+describe("parseRuleSets", () => {
+    it("should read every whitelist rule, not just the first", () => {
+        const { whitelist } = parseRuleSets({
+            whitelist: [{ host: ["www.shop.de"] }, { host: ["m.shop.de"] }],
+        });
+        expect(whitelist).to.have.lengthOf(2);
+        expect(whitelist[1].source).to.equal("whitelist[1]");
+    });
+    it("should keep the conditions of a rule together", () => {
+        const { enabledSites } = parseRuleSets({
+            enabledSites: [{ host: ["www.shop.de"], pathname: [/^\/p\//i] }],
+        });
+        expect(enabledSites[0].conditions.map(({ subject }) => subject)).to.deep.eq(["host", "pathname"]);
+    });
+    it("should normalize the content types", () => {
+        const { blacklist } = parseRuleSets({
+            blacklist: [{ contentType: "Image" }],
+        });
+        expect(blacklist[0].contentTypes).to.deep.equal(["image"]);
+    });
+    it("should leave the content types undefined when there are none", () => {
+        const { blacklist } = parseRuleSets({ blacklist: [{ pathname: "/a" }] });
+        expect(blacklist[0].contentTypes).to.equal(undefined);
+    });
+    it("should record criteria that are not part of the url", () => {
+        const { disabledSites } = parseRuleSets({
+            disabledSites: [{ cookie: /loggedIn/, mobile: true, pathname: "/a" }],
+        });
+        expect(disabledSites[0].criteriaOutsideTheUrl).to.deep.equal([
+            "cookie",
+            "mobile",
+        ]);
+    });
+    it("should apply the config version to every rule", () => {
+        const { enabledSites } = parseRuleSets({
+            enabledSites: [{ pathname: "/a" }],
+            ruleSetConfig: { version: 2 },
+        });
+        expect(enabledSites[0].ruleSetVersion).to.equal(2);
+    });
+    it("should let a rule override the version", () => {
+        const { enabledSites } = parseRuleSets({
+            enabledSites: [{ pathname: "/a", ruleSetVersion: 1 }],
+            ruleSetConfig: { version: 2 },
+        });
+        expect(enabledSites[0].ruleSetVersion).to.equal(1);
+    });
+    it("should survive a config without any rule set", () => {
+        const parsed = parseRuleSets({});
+        expect(parsed.whitelist).to.deep.equal([]);
+        expect(parsed.enabledSites).to.deep.equal([]);
+        expect(parsed.stripQueryParams).to.deep.equal([]);
+    });
+    it("should ignore a rule set that is not an array", () => {
+        expect(parseRuleSets({ blacklist: "everything" }).blacklist).to.deep.equal([]);
+    });
+    it("should keep a rule without conditions", () => {
+        const { whitelist } = parseRuleSets({ whitelist: [{}] });
+        expect(whitelist).to.have.lengthOf(1);
+        expect(whitelist[0].conditions).to.deep.equal([]);
+        expect(whitelist[0].matchesNothing).to.equal(true);
+    });
+    it("should mark a rule with an empty condition as matching nothing", () => {
+        const { blacklist } = parseRuleSets({ blacklist: [{ host: [] }] });
+        expect(blacklist[0].matchesNothing).to.equal(true);
+    });
+    it("should mark an empty content type as matching nothing", () => {
+        const { blacklist } = parseRuleSets({ blacklist: [{ contentType: [] }] });
+        expect(blacklist[0].matchesNothing).to.equal(true);
+    });
+    it("should not mark a rule with a usable condition", () => {
+        const { blacklist } = parseRuleSets({ blacklist: [{ host: ["a.de"] }] });
+        expect(blacklist[0].matchesNothing).to.equal(false);
+    });
+});
+describe("parseStripQueryParams", () => {
+    it("should read a bare list of parameters", () => {
+        const rules = parseStripQueryParams(["gclid", /^utm[_-]/], 2);
+        expect(rules).to.have.lengthOf(1);
+        expect(rules[0].params).to.have.lengthOf(2);
+        expect(rules[0].enabledSites).to.equal(undefined);
+    });
+    it("should read a single parameter", () => {
+        expect(parseStripQueryParams("gclid", 2)[0].params).to.deep.equal([
+            { kind: "string", value: "gclid" },
+        ]);
+    });
+    it("should keep the pages a rule is scoped to", () => {
+        const rules = parseStripQueryParams([{ enabledSites: [{ pathname: [/^\/p\//i] }], params: ["size"] }], 2);
+        expect(rules[0].enabledSites).to.have.lengthOf(1);
+        expect(rules[0].enabledSites[0].source).to.equal("stripQueryParams[0].enabledSites[0]");
+    });
+    it("should skip a rule without parameters", () => {
+        expect(parseStripQueryParams([{ enabledSites: [] }], 2)).to.deep.equal([]);
+    });
+    it("should return nothing when the property is missing", () => {
+        expect(parseStripQueryParams(undefined, 2)).to.deep.equal([]);
+    });
+});

package/dist/services/query-builder/rules/spec/rule-reducer.spec.d.ts

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

package/dist/services/query-builder/rules/spec/rule-reducer.spec.js

@@ -0,0 +1,169 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { parseRuleSets } from "../rule-parser.js";
+import { absorbRules, dropUnreachableRules, findShadowedRules, reductionBudget, } from "../rule-reducer.js";
+function rulesOf(config, version = 2) {
+    return parseRuleSets({ ruleSetConfig: { version }, ...config });
+}
+function blacklist(rules, version = 2) {
+    return rulesOf({ blacklist: rules }, version).blacklist;
+}
+function enabled(rules, version = 2) {
+    return rulesOf({ enabledSites: rules }, version).enabledSites;
+}
+/** The entries left on the first rule's first condition. */
+function patternsOf(rules) {
+    return (rules[0]?.conditions[0]?.patterns ?? []).map(({ value }) => String(value));
+}
+describe("absorbRules", () => {
+    it("should drop a rule a sibling covers", () => {
+        const { notes, rules } = absorbRules(blacklist([{ pathname: [/^\/p\/shoes\//i] }, { pathname: [/^\/p\//i] }]));
+        expect(rules).to.have.lengthOf(1);
+        expect(rules[0].source).to.equal("blacklist[1]");
+        expect(notes[0].reason).to.contain("already covered by blacklist[1]");
+    });
+    it("should keep the first of two equivalent rules", () => {
+        const { rules } = absorbRules(blacklist([{ pathname: [/^\/p\//i] }, { pathname: [/^\/p\//i] }]));
+        expect(rules).to.have.lengthOf(1);
+        expect(rules[0].source).to.equal("blacklist[0]");
+    });
+    it("should not compare rules about different parts of the url", () => {
+        const { rules } = absorbRules(blacklist([{ host: ["www.shop.de"] }, { pathname: [/^\/p\//i] }]));
+        expect(rules).to.have.lengthOf(2);
+    });
+    it("should keep a rule that is wider on a subject the other constrains", () => {
+        const { rules } = absorbRules(blacklist([
+            { host: ["www.shop.de"], pathname: [/^\/p\//i] },
+            { pathname: [/^\/p\//i] },
+        ]));
+        expect(rules).to.have.lengthOf(1);
+        expect(rules[0].source).to.equal("blacklist[1]");
+    });
+    it("should drop a condition entry a sibling entry covers", () => {
+        const { rules } = absorbRules(blacklist([{ pathname: [/^\/p\/shoes\//i, /^\/p\//i] }]));
+        expect(patternsOf(rules)).to.deep.equal(["/^\\/p\\//i"]);
+    });
+    it("should keep entries that only overlap", () => {
+        const { rules } = absorbRules(blacklist([{ pathname: [/^\/p\//i, /shoes/i] }]));
+        expect(patternsOf(rules)).to.have.lengthOf(2);
+    });
+    it("should absorb an entry with an assertion into a wider one", () => {
+        // `\b` has no automaton, but read as widely as possible the entry means
+        // "contains p" — which /p/i does cover, so the absorption holds.
+        const { rules } = absorbRules(blacklist([{ pathname: [/\bp\b/i, /p/i] }]));
+        expect(patternsOf(rules)).to.deep.equal(["/p/i"]);
+    });
+    it("should not let an entry with an assertion absorb a wider one", () => {
+        // Read as narrowly as possible the entry means nothing at all, so it
+        // cannot stand in for /p/i.
+        const { rules } = absorbRules(blacklist([{ pathname: [/p/i, /\bp\b/i] }]));
+        expect(patternsOf(rules)).to.deep.equal(["/p/i"]);
+    });
+});
+describe("dropUnreachableRules", () => {
+    const reachable = [enabled([{ pathname: [/^\/$/, /^\/p\//i] }])];
+    it("should drop an entry no enabled page can match", () => {
+        const { notes, rules } = dropUnreachableRules(blacklist([{ pathname: [/^\/checkout/i, /^\/p\//i] }]), reachable);
+        expect(patternsOf(rules)).to.deep.equal(["/^\\/p\\//i"]);
+        expect(notes[0].reason).to.contain("matches no page enabledSites");
+    });
+    it("should drop the rule once no entry of a condition is left", () => {
+        const { notes, rules } = dropUnreachableRules(blacklist([{ pathname: [/^\/checkout/i, /^\/account/i] }]), reachable);
+        expect(rules).to.deep.equal([]);
+        expect(notes[0].source).to.equal("blacklist[0]");
+    });
+    it("should keep an unanchored entry that can hit an enabled page", () => {
+        const { rules } = dropUnreachableRules(blacklist([{ pathname: [/\.pdf/i] }]), reachable);
+        expect(patternsOf(rules)).to.have.lengthOf(1);
+    });
+    it("should keep an entry when the enabled rules leave the subject free", () => {
+        const { rules } = dropUnreachableRules(blacklist([{ host: ["cdn.shop.de"] }]), reachable);
+        expect(rules).to.have.lengthOf(1);
+    });
+    it("should reduce nothing without an including set", () => {
+        const { rules } = dropUnreachableRules(blacklist([{ pathname: [/^\/checkout/i] }]), []);
+        expect(rules).to.have.lengthOf(1);
+    });
+    it("should not read an assertion as an exclusion", () => {
+        // `(\/|$)` has no automaton. Reading it as "never matches" would make
+        // /shop/x look unreachable, and the guard would vanish from the query.
+        const { rules } = dropUnreachableRules(blacklist([{ pathname: [/^\/shop\/x/i] }]), [enabled([{ pathname: [/^\/shop(\/|$)/i] }])]);
+        expect(rules).to.have.lengthOf(1);
+    });
+});
+describe("the reduction budget", () => {
+    it("should spend the same comparisons on the same input, twice", () => {
+        // The budget counts work, not milliseconds: a busier machine must not
+        // reduce a config differently than a quiet one.
+        const rules = () => blacklist([{ pathname: [/^\/p\/shoes\//i] }, { pathname: [/^\/p\//i] }]);
+        const budget = reductionBudget(3);
+        const first = absorbRules(rules(), budget);
+        const second = absorbRules(rules(), reductionBudget(3));
+        expect(first.rules.map(({ source }) => source)).to.deep.equal(second.rules.map(({ source }) => source));
+        expect(first.notes).to.deep.equal(second.notes);
+    });
+    const spent = () => reductionBudget(0);
+    it("should keep every rule once the budget is gone", () => {
+        const { notes, rules } = absorbRules(blacklist([{ pathname: [/^\/p\/shoes\//i] }, { pathname: [/^\/p\//i] }]), spent());
+        expect(rules).to.have.lengthOf(2);
+        expect(notes[0].reason).to.contain("stopped after");
+        expect(notes[0].reason).to.contain("comparisons");
+    });
+    it("should keep every condition entry once the budget is gone", () => {
+        const { rules } = dropUnreachableRules(blacklist([{ pathname: [/^\/checkout/i] }]), [enabled([{ pathname: [/^\/p\//i] }])], spent());
+        expect(rules).to.have.lengthOf(1);
+        expect(patternsOf(rules)).to.have.lengthOf(1);
+    });
+    it("should report no finding once the budget is gone", () => {
+        expect(findShadowedRules(enabled([{ pathname: [/^\/p\/shoes\//i] }]), blacklist([{ pathname: [/^\/p\//i] }]), spent())).to.deep.equal([]);
+    });
+    it("should reduce normally with comparisons left", () => {
+        const { rules } = absorbRules(blacklist([{ pathname: [/^\/p\/shoes\//i] }, { pathname: [/^\/p\//i] }]), reductionBudget(100));
+        expect(rules).to.have.lengthOf(1);
+    });
+});
+describe("findShadowedRules", () => {
+    it("should report an enabled rule an excluding rule covers", () => {
+        const notes = findShadowedRules(enabled([{ pathname: [/^\/p\/shoes\//i] }]), blacklist([{ pathname: [/^\/p\//i] }]));
+        expect(notes).to.have.lengthOf(1);
+        expect(notes[0].source).to.equal("enabledSites[0]");
+        expect(notes[0].reason).to.contain("blacklist[0]");
+    });
+    it("should say nothing about a rule that is only narrowed", () => {
+        const notes = findShadowedRules(enabled([{ pathname: [/^\/p\//i] }]), blacklist([{ pathname: [/^\/p\/shoes\//i] }]));
+        expect(notes).to.deep.equal([]);
+    });
+});
+describe("disabledScopes as rules", () => {
+    it("should read a scope as a case-sensitive path prefix", () => {
+        const { disabledScopes } = rulesOf({ disabledScopes: ["/checkout"] });
+        expect(disabledScopes).to.have.lengthOf(1);
+        expect(patternsOf(disabledScopes)).to.deep.equal(["/^\\/checkout/"]);
+        expect(disabledScopes[0].source).to.equal("disabledScopes[0]");
+    });
+    it("should escape a scope that reads as a pattern", () => {
+        const { disabledScopes } = rulesOf({ disabledScopes: ["/a.b"] });
+        expect(patternsOf(disabledScopes)).to.deep.equal([String.raw `/^\/a\.b/`]);
+    });
+    it("should ignore entries that are not a prefix", () => {
+        const { disabledScopes } = rulesOf({
+            disabledScopes: ["/cart", "", null, 7],
+        });
+        expect(disabledScopes).to.have.lengthOf(1);
+    });
+    it("should return nothing when the property is missing", () => {
+        expect(rulesOf({}).disabledScopes).to.deep.equal([]);
+    });
+    it("should cover the sibling paths a service worker scope covers", () => {
+        // A scope is a plain prefix, so `/checkout` claims `/checkoutTunnel` too
+        // and a page type living there can never be accelerated.
+        const notes = findShadowedRules(enabled([{ pathname: [/^\/checkoutTunnel/] }]), rulesOf({ disabledScopes: ["/checkout"] }).disabledScopes);
+        expect(notes).to.have.lengthOf(1);
+        expect(notes[0].reason).to.contain("disabledScopes[0]");
+    });
+    it("should not claim a path that only differs in case", () => {
+        // Scope matching is case-sensitive, unlike a string condition.
+        const notes = findShadowedRules(enabled([{ pathname: [/^\/Checkout/] }]), rulesOf({ disabledScopes: ["/checkout"] }).disabledScopes);
+        expect(notes).to.deep.equal([]);
+    });
+});

package/dist/services/query-builder/rules/spec/rule-relevance.spec.d.ts

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