@speedkit/cli 4.26.0 → 4.27.1

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

@@ -0,0 +1,159 @@
+import { DFA, isDisjointWith, JS, NFA } from "refa";
+import { escapeRegexLiteral } from "../sql/index.js";
+import { matchesExactly, } from "./rule-model.js";
+/**
+ * The language of one condition — the union of its entries, since one matching
+ * entry satisfies the condition.
+ *
+ * Returns `undefined` when an entry has no automaton at all, and the caller
+ * then leaves the rule out of every reduction.
+ */
+export function conditionLanguage(condition, ruleSetVersion, bound) {
+    // The reducer asks the same condition the same question many times over,
+    // once per rule or entry it is compared with, and building an automaton is
+    // the expensive part. Callers only ever read the result.
+    const cacheKey = `${ruleSetVersion}:${bound}`;
+    const cached = cache.get(condition);
+    if (cached?.has(cacheKey)) {
+        return cached.get(cacheKey);
+    }
+    const language = buildConditionLanguage(condition, ruleSetVersion, bound);
+    if (cached) {
+        cached.set(cacheKey, language);
+    }
+    else {
+        cache.set(condition, new Map([[cacheKey, language]]));
+    }
+    return language;
+}
+/** Automata already built, per condition. Never handed out for mutation. */
+const cache = new WeakMap();
+function buildConditionLanguage(condition, ruleSetVersion, bound) {
+    let language;
+    for (const pattern of condition.patterns) {
+        const entry = patternLanguage(pattern, ruleSetVersion, bound);
+        if (!entry) {
+            return undefined;
+        }
+        if (!language) {
+            language = entry;
+            continue;
+        }
+        // Automata built for different character ranges cannot be combined; that
+        // happens when one pattern is unicode-aware and another is not.
+        if (language.maxCharacter !== entry.maxCharacter) {
+            return undefined;
+        }
+        const united = attempt(() => {
+            language?.union(entry);
+            return true;
+        });
+        if (!united) {
+            return undefined;
+        }
+    }
+    // The union of many patterns is where determinisation gets expensive, and
+    // its size is what decides that cost — so the same cap applies to it.
+    return language && language.countNodes() > MAX_NODES ? undefined : language;
+}
+/** The complement of an `atMost` language. */
+export function outsideOf(language) {
+    return attempt(() => {
+        const complement = DFA.fromFA(language);
+        complement.complement();
+        return complement;
+    });
+}
+/**
+ * True when the language stays inside the one `outside` was built from —
+ * `language ⊆ superset ⟺ language ∩ ¬superset = ∅`.
+ *
+ * @param language - has to be an `atLeast` language.
+ * @param outside - has to come from {@link outsideOf} on an `atMost` language.
+ */
+export function isInside(language, outside) {
+    if (language.maxCharacter !== outside.maxCharacter) {
+        return undefined;
+    }
+    return attempt(() => isDisjointWith(language, outside));
+}
+/**
+ * True when no subject is accepted by both languages. Both have to be
+ * `atLeast` languages.
+ */
+export function languagesDisjoint(left, right) {
+    if (left.maxCharacter !== right.maxCharacter) {
+        return undefined;
+    }
+    return attempt(() => isDisjointWith(left, right));
+}
+/**
+ * The language of a single condition entry.
+ *
+ * The automaton describes *whole* subjects, so where the pattern is not
+ * anchored it is padded: an unanchored JavaScript pattern matches anywhere in
+ * the subject, and a version 1 string is a prefix of it.
+ */
+function patternLanguage(pattern, ruleSetVersion, bound) {
+    if (pattern.kind === "string") {
+        const value = escapeRegexLiteral(pattern.value);
+        const source = matchesExactly(ruleSetVersion) ? value : `${value}${ANY}`;
+        // A string condition lower-cases both sides, which the `i` flag mirrors.
+        return build(source, "i", bound);
+    }
+    const { flags, source } = pattern.value;
+    const anchoredStart = source.startsWith("^");
+    const anchoredEnd = /(?<!\\)\$$/.test(source);
+    const inner = source.slice(anchoredStart ? 1 : 0, anchoredEnd ? -1 : undefined);
+    return build(`${anchoredStart ? "" : ANY}(?:${inner})${anchoredEnd ? "" : ANY}`, 
+    // A global or sticky flag says nothing about the language.
+    flags.replaceAll(/[gy]/g, ""), bound);
+}
+/** Matches any subject, used to pad an unanchored pattern. */
+const ANY = String.raw `[\s\S]*`;
+/**
+ * The most states an automaton may have to take part in a reduction.
+ *
+ * Comparing two automata costs far more than building them, and past a certain
+ * size that cost falls off a cliff. Measured over the configs in the
+ * onboarding repo: at 200 the slowest customer builds its query in 1.0s, at
+ * 250 the same customer takes 9.7s, and none of them reduces any better for
+ * it. The largest condition that ever carried a reduction has 189 states,
+ * which is what this leaves room for.
+ *
+ * Refusing an automaton only costs a reduction — the rule stays in the query,
+ * and the query stays correct — so the cap is safe to tighten and expensive to
+ * raise.
+ */
+const MAX_NODES = 200;
+function build(source, flags, bound) {
+    return attempt(() => {
+        const { expression, maxCharacter } = JS.Parser.fromLiteral({
+            flags,
+            source,
+        }).parse({
+            // An assertion left inside the pattern is widened or narrowed, whichever
+            // keeps the caller's answer sound.
+            assertions: bound === "atLeast" ? "ignore" : "disable",
+            backreferences: "throw",
+        });
+        const nfa = NFA.fromRegex(expression, { maxCharacter });
+        return nfa.countNodes() > MAX_NODES ? undefined : nfa;
+    });
+}
+/**
+ * Runs an automaton operation, or gives up on it.
+ *
+ * Every step can fail on a pattern that is legal but too much for an
+ * automaton — a back reference, or a determinisation that would need more
+ * states than `refa` allows. Failing means "undecidable", which costs a
+ * reduction and never a correct query.
+ */
+function attempt(operation) {
+    try {
+        return operation();
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,107 @@
+import { ConditionKey } from "@speedkit/rules";
+/**
+ * The rule shapes of a Speed Kit config, normalized into something the query
+ * builder can reason about.
+ *
+ * A `SpeedKitRule` in a config is loose: a condition may be a string, a
+ * regular expression or an array of both, a rule may carry criteria that have
+ * nothing to do with the URL, and the rule-set version decides what a string
+ * even means. Everything downstream — relevance, reduction, translation —
+ * works on the types here instead of on the raw config.
+ */
+/** The rule-set version a config runs under when it declares none. */
+export declare const DEFAULT_RULE_SET_VERSION = 1;
+/** Content types a page impression can have. */
+export declare const DOCUMENT_CONTENT_TYPES: readonly ["document", "navigate"];
+/** The condition keys naming a part of the URL a query can match on. */
+export declare const URL_CONDITION_KEYS: readonly [ConditionKey.Host, ConditionKey.Pathname, ConditionKey.Url];
+/**
+ * Criteria of a `SpeedKitRule` that a page impression does not carry, so they
+ * cannot be part of a query. A rule using one of these is either approximated
+ * (when it also has URL conditions) or reported as untranslatable.
+ *
+ * `hashparam` is among them: the runtime matches it against the fragment,
+ * which is not part of a URL the way the warehouse stores it.
+ */
+export declare const CRITERIA_OUTSIDE_THE_URL: ConditionKey[];
+/** The parts of a URL a rule can match on. */
+export type RuleSubject = "host" | "pathname" | "url";
+/** One entry of a rule condition. Entries of a condition are OR'd. */
+export type ConditionPattern = {
+    readonly kind: "regexp";
+    readonly value: RegExp;
+} | {
+    readonly kind: "string";
+    readonly value: string;
+};
+export interface RuleCondition {
+    /** OR'd — one matching entry satisfies the condition. */
+    readonly patterns: readonly ConditionPattern[];
+    readonly subject: RuleSubject;
+}
+export interface NormalizedRule {
+    /** AND'd — every condition of a rule has to match. */
+    readonly conditions: readonly RuleCondition[];
+    /**
+     * True when the rule can never match, whatever the URL.
+     *
+     * The runtime builds one condition per key it knows and requires all of
+     * them, so two shapes match nothing: a rule with no such key at all, and a
+     * rule whose condition is an empty list. The second one is easy to write by
+     * accident — `host: hasWebPSupport ? [] : [...]` is a real config — and
+     * reading it as "matches everything" turns a blacklist into `where false`.
+     */
+    readonly matchesNothing: boolean;
+    /** Undefined means the rule applies to every content type. */
+    readonly contentTypes?: readonly string[];
+    /** Criteria that were present but cannot be expressed over a URL. */
+    readonly criteriaOutsideTheUrl: readonly string[];
+    /** Version this rule is parsed under; a rule may override the config's. */
+    readonly ruleSetVersion: number;
+    /** Where the rule came from, e.g. `disabledSites[1]`. For reporting. */
+    readonly source: string;
+}
+export interface StripParameterRule {
+    /** Pages the stripping is limited to, if any. */
+    readonly enabledSites?: readonly NormalizedRule[];
+    /** OR'd parameter-name patterns. */
+    readonly params: readonly ConditionPattern[];
+    /** Resources the stripping is limited to, if any. */
+    readonly rules?: readonly NormalizedRule[];
+    /** Decides whether a parameter name matches exactly or as a prefix. */
+    readonly ruleSetVersion: number;
+    readonly source: string;
+}
+export interface ParsedRuleSets {
+    readonly blacklist: readonly NormalizedRule[];
+    /**
+     * `disabledScopes`, as rules. Not a rule set in the config — a list of path
+     * prefixes the service worker must never claim — but it decides which pages
+     * Speed Kit touches just like `disabledSites` does, so the query treats it
+     * the same way.
+     */
+    readonly disabledScopes: readonly NormalizedRule[];
+    readonly disabledSites: readonly NormalizedRule[];
+    readonly enabledSites: readonly NormalizedRule[];
+    readonly ruleSetVersion: number;
+    readonly stripQueryParams: readonly StripParameterRule[];
+    readonly whitelist: readonly NormalizedRule[];
+}
+/**
+ * The subject a condition is really matched against. A `pathname` condition
+ * reads the query string too unless the rule set is version 2, which makes it
+ * a different subject — and one a query must not compare against the other.
+ */
+export declare function resolvedSubject(subject: RuleSubject, ruleSetVersion: number): ResolvedSubject;
+/** The subjects a query provides, after the version has been resolved. */
+export type ResolvedSubject = "host" | "path" | "pathWithSearch" | "url";
+/**
+ * True when the version matches parameter names and string conditions
+ * exactly. Version 1 treats them as prefixes and also feeds the query string
+ * into `pathname` conditions.
+ *
+ * The comparison is exact, not `>= 2`: `testCondition` in `@speedkit/rules`
+ * checks the version with `=== 2`, so a config declaring anything else falls
+ * back to the version 1 behaviour.
+ */
+export declare function matchesExactly(ruleSetVersion: number): boolean;

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

@@ -0,0 +1,54 @@
+import { ConditionKey } from "@speedkit/rules";
+/**
+ * The rule shapes of a Speed Kit config, normalized into something the query
+ * builder can reason about.
+ *
+ * A `SpeedKitRule` in a config is loose: a condition may be a string, a
+ * regular expression or an array of both, a rule may carry criteria that have
+ * nothing to do with the URL, and the rule-set version decides what a string
+ * even means. Everything downstream — relevance, reduction, translation —
+ * works on the types here instead of on the raw config.
+ */
+/** The rule-set version a config runs under when it declares none. */
+export const DEFAULT_RULE_SET_VERSION = 1;
+/** Content types a page impression can have. */
+export const DOCUMENT_CONTENT_TYPES = ["document", "navigate"];
+/** The condition keys naming a part of the URL a query can match on. */
+export const URL_CONDITION_KEYS = [
+    ConditionKey.Host,
+    ConditionKey.Pathname,
+    ConditionKey.Url,
+];
+/**
+ * Criteria of a `SpeedKitRule` that a page impression does not carry, so they
+ * cannot be part of a query. A rule using one of these is either approximated
+ * (when it also has URL conditions) or reported as untranslatable.
+ *
+ * `hashparam` is among them: the runtime matches it against the fragment,
+ * which is not part of a URL the way the warehouse stores it.
+ */
+export const CRITERIA_OUTSIDE_THE_URL = Object.values(ConditionKey).filter((key) => key !== ConditionKey.ContentType &&
+    !URL_CONDITION_KEYS.includes(key));
+/**
+ * The subject a condition is really matched against. A `pathname` condition
+ * reads the query string too unless the rule set is version 2, which makes it
+ * a different subject — and one a query must not compare against the other.
+ */
+export function resolvedSubject(subject, ruleSetVersion) {
+    if (subject !== "pathname") {
+        return subject;
+    }
+    return matchesExactly(ruleSetVersion) ? "path" : "pathWithSearch";
+}
+/**
+ * True when the version matches parameter names and string conditions
+ * exactly. Version 1 treats them as prefixes and also feeds the query string
+ * into `pathname` conditions.
+ *
+ * The comparison is exact, not `>= 2`: `testCondition` in `@speedkit/rules`
+ * checks the version with `=== 2`, so a config declaring anything else falls
+ * back to the version 1 behaviour.
+ */
+export function matchesExactly(ruleSetVersion) {
+    return ruleSetVersion === 2;
+}

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

@@ -0,0 +1,33 @@
+import { ConditionPattern, NormalizedRule, ParsedRuleSets, StripParameterRule } from "./rule-model.js";
+/** Reads the rule sets a query is built from out of an evaluated config. */
+export declare function parseRuleSets(config: unknown): ParsedRuleSets;
+/** The declared rule-set version, or 1 for a config that declares none. */
+export declare function parseRuleSetVersion(config: unknown): number;
+/** Normalizes a `SpeedKitRule[]` — anything else yields no rules. */
+export declare function parseRules(value: unknown, source: string, ruleSetVersion: number): NormalizedRule[];
+/**
+ * Normalizes a `Condition` — a string, a regular expression, or an array of
+ * both — into a flat list of patterns.
+ */
+export declare function parseCondition(value: unknown): ConditionPattern[];
+/**
+ * Turns `disabledScopes` into rules.
+ *
+ * A scope is a service-worker scope, not a Speed Kit condition: a
+ * case-sensitive path prefix, matched on the URL string with no regular
+ * expression and no wildcard, so `/checkout` covers `/checkout/payment` and
+ * `/checkoutTunnel` but not `/en/checkout`. Written as an anchored pattern it
+ * says exactly that, and it can then be read, reduced and translated like
+ * every other rule.
+ *
+ * Pages under a scope are served by an empty service worker, so Speed Kit
+ * never touches them — they belong in neither a pre-warm list nor a parameter
+ * analysis.
+ */
+export declare function parseDisabledScopes(value: unknown): NormalizedRule[];
+/**
+ * Normalizes `stripQueryParams`, which is either a bare condition (every
+ * parameter matching it is stripped everywhere) or a list of rules that scope
+ * the stripping to certain pages or resources.
+ */
+export declare function parseStripQueryParams(value: unknown, ruleSetVersion: number): StripParameterRule[];

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

@@ -0,0 +1,189 @@
+import { types } from "node:util";
+import { ConditionKey } from "@speedkit/rules";
+import { escapeRegexLiteral } from "../sql/index.js";
+import { CRITERIA_OUTSIDE_THE_URL, DEFAULT_RULE_SET_VERSION, } from "./rule-model.js";
+const SUBJECTS = ["host", "pathname", "url"];
+/** Reads the rule sets a query is built from out of an evaluated config. */
+export function parseRuleSets(config) {
+    const speedKitConfig = asRecord(config) ?? {};
+    const ruleSetVersion = parseRuleSetVersion(speedKitConfig);
+    return {
+        blacklist: parseRules(speedKitConfig.blacklist, "blacklist", ruleSetVersion),
+        disabledScopes: parseDisabledScopes(speedKitConfig.disabledScopes),
+        disabledSites: parseRules(speedKitConfig.disabledSites, "disabledSites", ruleSetVersion),
+        enabledSites: parseRules(speedKitConfig.enabledSites, "enabledSites", ruleSetVersion),
+        ruleSetVersion,
+        stripQueryParams: parseStripQueryParams(speedKitConfig.stripQueryParams, ruleSetVersion),
+        whitelist: parseRules(speedKitConfig.whitelist, "whitelist", ruleSetVersion),
+    };
+}
+/** The declared rule-set version, or 1 for a config that declares none. */
+export function parseRuleSetVersion(config) {
+    const ruleSetConfig = asRecord(asRecord(config)?.ruleSetConfig);
+    const version = Number(ruleSetConfig?.version);
+    return Number.isFinite(version) && version > 0
+        ? version
+        : DEFAULT_RULE_SET_VERSION;
+}
+/** Normalizes a `SpeedKitRule[]` — anything else yields no rules. */
+export function parseRules(value, source, ruleSetVersion) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const rules = [];
+    for (const [index, entry] of value.entries()) {
+        const rule = parseRule(entry, `${source}[${index}]`, ruleSetVersion);
+        if (rule) {
+            rules.push(rule);
+        }
+    }
+    return rules;
+}
+/**
+ * Normalizes a `Condition` — a string, a regular expression, or an array of
+ * both — into a flat list of patterns.
+ */
+export function parseCondition(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    const entries = Array.isArray(value) ? value : [value];
+    const patterns = [];
+    for (const entry of entries) {
+        // The config is evaluated in a vm context, so its regular expressions come
+        // from another realm: `instanceof RegExp` is false for them here, and it
+        // is false again in `testCondition`. Rebuilding them in this realm is what
+        // makes every later check see a regular expression.
+        if (types.isRegExp(entry)) {
+            const { flags, source } = entry;
+            patterns.push({ kind: "regexp", value: new RegExp(source, flags) });
+            continue;
+        }
+        if (typeof entry === "string" || typeof entry === "number") {
+            patterns.push({ kind: "string", value: String(entry) });
+        }
+    }
+    return patterns;
+}
+function parseRule(value, source, ruleSetVersion) {
+    const rule = asRecord(value);
+    if (!rule) {
+        return undefined;
+    }
+    const conditions = [];
+    for (const subject of SUBJECTS) {
+        const patterns = parseCondition(rule[subject]);
+        if (patterns.length > 0) {
+            conditions.push({ patterns, subject });
+        }
+    }
+    const version = Number(rule.ruleSetVersion);
+    const keys = Object.values(ConditionKey).filter((key) => rule[key] !== undefined);
+    return {
+        conditions,
+        matchesNothing: keys.length === 0 ||
+            // An empty condition is satisfied by nothing, and every condition of a
+            // rule has to hold.
+            keys.some((key) => Array.isArray(rule[key]) && rule[key].length === 0),
+        contentTypes: parseContentTypes(rule.contentType),
+        criteriaOutsideTheUrl: CRITERIA_OUTSIDE_THE_URL.filter((criterion) => rule[criterion] !== undefined),
+        ruleSetVersion: Number.isFinite(version) && version > 0 ? version : ruleSetVersion,
+        source,
+    };
+}
+function parseContentTypes(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const entries = Array.isArray(value) ? value : [value];
+    const contentTypes = entries
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.toLowerCase());
+    return contentTypes.length > 0 ? contentTypes : undefined;
+}
+/**
+ * Turns `disabledScopes` into rules.
+ *
+ * A scope is a service-worker scope, not a Speed Kit condition: a
+ * case-sensitive path prefix, matched on the URL string with no regular
+ * expression and no wildcard, so `/checkout` covers `/checkout/payment` and
+ * `/checkoutTunnel` but not `/en/checkout`. Written as an anchored pattern it
+ * says exactly that, and it can then be read, reduced and translated like
+ * every other rule.
+ *
+ * Pages under a scope are served by an empty service worker, so Speed Kit
+ * never touches them — they belong in neither a pre-warm list nor a parameter
+ * analysis.
+ */
+export function parseDisabledScopes(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const rules = [];
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            continue;
+        }
+        rules.push({
+            conditions: [
+                {
+                    patterns: [
+                        {
+                            kind: "regexp",
+                            value: new RegExp(`^${escapeRegexLiteral(entry)}`),
+                        },
+                    ],
+                    subject: "pathname",
+                },
+            ],
+            criteriaOutsideTheUrl: [],
+            matchesNothing: false,
+            // Version 2 keeps the query string out of the subject, which is what a
+            // path prefix is matched against.
+            ruleSetVersion: 2,
+            source: `disabledScopes[${index}]`,
+        });
+    }
+    return rules;
+}
+/**
+ * Normalizes `stripQueryParams`, which is either a bare condition (every
+ * parameter matching it is stripped everywhere) or a list of rules that scope
+ * the stripping to certain pages or resources.
+ */
+export function parseStripQueryParams(value, ruleSetVersion) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    const entries = Array.isArray(value) ? value : [value];
+    // A bare condition: strings and regular expressions, no scoping.
+    const bare = entries.filter((entry) => typeof entry === "string" || entry instanceof RegExp);
+    if (bare.length === entries.length) {
+        const params = parseCondition(bare);
+        return params.length > 0
+            ? [{ params, ruleSetVersion, source: "stripQueryParams" }]
+            : [];
+    }
+    const rules = [];
+    for (const [index, entry] of entries.entries()) {
+        const rule = asRecord(entry);
+        const params = parseCondition(rule?.params);
+        if (!rule || params.length === 0) {
+            continue;
+        }
+        const source = `stripQueryParams[${index}]`;
+        rules.push({
+            enabledSites: parseRules(rule.enabledSites, `${source}.enabledSites`, ruleSetVersion),
+            params,
+            rules: parseRules(rule.rules, `${source}.rules`, ruleSetVersion),
+            ruleSetVersion,
+            source,
+        });
+    }
+    return rules;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}

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

@@ -0,0 +1,71 @@
+import { NormalizedRule } from "./rule-model.js";
+import { RuleNote } from "./rule-relevance.js";
+/**
+ * How much comparing the reductions may do in total.
+ *
+ * Deciding one pattern against another is cheap for the patterns configs
+ * normally use, but a handful of them build automata whose determinisation
+ * costs seconds. Reducing is an optimisation — a query that keeps a redundant
+ * rule is still correct — so the work is capped.
+ *
+ * The cap counts comparisons rather than milliseconds. A clock makes the
+ * result depend on how busy the machine was: the same config would reduce
+ * further on a quiet laptop than in CI, and two runs would disagree about a
+ * query nobody changed. Counting the work makes the output a function of the
+ * config alone, which is what a golden query and a snapshot diff need.
+ */
+export interface ReductionBudget {
+    /** True once no comparison is left. */
+    exhausted: () => boolean;
+    /** Takes one comparison from the budget; false when there was none left. */
+    spend: () => boolean;
+}
+/**
+ * The default budget for one query build.
+ *
+ * Calibrated against the configs in the onboarding repo: a config whose rules
+ * can be reduced spends far less than this — the largest reduction observed
+ * needs a few hundred — while the pathological ones, whose automata blow up on
+ * determinisation, are stopped before the command starts to feel slow.
+ */
+export declare const BUDGET_COMPARISONS = 800;
+/** A budget of that many comparisons. */
+export declare function reductionBudget(comparisons?: number): ReductionBudget;
+export interface ReductionResult {
+    /** What was reduced away, and what made it redundant. */
+    readonly notes: RuleNote[];
+    readonly rules: NormalizedRule[];
+}
+/**
+ * The rules of one set, with everything a sibling already covers removed.
+ *
+ * Every rule set is a disjunction, and so is the entry list of a condition, so
+ * whatever is contained in something next to it contributes nothing: `a or b`
+ * is `b` when `a` implies `b`. Dropping it cannot change the result — it only
+ * shortens the query, which is the point.
+ */
+export declare function absorbRules(rules: readonly NormalizedRule[], budget?: ReductionBudget): ReductionResult;
+/**
+ * The rules of an excluding set — `blacklist`, `disabledSites` — with
+ * everything that can never fire removed.
+ *
+ * A page has to pass every including set to reach the result at all, so an
+ * entry excluding pages none of them lets through excludes nothing. This is
+ * the bulk of what makes a generated query long: a config guards checkout,
+ * account and login while `enabledSites` only ever allowed the homepage and
+ * product pages. Configs write those guards as entries of a single rule, so
+ * the reduction works per entry and drops the rule only once a condition has
+ * no entry left that could match.
+ *
+ * @param reachable - The including sets, each a disjunction, all of which have
+ * to hold. An empty set means "everything" and is left out by the caller.
+ */
+export declare function dropUnreachableRules(rules: readonly NormalizedRule[], reachable: readonly (readonly NormalizedRule[])[], budget?: ReductionBudget): ReductionResult;
+/**
+ * Rules of an including set that an excluding rule covers completely — pages
+ * the config means to accelerate but never will.
+ *
+ * Unlike the reductions above this changes nothing about the query: it is a
+ * finding about the config, and the caller reports it.
+ */
+export declare function findShadowedRules(included: readonly NormalizedRule[], excluding: readonly NormalizedRule[], budget?: ReductionBudget): RuleNote[];