@speedkit/cli 4.25.2 → 4.27.0

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

@@ -0,0 +1,88 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { parseRuleSets } from "../rule-parser.js";
+import { keepRelevantRules } from "../rule-relevance.js";
+function blacklist(...rules) {
+    return parseRuleSets({ blacklist: rules }).blacklist;
+}
+function blacklistV2(...rules) {
+    return parseRuleSets({ blacklist: rules, ruleSetConfig: { version: 2 } })
+        .blacklist;
+}
+describe("keepRelevantRules content types", () => {
+    it("should drop a rule that only applies to other content types", () => {
+        const result = keepRelevantRules(blacklist({ contentType: ["image", "script"], pathname: "/media" }));
+        expect(result.rules).to.deep.equal([]);
+        expect(result.dropped[0].reason).to.contain("image, script");
+    });
+    it("should keep a rule that also applies to documents", () => {
+        const result = keepRelevantRules(blacklist({ contentType: ["document"], pathname: "/checkout" }));
+        expect(result.rules).to.have.lengthOf(1);
+    });
+    it("should keep a rule without a content type", () => {
+        const result = keepRelevantRules(blacklist({ pathname: "/checkout" }));
+        expect(result.rules).to.have.lengthOf(1);
+    });
+});
+describe("keepRelevantRules criteria outside the url", () => {
+    it("should drop a rule that matches on a cookie only", () => {
+        const result = keepRelevantRules(blacklist({ cookie: /loggedIn/ }));
+        expect(result.rules).to.deep.equal([]);
+        expect(result.dropped[0].reason).to.contain("cookie");
+    });
+    it("should keep a rule with url conditions and report it as approximated", () => {
+        const result = keepRelevantRules(blacklist({ cookie: /loggedIn/, pathname: "/account" }));
+        expect(result.rules).to.have.lengthOf(1);
+        expect(result.approximated).to.have.lengthOf(1);
+        expect(result.approximated[0].reason).to.contain("wider than the rule");
+    });
+    it("should not report a plain rule as approximated", () => {
+        const result = keepRelevantRules(blacklist({ pathname: "/account" }));
+        expect(result.approximated).to.deep.equal([]);
+    });
+});
+describe("keepRelevantRules hosts", () => {
+    const hosts = ["www.shop.de", "m.shop.de"];
+    it("should drop a rule for a host the query does not cover", () => {
+        const result = keepRelevantRules(blacklist({ host: ["cdn.tracking.com"] }), { hosts });
+        expect(result.rules).to.deep.equal([]);
+        expect(result.dropped[0].reason).to.contain("none of the queried origins");
+    });
+    it("should keep a rule for a covered host", () => {
+        const result = keepRelevantRules(blacklist({ host: ["m.shop.de"] }), {
+            hosts,
+        });
+        expect(result.rules).to.have.lengthOf(1);
+    });
+    it("should keep a rule whose host pattern matches", () => {
+        const result = keepRelevantRules(blacklist({ host: [/shop\.de$/i] }), {
+            hosts,
+        });
+        expect(result.rules).to.have.lengthOf(1);
+    });
+    it("should treat a host string as a prefix under version 1", () => {
+        const result = keepRelevantRules(blacklist({ host: ["www.shop"] }), {
+            hosts,
+        });
+        expect(result.rules).to.have.lengthOf(1);
+    });
+    it("should treat a host string as exact under version 2", () => {
+        const result = keepRelevantRules(blacklistV2({ host: ["www.shop"] }), {
+            hosts,
+        });
+        expect(result.rules).to.deep.equal([]);
+    });
+    it("should not be confused by a global pattern matched twice", () => {
+        const rules = blacklist({ host: [/shop\.de/g] }, { host: [/shop\.de/g] });
+        const result = keepRelevantRules(rules, { hosts });
+        expect(result.rules).to.have.lengthOf(2);
+    });
+    it("should keep a rule without a host condition", () => {
+        const result = keepRelevantRules(blacklist({ pathname: "/a" }), { hosts });
+        expect(result.rules).to.have.lengthOf(1);
+    });
+    it("should skip the check when no hosts are given", () => {
+        const result = keepRelevantRules(blacklist({ host: ["cdn.other.com"] }));
+        expect(result.rules).to.have.lengthOf(1);
+    });
+});

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

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

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

@@ -0,0 +1,110 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { column, formatPredicate, isFalse, isTrue, leaf, } from "../../sql/index.js";
+import { parseRuleSets } from "../rule-parser.js";
+import { translateRules, urlSubjects } from "../rule-to-sql.js";
+const subjects = urlSubjects(column("url"));
+function enabledSites(rules, version) {
+    return parseRuleSets({
+        enabledSites: rules,
+        ...(version ? { ruleSetConfig: { version } } : {}),
+    }).enabledSites;
+}
+function sql(rules, version) {
+    return formatPredicate(translateRules(enabledSites(rules, version), subjects).predicate);
+}
+describe("urlSubjects", () => {
+    it("should extract the host", () => {
+        expect(subjects.host).to.equal("url_extract_host(url)");
+    });
+    it("should read an empty path as the root, like the browser does", () => {
+        expect(subjects.path).to.equal("coalesce(nullif(url_extract_path(url), ''), '/')");
+    });
+    it("should append the query string for the version 1 pathname subject", () => {
+        expect(subjects.pathWithSearch).to.equal(`(${subjects.path} || coalesce(nullif(('?' || url_extract_query(url)), '?'), ''))`);
+    });
+    it("should strip fragment and scheme from the url subject", () => {
+        expect(subjects.url).to.equal(String.raw `regexp_replace(regexp_replace(url, '#.*', ''), '^(\w+:)?//', '')`);
+    });
+});
+describe("translateRules string conditions", () => {
+    it("should match a pathname as a prefix under version 1", () => {
+        expect(sql([{ pathname: "/shop" }])).to.equal(`lower(${subjects.pathWithSearch}) like '/shop%'`);
+    });
+    it("should match a pathname exactly under version 2", () => {
+        expect(sql([{ pathname: "/shop" }], 2)).to.equal(`lower(${subjects.path}) = '/shop'`);
+    });
+    it("should ignore the case of a host condition", () => {
+        expect(sql([{ host: "WWW.Shop.de" }], 2)).to.equal(`lower(${subjects.host}) = 'www.shop.de'`);
+    });
+    it("should match a url condition against the stripped url", () => {
+        // `stripForRules` takes the scheme off, so the config writes the URL
+        // without one — and so does the comparison.
+        expect(sql([{ url: "www.shop.de/" }], 2)).to.equal(`lower(${subjects.url}) = 'www.shop.de/'`);
+    });
+});
+describe("translateRules regular expressions", () => {
+    it("should move the i flag into the pattern", () => {
+        expect(sql([{ pathname: [/^\/p\//i] }], 2)).to.equal(`regexp_like(${subjects.path}, '(?i)^/p/')`);
+    });
+    it("should match a version 1 pathname pattern against path and query", () => {
+        expect(sql([{ pathname: [/\/$/i] }])).to.equal(`regexp_like(${subjects.pathWithSearch}, '(?i)/$')`);
+    });
+    it("should report a warning with the rule it came from", () => {
+        const { warnings } = translateRules(enabledSites([{ pathname: [/(?<=\/de)\/p\//i] }]), subjects);
+        expect(warnings).to.have.lengthOf(1);
+        expect(warnings[0]).to.contain("enabledSites[0]");
+        expect(warnings[0]).to.contain("lookbehind");
+    });
+});
+describe("translateRules structure", () => {
+    it("should or the entries of a condition", () => {
+        expect(sql([{ pathname: ["/a", "/b"] }], 2)).to.equal([
+            `lower(${subjects.path}) = '/a'`,
+            `or lower(${subjects.path}) = '/b'`,
+        ].join("\n"));
+    });
+    it("should and the conditions of a rule", () => {
+        expect(sql([{ host: "www.shop.de", pathname: "/a" }], 2)).to.equal([
+            `lower(${subjects.host}) = 'www.shop.de'`,
+            `and lower(${subjects.path}) = '/a'`,
+        ].join("\n"));
+    });
+    it("should or the rules of a set, keeping each rule's conditions together", () => {
+        expect(sql([
+            { host: "www.shop.de", pathname: "/de/" },
+            { host: "www.shop.fr", pathname: "/fr/" },
+        ], 2)).to.equal([
+            "(",
+            `  lower(${subjects.host}) = 'www.shop.de'`,
+            `  and lower(${subjects.path}) = '/de/'`,
+            ")",
+            "or (",
+            `  lower(${subjects.host}) = 'www.shop.fr'`,
+            `  and lower(${subjects.path}) = '/fr/'`,
+            ")",
+        ].join("\n"));
+    });
+    it("should match nothing for a rule without conditions", () => {
+        // The runtime's AndRule returns false when it holds no condition.
+        expect(isFalse(translateRules(enabledSites([{}]), subjects).predicate)).to.equal(true);
+    });
+    it("should match nothing for a rule whose condition is empty", () => {
+        // `host: hasWebPSupport ? [] : [...]` is a real config. Reading the empty
+        // list as "any host" would make a blacklist exclude everything.
+        expect(isFalse(translateRules(enabledSites([{ host: [] }]), subjects).predicate)).to.equal(true);
+    });
+    it("should keep a rule whose other condition is empty out of the way", () => {
+        const { predicate } = translateRules(enabledSites([{ host: [], pathname: [/^\/p\//i] }]), subjects);
+        expect(isFalse(predicate)).to.equal(true);
+    });
+    it("should be true for an empty rule set by default", () => {
+        expect(isTrue(translateRules([], subjects).predicate)).to.equal(true);
+    });
+    it("should use the given meaning of an empty rule set", () => {
+        const { predicate } = translateRules([], subjects, {
+            whenEmpty: leaf("a"),
+        });
+        expect(formatPredicate(predicate)).to.equal("a");
+    });
+});

package/dist/services/query-builder/rules/spec/runtime-semantics.spec.d.ts

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

package/dist/services/query-builder/rules/spec/runtime-semantics.spec.js

@@ -0,0 +1,55 @@
+import { PathnameRule, testCondition } from "@speedkit/rules";
+import { expect } from "chai";
+import { before, describe, it } from "mocha";
+import { matchesExactly } from "../rule-model.js";
+/**
+ * The query builder mirrors decisions that `@speedkit/rules` makes in the
+ * browser. It cannot call into the package to build SQL, so these tests pin
+ * the mirrored behaviour against the package itself — if the runtime ever
+ * changes how a condition or a subject is read, they fail here rather than in
+ * a query nobody re-reads.
+ */
+const VERSIONS = [1, 2, 3];
+describe("string conditions follow the runtime", () => {
+    for (const version of VERSIONS) {
+        it(`should match exactly only where the runtime does, version ${version}`, () => {
+            // A subject the condition is a prefix of, but not equal to.
+            const runtimeMatchesPrefix = testCondition("/shoes/nike", "/shoes", version);
+            const runtimeMatchesExact = testCondition("/shoes", "/shoes", version);
+            expect(runtimeMatchesExact).to.equal(true);
+            expect(runtimeMatchesPrefix).to.equal(!matchesExactly(version));
+        });
+    }
+    it("should ignore case on both sides", () => {
+        expect(testCondition("/Shoes", "/shOES", 1)).to.equal(true);
+        expect(testCondition("/Shoes", "/shOES", 2)).to.equal(true);
+    });
+});
+describe("the pathname subject follows the runtime", () => {
+    // The package resolves a request URL against `location`, which only exists
+    // in a browser. Anything that evaluates a rule outside one has to provide it.
+    before(() => {
+        const global = globalThis;
+        global.location ??= new URL("https://www.shop.de/");
+    });
+    function matchesPathname(pattern, ruleSetVersion) {
+        return new PathnameRule(pattern).matches(new Request("https://www.shop.de/shoes/?page=2"), { ruleSetVersion });
+    }
+    it("should test a version 1 pattern against path and query", () => {
+        // The subject ends in `2`, not in the slash, so the anchored pattern
+        // misses a URL a reader would expect it to cover.
+        expect(matchesPathname(/\/$/, 1)).to.equal(false);
+    });
+    it("should test a version 2 pattern against the path alone", () => {
+        expect(matchesPathname(/\/$/, 2)).to.equal(true);
+    });
+    it("should fall back to the version 1 subject for any other version", () => {
+        expect(matchesPathname(/\/$/, 3)).to.equal(false);
+        expect(matchesExactly(3)).to.equal(false);
+    });
+    it("should match a pattern that survives both versions", () => {
+        const bothVersions = /^[^?]*\/(\?|$)/;
+        expect(matchesPathname(bothVersions, 1)).to.equal(true);
+        expect(matchesPathname(bothVersions, 2)).to.equal(true);
+    });
+});

package/dist/services/query-builder/rules/spec/strip-parameters.spec.d.ts

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

package/dist/services/query-builder/rules/spec/strip-parameters.spec.js

@@ -0,0 +1,85 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { column, formatPredicate } from "../../sql/index.js";
+import { parseRuleSets } from "../rule-parser.js";
+import { urlSubjects } from "../rule-to-sql.js";
+import { notStrippedParameter, prepareStripParameters, strippedUrlExpression, } from "../strip-parameters.js";
+const subjects = urlSubjects(column("url"));
+function prepare(stripQueryParams, version = 2) {
+    return prepareStripParameters(parseRuleSets({ ruleSetConfig: { version }, stripQueryParams })
+        .stripQueryParams, subjects);
+}
+function strippedUrl(stripQueryParams, version = 2) {
+    return strippedUrlExpression(prepare(stripQueryParams, version), "url");
+}
+function keptParameter(stripQueryParams, version = 2) {
+    return formatPredicate(notStrippedParameter(prepare(stripQueryParams, version), "key"));
+}
+describe("strippedUrlExpression", () => {
+    it("should always remove the fragment", () => {
+        expect(strippedUrl([])).to.equal("regexp_replace(url, '#.*')");
+    });
+    it("should match a name exactly under version 2", () => {
+        expect(strippedUrl(["gclid"])).to.contain("(?i)[?&](gclid)(=[^&]*)?(?=&|$)");
+    });
+    it("should match a name as a prefix under version 1", () => {
+        expect(strippedUrl(["utm"], 1)).to.contain("(?i)[?&](utm)[^&]*");
+    });
+    it("should escape a name that reads as a pattern", () => {
+        expect(strippedUrl(["a.b"])).to.contain(String.raw `(a\.b)`);
+    });
+    it("should use the prefix form for a pattern anchored at the start", () => {
+        expect(strippedUrl([/^utm[_-]/i])).to.contain("(?i)[?&](utm[_-])[^&]*");
+    });
+    it("should use the suffix form for a pattern anchored at the end", () => {
+        expect(strippedUrl([/id$/i])).to.contain("(?i)[?&][^&]*(id)(=[^&]*)?(?=&|$)");
+    });
+    it("should keep case-sensitive patterns in their own expression", () => {
+        const expression = strippedUrl([/^utm/, /^UTM/i]);
+        expect(expression).to.contain("'[?&](utm)[^&]*'");
+        expect(expression).to.contain("'(?i)[?&](UTM)[^&]*'");
+    });
+    it("should merge rules that strip everywhere into one expression", () => {
+        const merged = strippedUrl([{ params: ["a"] }, { params: ["b"] }]);
+        expect(merged.match(/regexp_replace/g)).to.have.lengthOf(2);
+        expect(merged).to.contain("(a|b)");
+    });
+    it("should apply a scoped rule only on the pages it names", () => {
+        const expression = strippedUrl([
+            { enabledSites: [{ pathname: [/^\/p\//i] }], params: ["size"] },
+        ]);
+        expect(expression).to.contain("if(regexp_like(");
+        expect(expression).to.contain("(?i)^/p/");
+    });
+    it("should leave out a rule scoped to something that is never a document", () => {
+        const prepared = prepare([
+            { params: ["size"], rules: [{ contentType: ["image"] }] },
+        ]);
+        expect(prepared.groups).to.deep.equal([]);
+        expect(prepared.dropped[0].source).to.equal("stripQueryParams[0]");
+    });
+});
+describe("notStrippedParameter", () => {
+    it("should keep every parameter when nothing is stripped", () => {
+        expect(keptParameter([])).to.equal("true");
+    });
+    it("should reject a stripped name exactly under version 2", () => {
+        expect(keptParameter(["gclid"])).to.equal("not (lower(key) = 'gclid')");
+    });
+    it("should reject a stripped name as a prefix under version 1", () => {
+        expect(keptParameter(["utm"], 1)).to.equal("not (lower(key) like 'utm%')");
+    });
+    it("should reject every stripped name", () => {
+        expect(keptParameter(["a", "b"])).to.equal("not (lower(key) = 'a')\nand not (lower(key) = 'b')");
+    });
+    it("should reject a scoped name only on its own pages", () => {
+        expect(keptParameter([
+            { enabledSites: [{ pathname: [/^\/p\//i] }], params: ["size"] },
+        ])).to.equal([
+            "not (",
+            "  regexp_like(coalesce(nullif(url_extract_path(url), ''), '/'), '(?i)^/p/')",
+            "  and lower(key) = 'size'",
+            ")",
+        ].join("\n"));
+    });
+});

package/dist/services/query-builder/rules/strip-parameters.d.ts

@@ -0,0 +1,39 @@
+import { Predicate, SqlExpression } from "../sql/index.js";
+import { ConditionPattern, StripParameterRule } from "./rule-model.js";
+import { RelevanceContext, RuleNote } from "./rule-relevance.js";
+import { RuleSubjectExpressions } from "./rule-to-sql.js";
+/** Parameters that are stripped on the pages a scope predicate selects. */
+export interface StripParameterGroup {
+    readonly params: readonly ConditionPattern[];
+    readonly ruleSetVersion: number;
+    /** `TRUE` when the parameters are stripped everywhere. */
+    readonly scope: Predicate;
+    readonly sources: string[];
+}
+export interface PreparedStripParameters {
+    /** Strip rules that cannot apply to a page impression. */
+    readonly dropped: RuleNote[];
+    readonly groups: StripParameterGroup[];
+    readonly warnings: string[];
+}
+/**
+ * Turns the `stripQueryParams` rules into the groups the query needs.
+ *
+ * Rules that strip everywhere are merged into a single group so their
+ * parameters share one set of expressions, which is what the emitted query
+ * looked like before scoping was understood. A rule limited to certain pages
+ * or resources keeps its own group and carries the predicate that selects
+ * them; one limited to resources that are never documents is dropped.
+ */
+export declare function prepareStripParameters(rules: readonly StripParameterRule[], subjects: RuleSubjectExpressions, context?: RelevanceContext): PreparedStripParameters;
+/**
+ * The URL with every stripped parameter and the fragment removed — the cache
+ * key Speed Kit would use. Built as nested `regexp_replace` calls, one per
+ * kind of parameter pattern.
+ */
+export declare function strippedUrlExpression(prepared: PreparedStripParameters, url: SqlExpression, warnings?: string[]): SqlExpression;
+/**
+ * Holds for a parameter name that Speed Kit keeps — the filter the parameter
+ * analysis applies to every key of a URL.
+ */
+export declare function notStrippedParameter(prepared: PreparedStripParameters, key: SqlExpression, warnings?: string[]): Predicate;

package/dist/services/query-builder/rules/strip-parameters.js

@@ -0,0 +1,197 @@
+import { and, call, equalsIgnoreCase, escapeRegexLiteral, formatPredicate, isTrue, literal, not, or, regexpLike, startsWith, toAthenaRegex, TRUE, } from "../sql/index.js";
+import { matchesExactly, } from "./rule-model.js";
+import { keepRelevantRules, } from "./rule-relevance.js";
+import { translateRules } from "./rule-to-sql.js";
+/**
+ * Turns the `stripQueryParams` rules into the groups the query needs.
+ *
+ * Rules that strip everywhere are merged into a single group so their
+ * parameters share one set of expressions, which is what the emitted query
+ * looked like before scoping was understood. A rule limited to certain pages
+ * or resources keeps its own group and carries the predicate that selects
+ * them; one limited to resources that are never documents is dropped.
+ */
+export function prepareStripParameters(rules, subjects, context = {}) {
+    const dropped = [];
+    const warnings = [];
+    const groups = [];
+    // Groups the rules stripping everywhere are merged into, one per version.
+    const unscoped = new Map();
+    for (const rule of rules) {
+        const page = scopeOf(rule.enabledSites, subjects, context, warnings);
+        const resource = scopeOf(rule.rules, subjects, context, warnings);
+        if (!page || !resource) {
+            dropped.push({
+                reason: "strips parameters only on pages or resources a page impression can never be",
+                source: rule.source,
+            });
+            continue;
+        }
+        const scope = and(page, resource);
+        const merged = isTrue(scope)
+            ? unscoped.get(rule.ruleSetVersion)
+            : undefined;
+        if (merged) {
+            merged.params.push(...rule.params);
+            merged.sources.push(rule.source);
+            continue;
+        }
+        // The group holds the very arrays the map keeps, so a later rule that
+        // strips everywhere too extends this group instead of adding another.
+        const group = {
+            params: [...rule.params],
+            ruleSetVersion: rule.ruleSetVersion,
+            scope,
+            sources: [rule.source],
+        };
+        groups.push(group);
+        if (isTrue(scope)) {
+            unscoped.set(rule.ruleSetVersion, group);
+        }
+    }
+    return { dropped, groups, warnings };
+}
+/**
+ * The URL with every stripped parameter and the fragment removed — the cache
+ * key Speed Kit would use. Built as nested `regexp_replace` calls, one per
+ * kind of parameter pattern.
+ */
+export function strippedUrlExpression(prepared, url, warnings = []) {
+    let expression = call("regexp_replace", url, literal("#.*"));
+    for (const group of prepared.groups) {
+        const replaced = replaceParameters(group, expression, warnings);
+        expression = isTrue(group.scope)
+            ? replaced
+            : // Commas separate the arguments, and `and` binds tighter, so the
+                // predicate needs no parentheses of its own here.
+                call("if", formatPredicate(group.scope), replaced, expression);
+    }
+    return expression;
+}
+/**
+ * Holds for a parameter name that Speed Kit keeps — the filter the parameter
+ * analysis applies to every key of a URL.
+ */
+export function notStrippedParameter(prepared, key, warnings = []) {
+    return and(...prepared.groups.map((group) => {
+        const matches = group.params.map((pattern) => matchesParameter(pattern, key, group.ruleSetVersion, warnings));
+        return isTrue(group.scope)
+            ? and(...matches.map((match) => not(match)))
+            : not(and(group.scope, or(...matches)));
+    }));
+}
+/**
+ * The predicate selecting the pages or resources a strip rule is scoped to,
+ * or `undefined` when the scope was given but can never hold for a document.
+ */
+function scopeOf(rules, subjects, context, warnings) {
+    if (!rules || rules.length === 0) {
+        return TRUE;
+    }
+    const relevant = keepRelevantRules(rules, context);
+    if (relevant.rules.length === 0) {
+        return undefined;
+    }
+    const { predicate, warnings: ruleWarnings } = translateRules(relevant.rules, subjects);
+    warnings.push(...ruleWarnings);
+    return predicate;
+}
+function matchesParameter(pattern, key, ruleSetVersion, warnings) {
+    if (pattern.kind === "regexp") {
+        const athenaRegex = toAthenaRegex(pattern.value);
+        warnings.push(...athenaRegex.warnings.map((warning) => `stripQueryParams: ${warning}`));
+        return regexpLike(key, athenaRegex.pattern);
+    }
+    // A parameter name is a string condition: case-insensitive, and a prefix
+    // until the config moves to rule-set version 2.
+    return matchesExactly(ruleSetVersion)
+        ? equalsIgnoreCase(key, pattern.value)
+        : startsWith(key, pattern.value);
+}
+/**
+ * Nests one `regexp_replace` per pattern kind around the given expression.
+ *
+ * A parameter is removed together with its value, and where in the name the
+ * pattern has to match depends on how it is anchored: `/^utm/` covers every
+ * name starting with `utm`, `/id$/` every name ending in it, a plain name
+ * matches the whole key. Case-insensitive patterns need their own expression
+ * because the flag applies to the whole alternation.
+ */
+function replaceParameters(group, expression, warnings) {
+    const buckets = bucketParameters(group, warnings);
+    const patterns = [
+        prefixPattern(buckets.prefix, false),
+        prefixPattern(buckets.prefixIgnoreCase, true),
+        suffixPattern(buckets.suffix, false),
+        suffixPattern(buckets.suffixIgnoreCase, true),
+        fullPattern(buckets.full, false),
+        fullPattern(buckets.fullIgnoreCase, true),
+    ];
+    let replaced = expression;
+    for (const pattern of patterns) {
+        if (pattern) {
+            replaced = call("regexp_replace", replaced, literal(pattern), literal(""));
+        }
+    }
+    return replaced;
+}
+function bucketParameters(group, warnings) {
+    const buckets = {
+        full: [],
+        fullIgnoreCase: [],
+        prefix: [],
+        prefixIgnoreCase: [],
+        suffix: [],
+        suffixIgnoreCase: [],
+    };
+    for (const pattern of group.params) {
+        if (pattern.kind === "string") {
+            // A string is matched case-insensitively, so it belongs to the
+            // ignore-case bucket, and version 1 treats it as a prefix.
+            const name = escapeRegexLiteral(pattern.value);
+            if (matchesExactly(group.ruleSetVersion)) {
+                buckets.fullIgnoreCase.push(name);
+            }
+            else {
+                buckets.prefixIgnoreCase.push(name);
+            }
+            continue;
+        }
+        const { pattern: athenaPattern, warnings: patternWarnings } = toAthenaRegex(stripFlags(pattern.value));
+        warnings.push(...patternWarnings.map((warning) => `stripQueryParams: ${warning}`));
+        const ignoreCase = pattern.value.ignoreCase;
+        const anchoredStart = athenaPattern.startsWith("^");
+        const anchoredEnd = /(?<!\\)\$$/.test(athenaPattern);
+        const inner = athenaPattern.slice(anchoredStart ? 1 : 0, anchoredEnd ? -1 : undefined);
+        if (anchoredStart && !anchoredEnd) {
+            (ignoreCase ? buckets.prefixIgnoreCase : buckets.prefix).push(inner);
+            continue;
+        }
+        if (anchoredEnd && !anchoredStart) {
+            (ignoreCase ? buckets.suffixIgnoreCase : buckets.suffix).push(inner);
+            continue;
+        }
+        // Anchored on both sides, or on neither: both mean the whole name.
+        (ignoreCase ? buckets.fullIgnoreCase : buckets.full).push(inner);
+    }
+    return buckets;
+}
+/** The pattern without its flags — they are applied to the whole alternation. */
+function stripFlags(regExp) {
+    return new RegExp(regExp.source);
+}
+function prefixPattern(names, ignoreCase) {
+    return names.length > 0
+        ? `${ignoreCase ? "(?i)" : ""}[?&](${names.join("|")})[^&]*`
+        : null;
+}
+function suffixPattern(names, ignoreCase) {
+    return names.length > 0
+        ? `${ignoreCase ? "(?i)" : ""}[?&][^&]*(${names.join("|")})(=[^&]*)?(?=&|$)`
+        : null;
+}
+function fullPattern(names, ignoreCase) {
+    return names.length > 0
+        ? `${ignoreCase ? "(?i)" : ""}[?&](${names.join("|")})(=[^&]*)?(?=&|$)`
+        : null;
+}

package/dist/services/query-builder/sql/expression.d.ts

@@ -0,0 +1,73 @@
+import { Predicate } from "./predicate.js";
+/**
+ * A scalar SQL expression. Always build one through the functions in this
+ * module: they escape their operands, which is what keeps a config pattern
+ * containing a quote from producing broken SQL.
+ */
+export type SqlExpression = string;
+/**
+ * A string, number or boolean as a SQL literal. Quotes inside a string are
+ * doubled, so any config-provided value is safe to embed.
+ */
+export declare function literal(value: boolean | number | string): SqlExpression;
+/**
+ * A column reference, optionally qualified (`cdnclient.bot`). Rejects anything
+ * that is not an identifier, so a column name can never smuggle in SQL.
+ */
+export declare function column(name: string): SqlExpression;
+/** A function call with the given arguments, e.g. `url_extract_path(url)`. */
+export declare function call(name: string, ...args: SqlExpression[]): SqlExpression;
+/** `lower(expression)`, used to match the case-insensitive string conditions. */
+export declare function lower(expression: SqlExpression): SqlExpression;
+/** Concatenation of all expressions, parenthesised so it can be nested. */
+export declare function concat(...expressions: SqlExpression[]): SqlExpression;
+/**
+ * Wraps a hand-written expression. The caller is responsible for escaping its
+ * operands and for parenthesising anything that binds loosely.
+ */
+export declare function raw(sql: string): SqlExpression;
+/** `left = right`. */
+export declare function equals(left: SqlExpression, right: SqlExpression): Predicate;
+/** `left <> right`. */
+export declare function notEquals(left: SqlExpression, right: SqlExpression): Predicate;
+/**
+ * A placeholder for a value passed to Athena alongside the query.
+ *
+ * Placeholders are bound by position, in the order they appear in the printed
+ * SQL — so a predicate must not contain two identical comparisons over
+ * placeholders: {@link and} and {@link or} drop a duplicate operand, which
+ * would leave one value too many.
+ */
+export declare function parameter(): SqlExpression;
+/** `left >= right`. */
+export declare function greaterOrEqual(left: SqlExpression, right: SqlExpression): Predicate;
+/** `left > right`. */
+export declare function greaterThan(left: SqlExpression, right: SqlExpression): Predicate;
+/**
+ * `subject = 'value'`, ignoring case on both sides — the semantics of a string
+ * condition in a Speed Kit rule set of version 2.
+ */
+export declare function equalsIgnoreCase(subject: SqlExpression, value: string): Predicate;
+/**
+ * `subject like 'value%'` — a prefix match, which is what a string condition
+ * means in a rule set of version 1. Case is ignored by default, matching the
+ * runtime, which lower-cases both sides.
+ */
+export declare function startsWith(subject: SqlExpression, value: string, options?: {
+    ignoreCase?: boolean;
+}): Predicate;
+/** `subject between low and high`. */
+export declare function between(subject: SqlExpression, low: SqlExpression, high: SqlExpression): Predicate;
+/** `expression is null`. */
+export declare function isNull(expression: SqlExpression): Predicate;
+/** `subject not in ('a', 'b')`. */
+export declare function notInValues(subject: SqlExpression, values: readonly (number | string)[]): Predicate;
+/** `subject in ('a', 'b')`. */
+export declare function inValues(subject: SqlExpression, values: readonly (number | string)[]): Predicate;
+/**
+ * `regexp_like(subject, 'pattern')`. The pattern is expected to already be in
+ * Athena's dialect — see {@link toAthenaRegex}.
+ */
+export declare function regexpLike(subject: SqlExpression, pattern: string): Predicate;
+/** A boolean column used as a predicate on its own, e.g. `suspicious`. */
+export declare function booleanColumn(name: string): Predicate;