@speedkit/cli 4.26.0 → 4.27.1

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;

package/dist/services/query-builder/sql/expression.js

@@ -0,0 +1,133 @@
+import { leaf } from "./predicate.js";
+const IDENTIFIER = /^[a-z_][\w$]*(\.[a-z_][\w$]*)*$/i;
+/** Characters that carry a meaning inside a `like` pattern. */
+const LIKE_METACHARACTERS = /[%_\\]/;
+/**
+ * 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 function literal(value) {
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error(`Cannot use ${value} as a SQL literal`);
+        }
+        return String(value);
+    }
+    return `'${value.replaceAll("'", "''")}'`;
+}
+/**
+ * A column reference, optionally qualified (`cdnclient.bot`). Rejects anything
+ * that is not an identifier, so a column name can never smuggle in SQL.
+ */
+export function column(name) {
+    if (!IDENTIFIER.test(name)) {
+        throw new Error(`Not a valid column name: ${name}`);
+    }
+    return name;
+}
+/** A function call with the given arguments, e.g. `url_extract_path(url)`. */
+export function call(name, ...args) {
+    if (!IDENTIFIER.test(name)) {
+        throw new Error(`Not a valid function name: ${name}`);
+    }
+    return `${name}(${args.join(", ")})`;
+}
+/** `lower(expression)`, used to match the case-insensitive string conditions. */
+export function lower(expression) {
+    return call("lower", expression);
+}
+/** Concatenation of all expressions, parenthesised so it can be nested. */
+export function concat(...expressions) {
+    return `(${expressions.join(" || ")})`;
+}
+/**
+ * Wraps a hand-written expression. The caller is responsible for escaping its
+ * operands and for parenthesising anything that binds loosely.
+ */
+export function raw(sql) {
+    return sql;
+}
+/** `left = right`. */
+export function equals(left, right) {
+    return leaf(`${left} = ${right}`);
+}
+/** `left <> right`. */
+export function notEquals(left, right) {
+    return leaf(`${left} <> ${right}`);
+}
+/**
+ * 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 function parameter() {
+    return "?";
+}
+/** `left >= right`. */
+export function greaterOrEqual(left, right) {
+    return leaf(`${left} >= ${right}`);
+}
+/** `left > right`. */
+export function greaterThan(left, right) {
+    return leaf(`${left} > ${right}`);
+}
+/**
+ * `subject = 'value'`, ignoring case on both sides — the semantics of a string
+ * condition in a Speed Kit rule set of version 2.
+ */
+export function equalsIgnoreCase(subject, value) {
+    return equals(lower(subject), literal(value.toLowerCase()));
+}
+/**
+ * `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 function startsWith(subject, value, options = {}) {
+    const ignoreCase = options.ignoreCase ?? true;
+    const prefix = ignoreCase ? value.toLowerCase() : value;
+    const left = ignoreCase ? lower(subject) : subject;
+    if (!LIKE_METACHARACTERS.test(prefix)) {
+        return leaf(`${left} like ${literal(`${prefix}%`)}`);
+    }
+    // `like` has no escape character unless one is declared, so a value
+    // containing `%`, `_` or `\` needs both the escaping and the declaration.
+    const escaped = prefix.replaceAll(/[%_\\]/g, (match) => `\\${match}`);
+    return leaf(`${left} like ${literal(`${escaped}%`)} escape '\\'`);
+}
+/** `subject between low and high`. */
+export function between(subject, low, high) {
+    return leaf(`${subject} between ${low} and ${high}`);
+}
+/** `expression is null`. */
+export function isNull(expression) {
+    return leaf(`${expression} is null`);
+}
+/** `subject not in ('a', 'b')`. */
+export function notInValues(subject, values) {
+    return leaf(`${subject} not in (${valueList(values)})`);
+}
+/** `subject in ('a', 'b')`. */
+export function inValues(subject, values) {
+    return leaf(`${subject} in (${valueList(values)})`);
+}
+function valueList(values) {
+    return values.map((value) => literal(value)).join(", ");
+}
+/**
+ * `regexp_like(subject, 'pattern')`. The pattern is expected to already be in
+ * Athena's dialect — see {@link toAthenaRegex}.
+ */
+export function regexpLike(subject, pattern) {
+    return leaf(call("regexp_like", subject, literal(pattern)), true);
+}
+/** A boolean column used as a predicate on its own, e.g. `suspicious`. */
+export function booleanColumn(name) {
+    return leaf(column(name), true);
+}

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

@@ -0,0 +1,14 @@
+import { Predicate } from "./predicate.js";
+export interface FormatPredicateOptions {
+    /**
+     * Indentation level the predicate starts at. The first line is *not*
+     * indented — the caller has already positioned it (e.g. after `where `) —
+     * every following line is.
+     */
+    readonly level?: number;
+}
+/**
+ * Renders a predicate as SQL that a human can read in the Athena console: one
+ * operand per line, the operator leading the line, nested groups indented.
+ */
+export declare function formatPredicate(predicate: Predicate, options?: FormatPredicateOptions): string;

package/dist/services/query-builder/sql/format.js

@@ -0,0 +1,48 @@
+/** Two spaces per level, matching the indentation of the emitted queries. */
+const INDENT = "  ";
+/**
+ * Renders a predicate as SQL that a human can read in the Athena console: one
+ * operand per line, the operator leading the line, nested groups indented.
+ */
+export function formatPredicate(predicate, options = {}) {
+    return print(predicate, options.level ?? 0);
+}
+function print(predicate, level) {
+    switch (predicate.kind) {
+        case "and":
+        case "or": {
+            const separator = `\n${INDENT.repeat(level)}${predicate.kind} `;
+            return predicate.children
+                .map((child) => printOperand(child, level, false))
+                .join(separator);
+        }
+        case "false": {
+            return "false";
+        }
+        case "leaf": {
+            return predicate.sql;
+        }
+        case "not": {
+            return `not ${printOperand(predicate.child, level, true)}`;
+        }
+        case "true": {
+            return "true";
+        }
+    }
+}
+/**
+ * Prints an operand of `and`, `or` or `not`. Groups get parentheses and their
+ * own indentation level. A leaf goes inline; a negated comparison is
+ * parenthesised, because `not` binding looser than `=` is a detail a reader
+ * should not have to remember.
+ */
+function printOperand(predicate, level, negated) {
+    if (predicate.kind === "leaf") {
+        return negated && !predicate.atomic ? `(${predicate.sql})` : predicate.sql;
+    }
+    if (predicate.kind !== "and" && predicate.kind !== "or") {
+        return print(predicate, level);
+    }
+    const inner = INDENT.repeat(level + 1);
+    return `(\n${inner}${print(predicate, level + 1)}\n${INDENT.repeat(level)})`;
+}

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

@@ -0,0 +1,4 @@
+export * from "./expression.js";
+export * from "./format.js";
+export * from "./predicate.js";
+export * from "./regex.js";

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

@@ -0,0 +1,4 @@
+export * from "./expression.js";
+export * from "./format.js";
+export * from "./predicate.js";
+export * from "./regex.js";