@speedkit/cli 4.26.0 → 4.27.0

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[];

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

@@ -0,0 +1,383 @@
+import { conditionLanguage, isInside, languagesDisjoint, outsideOf, } from "./pattern-language.js";
+import { resolvedSubject, } from "./rule-model.js";
+/**
+ * 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 const BUDGET_COMPARISONS = 800;
+/** A budget of that many comparisons. */
+export function reductionBudget(comparisons = BUDGET_COMPARISONS) {
+    let left = Math.max(0, Math.floor(comparisons));
+    return {
+        exhausted: () => left <= 0,
+        spend: () => left-- > 0,
+    };
+}
+/** A budget that never runs out. */
+const UNLIMITED = {
+    exhausted: () => false,
+    spend: () => true,
+};
+/** The note left behind when the budget ran out. */
+const STOPPED_EARLY = {
+    reason: `stopped after ${BUDGET_COMPARISONS} comparisons — rules that could still be reduced were kept`,
+    source: "reduction",
+};
+/** Every subject a query can provide. */
+const SUBJECTS = [
+    "host",
+    "path",
+    "pathWithSearch",
+    "url",
+];
+/**
+ * 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 function absorbRules(rules, budget = UNLIMITED) {
+    const notes = [];
+    const kept = [];
+    for (const [index, rule] of rules.entries()) {
+        if (budget.exhausted()) {
+            notes.push(STOPPED_EARLY);
+            kept.push(...rules.slice(index));
+            break;
+        }
+        // Compare against every other rule, but let only the earlier of two
+        // equivalent rules survive, or both would absorb each other.
+        const covering = rules.find((other, otherIndex) => otherIndex !== index &&
+            (otherIndex < index || !covers(rule, other, budget)) &&
+            covers(other, rule, budget));
+        if (covering) {
+            notes.push({
+                reason: `already covered by ${covering.source}`,
+                source: rule.source,
+            });
+            continue;
+        }
+        kept.push(absorbPatterns(rule, notes, budget));
+    }
+    return { notes, rules: kept };
+}
+/**
+ * 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 function dropUnreachableRules(rules, reachable, budget = UNLIMITED) {
+    const notes = [];
+    const kept = [];
+    const allowed = reachable.map((set) => ({
+        blocks: blockedSubjects(set),
+        rules: set,
+        source: sourceOf(set),
+    }));
+    for (const [index, rule] of rules.entries()) {
+        if (budget.exhausted()) {
+            notes.push(STOPPED_EARLY);
+            kept.push(...rules.slice(index));
+            break;
+        }
+        const narrowed = narrowToReachable(rule, allowed, notes, budget);
+        if (narrowed) {
+            kept.push(narrowed);
+        }
+    }
+    return { notes, rules: kept };
+}
+/**
+ * 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 function findShadowedRules(included, excluding, budget = UNLIMITED) {
+    const notes = [];
+    for (const rule of included) {
+        if (budget.exhausted()) {
+            break;
+        }
+        const shadowing = excluding.find((other) => covers(other, rule, budget));
+        if (shadowing) {
+            notes.push({
+                reason: `is completely excluded again by ${shadowing.source}, so it never applies`,
+                source: rule.source,
+            });
+        }
+    }
+    return notes;
+}
+/**
+ * The rule without the condition entries no reachable page can match, or
+ * `undefined` when a condition ends up with no entry at all — the rule then
+ * matches nothing.
+ */
+function narrowToReachable(rule, allowed, notes, budget) {
+    const conditions = [];
+    for (const condition of rule.conditions) {
+        const subject = resolvedSubject(condition.subject, rule.ruleSetVersion);
+        const reasons = new Map();
+        const patterns = condition.patterns.filter((pattern) => {
+            if (budget.exhausted()) {
+                return true;
+            }
+            const blocking = blockingSet(pattern, condition, rule, subject, allowed, budget);
+            if (blocking) {
+                reasons.set(pattern, blocking);
+            }
+            return !blocking;
+        });
+        if (patterns.length === 0) {
+            notes.push({
+                reason: `matches no page ${[...new Set(reasons.values())].join(" or ")} lets through`,
+                source: rule.source,
+            });
+            return undefined;
+        }
+        for (const [pattern, source] of reasons) {
+            notes.push({
+                reason: `${literalOf(pattern)} matches no page ${source} lets through`,
+                source: `${rule.source}.${condition.subject}`,
+            });
+        }
+        conditions.push({ ...condition, patterns });
+    }
+    return { ...rule, conditions };
+}
+/**
+ * The including set that keeps every page this entry matches out, if there is
+ * one. A set does that when none of its rules leaves room for the entry.
+ */
+function blockingSet(pattern, condition, rule, subject, allowed, budget) {
+    const candidates = allowed.filter((set) => set.blocks.has(subject));
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const language = languageOf(pattern, condition, rule, "atLeast");
+    if (!language) {
+        return undefined;
+    }
+    const blocking = candidates.find((set) => set.rules.every((allowedRule) => {
+        // A rule matching nothing keeps everything out.
+        if (allowedRule.matchesNothing) {
+            return true;
+        }
+        // A rule whose patterns have no automaton might leave room.
+        const allowedLanguage = languagesOf(allowedRule, "atLeast")?.get(subject);
+        return (!!allowedLanguage &&
+            budget.spend() &&
+            languagesDisjoint(language, allowedLanguage) === true);
+    }));
+    return blocking?.source;
+}
+/** The rule with the condition entries a sibling entry already covers removed. */
+function absorbPatterns(rule, notes, budget) {
+    const conditions = rule.conditions.map((condition) => {
+        if (condition.patterns.length < 2) {
+            return condition;
+        }
+        // The same entry is offered as the covering one to every other entry, so
+        // its complement is built once.
+        const outsides = new Map();
+        const outsideFor = (pattern) => {
+            if (!outsides.has(pattern)) {
+                const language = languageOf(pattern, condition, rule, "atMost");
+                outsides.set(pattern, language && outsideOf(language));
+            }
+            return outsides.get(pattern);
+        };
+        const patterns = condition.patterns.filter((pattern, index) => {
+            if (budget.exhausted()) {
+                return true;
+            }
+            const covering = condition.patterns.find((other, otherIndex) => otherIndex === index
+                ? false
+                : coversPattern(other, pattern, condition, rule, otherIndex < index, outsideFor, budget));
+            if (covering) {
+                notes.push({
+                    reason: `${literalOf(pattern)} is already covered by ${literalOf(covering)}`,
+                    source: `${rule.source}.${condition.subject}`,
+                });
+            }
+            return !covering;
+        });
+        return { ...condition, patterns };
+    });
+    return { ...rule, conditions };
+}
+/**
+ * True when every subject the entry matches is matched by `covering` too.
+ *
+ * @param mayAbsorbEquivalent - Whether `covering` is allowed to absorb an
+ * entry equivalent to it, which only the earlier of the two may do.
+ */
+function coversPattern(covering, pattern, condition, rule, mayAbsorbEquivalent, outsideFor, budget) {
+    if (!budget.spend()) {
+        return false;
+    }
+    const beyondCovering = outsideFor(covering);
+    const narrower = languageOf(pattern, condition, rule, "atLeast");
+    if (!beyondCovering ||
+        !narrower ||
+        isInside(narrower, beyondCovering) !== true) {
+        return false;
+    }
+    if (mayAbsorbEquivalent) {
+        return true;
+    }
+    const beyondPattern = outsideFor(pattern);
+    const coveringAtLeast = languageOf(covering, condition, rule, "atLeast");
+    const equivalent = !!beyondPattern &&
+        !!coveringAtLeast &&
+        isInside(coveringAtLeast, beyondPattern) === true;
+    return !equivalent;
+}
+/** The language of a single condition entry. */
+function languageOf(pattern, condition, rule, bound) {
+    return conditionLanguage({ patterns: [pattern], subject: condition.subject }, rule.ruleSetVersion, bound);
+}
+/** True when every page `rule` matches is matched by `covering` as well. */
+function covers(covering, rule, budget) {
+    if (covering.matchesNothing || rule.matchesNothing) {
+        return false;
+    }
+    if (!coversContentTypes(covering, rule)) {
+        return false;
+    }
+    // A subject the covering rule constrains and the other one does not leaves
+    // that one wider. Checking the subjects first keeps the automata out of the
+    // comparison of two rules that talk about different parts of the URL.
+    const constrained = subjectsOf(rule);
+    if (![...subjectsOf(covering)].every((subject) => constrained.has(subject))) {
+        return false;
+    }
+    // Everything past here builds automata, so it costs a comparison.
+    if (!budget.spend()) {
+        return false;
+    }
+    // Containment holds when everything the rule can match — at least — stays
+    // inside what the covering rule matches at most.
+    const languages = languagesOf(rule, "atLeast");
+    const outside = outsideLanguagesOf(covering);
+    if (!languages || !outside) {
+        return false;
+    }
+    // Every subject the covering rule constrains has to be constrained at least
+    // as narrowly by the other one. A subject it does not constrain is free,
+    // which can only make it wider.
+    for (const [subject, beyond] of outside) {
+        const narrower = languages.get(subject);
+        if (!narrower || !beyond || isInside(narrower, beyond) !== true) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The language of every subject a rule constrains, or `undefined` when one of
+ * them has no automaton — in which case the rule takes part in no reduction.
+ */
+function languagesOf(rule, bound) {
+    const cached = ruleCache.get(rule);
+    if (cached?.has(bound)) {
+        return cached.get(bound);
+    }
+    const languages = buildLanguagesOf(rule, bound);
+    if (cached) {
+        cached.set(bound, languages);
+    }
+    else {
+        ruleCache.set(rule, new Map([[bound, languages]]));
+    }
+    return languages;
+}
+/** Languages already collected, per rule. */
+const ruleCache = new WeakMap();
+/** Complements already built, per rule. */
+const outsideCache = new WeakMap();
+/**
+ * What every subject of a rule does *not* match, built once per rule: the same
+ * rule is offered as the covering one to every other rule of its set.
+ */
+function outsideLanguagesOf(rule) {
+    if (outsideCache.has(rule)) {
+        return outsideCache.get(rule);
+    }
+    const languages = languagesOf(rule, "atMost");
+    const outside = languages
+        ? new Map([...languages].map(([subject, language]) => [
+            subject,
+            outsideOf(language),
+        ]))
+        : undefined;
+    outsideCache.set(rule, outside);
+    return outside;
+}
+function buildLanguagesOf(rule, bound) {
+    const languages = new Map();
+    for (const condition of rule.conditions) {
+        const language = conditionLanguage(condition, rule.ruleSetVersion, bound);
+        if (!language) {
+            return undefined;
+        }
+        languages.set(resolvedSubject(condition.subject, rule.ruleSetVersion), language);
+    }
+    return languages;
+}
+/** True when `covering` applies wherever `rule` does, content-type-wise. */
+function coversContentTypes(covering, rule) {
+    if (!covering.contentTypes) {
+        return true;
+    }
+    return (rule.contentTypes?.every((type) => covering.contentTypes?.includes(type)) ??
+        false);
+}
+/** The subjects a rule constrains. */
+function subjectsOf(rule) {
+    return new Set(rule.conditions.map(({ subject }) => resolvedSubject(subject, rule.ruleSetVersion)));
+}
+/**
+ * The subjects on which a set of allowed rules can keep something out: those
+ * every one of its rules constrains.
+ */
+function blockedSubjects(rules) {
+    let blocked = new Set(SUBJECTS);
+    for (const rule of rules) {
+        // A rule matching nothing keeps everything out, on every subject.
+        if (rule.matchesNothing) {
+            continue;
+        }
+        const constrained = subjectsOf(rule);
+        blocked = new Set([...blocked].filter((subject) => constrained.has(subject)));
+    }
+    return blocked;
+}
+/** The rule set a group of rules came from, for a readable reason. */
+function sourceOf(rules) {
+    const [first] = rules;
+    return first ? first.source.replace(/\[\d+].*$/, "") : "the enabled pages";
+}
+function literalOf(pattern) {
+    return pattern.kind === "regexp"
+        ? String(pattern.value)
+        : `"${pattern.value}"`;
+}

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

@@ -0,0 +1,43 @@
+import { NormalizedRule } from "./rule-model.js";
+export interface RelevanceContext {
+    /**
+     * Content types a row of the queried relation can have. A page impression
+     * is a document, so a rule written for images or scripts can never apply.
+     */
+    readonly contentTypes?: readonly string[];
+    /**
+     * Hosts the query is already restricted to — the app's origins. A rule
+     * whose host condition matches none of them can never fire. Leave empty
+     * when the hosts are not known, and the check is skipped.
+     */
+    readonly hosts?: readonly string[];
+}
+export interface RuleNote {
+    readonly reason: string;
+    /** Where the rule sits in the config, e.g. `blacklist[3]`. */
+    readonly source: string;
+}
+export interface RelevanceResult {
+    /**
+     * Rules that survive but do not mean exactly what the config means — they
+     * carry a criterion outside the URL that the query cannot express, so the
+     * emitted filter is wider than the rule.
+     */
+    readonly approximated: RuleNote[];
+    /** Rules that can never apply to a row of this query. */
+    readonly dropped: RuleNote[];
+    readonly rules: NormalizedRule[];
+}
+/**
+ * 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 declare function keepRelevantRules(rules: readonly NormalizedRule[], context?: RelevanceContext): RelevanceResult;