@speedkit/cli 4.26.0 → 4.27.1

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

@@ -0,0 +1,66 @@
+/**
+ * A boolean SQL expression represented as a small tree instead of a string.
+ *
+ * The queries this builder emits are assembled from Speed Kit rules, and rules
+ * cancel each other out: a blacklist entry that can never match, an
+ * `enabledSites` rule already covered by another one. Folding those away is
+ * only possible while the predicate is still structured, which is what this
+ * type is for. {@link formatPredicate} turns it back into SQL.
+ *
+ * Leaves carry raw SQL. A leaf that is a single column or function call is
+ * atomic and needs no parentheses; a comparison is not, and gets them when it
+ * is negated. A leaf built by hand from a low-precedence expression (`a or b`)
+ * must bring its own.
+ */
+export type Predicate = {
+    readonly children: readonly Predicate[];
+    readonly kind: "and" | "or";
+} | {
+    readonly child: Predicate;
+    readonly kind: "not";
+} | {
+    readonly kind: "false";
+} | {
+    readonly atomic?: boolean;
+    readonly kind: "leaf";
+    readonly sql: string;
+} | {
+    readonly kind: "true";
+};
+/** The always-true predicate. Neutral in `and`, absorbing in `or`. */
+export declare const TRUE: Predicate;
+/** The always-false predicate. Absorbing in `and`, neutral in `or`. */
+export declare const FALSE: Predicate;
+/**
+ * Wraps a piece of SQL as a predicate. Prefer the constructors in
+ * `expression.ts`, which escape their operands.
+ *
+ * @param atomic - True for a single column or function call, which never
+ * needs parentheses around it.
+ */
+export declare function leaf(sql: string, atomic?: boolean): Predicate;
+/**
+ * Conjunction of all given predicates, simplified:
+ * nested `and`s are flattened, `TRUE` operands drop out, a single `FALSE`
+ * operand or a pair of `x` / `not x` collapses the whole conjunction, and
+ * duplicate operands are removed. An empty conjunction is `TRUE`.
+ */
+export declare function and(...predicates: Predicate[]): Predicate;
+/**
+ * Disjunction of all given predicates, simplified the same way {@link and} is
+ * — with the roles of `TRUE` and `FALSE` swapped. An empty disjunction is
+ * `FALSE`.
+ */
+export declare function or(...predicates: Predicate[]): Predicate;
+/** Negation, collapsing `not not x`, `not TRUE` and `not FALSE`. */
+export declare function not(predicate: Predicate): Predicate;
+/** True when the predicate is known to hold for every row. */
+export declare function isTrue(predicate: Predicate): boolean;
+/** True when the predicate is known to hold for no row. */
+export declare function isFalse(predicate: Predicate): boolean;
+/**
+ * A canonical string identifying the predicate, used to recognise duplicate
+ * and contradicting operands. Operands of `and` / `or` are sorted, so the key
+ * does not depend on the order they were passed in.
+ */
+export declare function predicateKey(predicate: Predicate): string;

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

@@ -0,0 +1,124 @@
+/** The always-true predicate. Neutral in `and`, absorbing in `or`. */
+export const TRUE = { kind: "true" };
+/** The always-false predicate. Absorbing in `and`, neutral in `or`. */
+export const FALSE = { kind: "false" };
+/**
+ * Wraps a piece of SQL as a predicate. Prefer the constructors in
+ * `expression.ts`, which escape their operands.
+ *
+ * @param atomic - True for a single column or function call, which never
+ * needs parentheses around it.
+ */
+export function leaf(sql, atomic = false) {
+    return { atomic, kind: "leaf", sql };
+}
+/**
+ * Conjunction of all given predicates, simplified:
+ * nested `and`s are flattened, `TRUE` operands drop out, a single `FALSE`
+ * operand or a pair of `x` / `not x` collapses the whole conjunction, and
+ * duplicate operands are removed. An empty conjunction is `TRUE`.
+ */
+export function and(...predicates) {
+    return combine("and", predicates);
+}
+/**
+ * Disjunction of all given predicates, simplified the same way {@link and} is
+ * — with the roles of `TRUE` and `FALSE` swapped. An empty disjunction is
+ * `FALSE`.
+ */
+export function or(...predicates) {
+    return combine("or", predicates);
+}
+/** Negation, collapsing `not not x`, `not TRUE` and `not FALSE`. */
+export function not(predicate) {
+    if (predicate.kind === "true") {
+        return FALSE;
+    }
+    if (predicate.kind === "false") {
+        return TRUE;
+    }
+    if (predicate.kind === "not") {
+        return predicate.child;
+    }
+    return { child: predicate, kind: "not" };
+}
+/** True when the predicate is known to hold for every row. */
+export function isTrue(predicate) {
+    return predicate.kind === "true";
+}
+/** True when the predicate is known to hold for no row. */
+export function isFalse(predicate) {
+    return predicate.kind === "false";
+}
+/**
+ * A canonical string identifying the predicate, used to recognise duplicate
+ * and contradicting operands. Operands of `and` / `or` are sorted, so the key
+ * does not depend on the order they were passed in.
+ */
+export function predicateKey(predicate) {
+    switch (predicate.kind) {
+        case "and":
+        case "or": {
+            const keys = predicate.children.map((child) => predicateKey(child));
+            return `${predicate.kind}(${[...keys].sort().join(",")})`;
+        }
+        case "false": {
+            return "false";
+        }
+        case "leaf": {
+            return `leaf(${predicate.sql})`;
+        }
+        case "not": {
+            return `not(${predicateKey(predicate.child)})`;
+        }
+        case "true": {
+            return "true";
+        }
+    }
+}
+function combine(kind, predicates) {
+    // The operand that swallows the whole expression: `false` in a conjunction,
+    // `true` in a disjunction. The other one is neutral and can be dropped.
+    const absorbing = kind === "and" ? "false" : "true";
+    const neutral = kind === "and" ? "true" : "false";
+    const children = [];
+    const keys = new Set();
+    for (const predicate of flatten(kind, predicates)) {
+        if (predicate.kind === absorbing) {
+            return absorbing === "false" ? FALSE : TRUE;
+        }
+        if (predicate.kind === neutral) {
+            continue;
+        }
+        const key = predicateKey(predicate);
+        if (keys.has(key)) {
+            continue;
+        }
+        keys.add(key);
+        children.push(predicate);
+    }
+    // `x and not x` is never true, `x or not x` is always true.
+    for (const child of children) {
+        if (child.kind === "not" && keys.has(predicateKey(child.child))) {
+            return absorbing === "false" ? FALSE : TRUE;
+        }
+    }
+    if (children.length === 0) {
+        return neutral === "true" ? TRUE : FALSE;
+    }
+    if (children.length === 1) {
+        return children[0];
+    }
+    return { children, kind };
+}
+function flatten(kind, predicates) {
+    const flattened = [];
+    for (const predicate of predicates) {
+        if (predicate.kind === kind) {
+            flattened.push(...flatten(kind, [...predicate.children]));
+            continue;
+        }
+        flattened.push(predicate);
+    }
+    return flattened;
+}

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

@@ -0,0 +1,28 @@
+export interface AthenaRegex {
+    /** The pattern to hand to `regexp_like`, without delimiters. */
+    readonly pattern: string;
+    /**
+     * Constructs whose meaning may differ between the browser and Athena. They
+     * do not stop the translation — the filter is emitted and the warning is
+     * reported, so a reviewer can check that one rule instead of the query.
+     */
+    readonly warnings: readonly string[];
+}
+/**
+ * Translates a JavaScript regular expression from a Speed Kit config into a
+ * pattern for Athena's `regexp_like`.
+ *
+ * Athena evaluates regular expressions with Joni in its Java syntax, which
+ * agrees with JavaScript on everything these configs use — character classes,
+ * groups, quantifiers, anchors, lookahead. It differs in three ways that
+ * matter here: flags have to travel inside the pattern as an inline group,
+ * `\/` is a JavaScript-source artefact that Joni would reject, and a handful
+ * of constructs are unsupported or subtly different. The first two are fixed,
+ * the third is reported.
+ */
+export declare function toAthenaRegex(regExp: RegExp): AthenaRegex;
+/**
+ * Escapes a plain string so it can be embedded in a regular expression as a
+ * literal, e.g. a query parameter name inside an alternation.
+ */
+export declare function escapeRegexLiteral(value: string): string;

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

@@ -0,0 +1,81 @@
+/**
+ * Translates a JavaScript regular expression from a Speed Kit config into a
+ * pattern for Athena's `regexp_like`.
+ *
+ * Athena evaluates regular expressions with Joni in its Java syntax, which
+ * agrees with JavaScript on everything these configs use — character classes,
+ * groups, quantifiers, anchors, lookahead. It differs in three ways that
+ * matter here: flags have to travel inside the pattern as an inline group,
+ * `\/` is a JavaScript-source artefact that Joni would reject, and a handful
+ * of constructs are unsupported or subtly different. The first two are fixed,
+ * the third is reported.
+ */
+export function toAthenaRegex(regExp) {
+    const { pattern, warnings } = translate(regExp.source, String(regExp));
+    const flags = [
+        regExp.ignoreCase ? "i" : "",
+        regExp.multiline ? "m" : "",
+        regExp.dotAll ? "s" : "",
+    ].join("");
+    // The v flag predates the lib this project compiles against, so read it
+    // off the flag string rather than the RegExp instance.
+    if (regExp.flags.includes("v")) {
+        warnings.push(`${regExp}: the v flag has no equivalent in Athena — class set operations will not be applied`);
+    }
+    return {
+        pattern: flags ? `(?${flags})${pattern}` : pattern,
+        warnings,
+    };
+}
+/**
+ * Escapes a plain string so it can be embedded in a regular expression as a
+ * literal, e.g. a query parameter name inside an alternation.
+ */
+export function escapeRegexLiteral(value) {
+    return value.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+}
+function translate(source, label) {
+    const characters = [];
+    const warnings = new Set();
+    let inCharacterClass = false;
+    for (let index = 0; index < source.length; index++) {
+        const character = source[index];
+        if (character === "\\" && index + 1 < source.length) {
+            const escaped = source[index + 1];
+            // `\/` only exists because the pattern was written as a literal between
+            // slashes. Joni treats an unknown escape as an error, so unescape it.
+            if (escaped === "/") {
+                characters.push("/");
+                index++;
+                continue;
+            }
+            if (!inCharacterClass && /[1-9]/.test(escaped)) {
+                warnings.add(`${label}: back references are not supported by Athena`);
+            }
+            if (escaped === "k") {
+                warnings.add(`${label}: back references are not supported by Athena`);
+            }
+            if (escaped === "u" && source[index + 2] === "{") {
+                warnings.add(`${label}: code point escapes (\\u{…}) are not supported by Athena`);
+            }
+            if (escaped === "p" || escaped === "P") {
+                warnings.add(`${label}: unicode property escapes use different property names in Athena`);
+            }
+            characters.push(character, escaped);
+            index++;
+            continue;
+        }
+        if (character === "[" && !inCharacterClass) {
+            inCharacterClass = true;
+        }
+        else if (character === "]" && inCharacterClass) {
+            inCharacterClass = false;
+        }
+        else if (!inCharacterClass &&
+            (source.startsWith("(?<=", index) || source.startsWith("(?<!", index))) {
+            warnings.add(`${label}: lookbehind is only partially supported by Athena — verify this filter`);
+        }
+        characters.push(character);
+    }
+    return { pattern: characters.join(""), warnings: [...warnings] };
+}

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

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

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

@@ -0,0 +1,75 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { booleanColumn, call, column, concat, equals, equalsIgnoreCase, inValues, literal, lower, notEquals, regexpLike, startsWith, } from "../expression.js";
+import { formatPredicate } from "../format.js";
+describe("literal", () => {
+    it("should quote a string", () => {
+        expect(literal("abc")).to.equal("'abc'");
+    });
+    it("should double a quote inside a string", () => {
+        expect(literal("it's")).to.equal("'it''s'");
+    });
+    it("should print numbers and booleans unquoted", () => {
+        expect(literal(42)).to.equal("42");
+        expect(literal(true)).to.equal("true");
+    });
+    it("should reject a non-finite number", () => {
+        expect(() => literal(Number.NaN)).to.throw();
+    });
+});
+describe("column", () => {
+    it("should accept a qualified name", () => {
+        expect(column("cdnclient.bot")).to.equal("cdnclient.bot");
+    });
+    it("should reject anything that is not an identifier", () => {
+        expect(() => column("url'; drop")).to.throw();
+        expect(() => column("1url")).to.throw();
+    });
+});
+describe("call", () => {
+    it("should join the arguments", () => {
+        expect(call("url_extract_path", column("url"))).to.equal("url_extract_path(url)");
+    });
+    it("should reject an invalid function name", () => {
+        expect(() => call("drop table x --")).to.throw();
+    });
+});
+describe("expression comparisons", () => {
+    it("should build an equality", () => {
+        expect(formatPredicate(equals(column("app"), literal("shop-de")))).to.equal("app = 'shop-de'");
+    });
+    it("should build an inequality", () => {
+        expect(formatPredicate(notEquals(column("device"), literal("Robot")))).to.equal("device <> 'Robot'");
+    });
+    it("should compare case-insensitively through lower", () => {
+        expect(formatPredicate(equalsIgnoreCase(column("url"), "https://Example.com/"))).to.equal("lower(url) = 'https://example.com/'");
+    });
+    it("should build an in list", () => {
+        expect(formatPredicate(inValues(column("navigationtype"), ["NAVIGATE", "RELOAD"]))).to.equal("navigationtype in ('NAVIGATE', 'RELOAD')");
+    });
+    it("should build a regexp_like", () => {
+        expect(formatPredicate(regexpLike(column("url"), "(?i)^/products/"))).to.equal("regexp_like(url, '(?i)^/products/')");
+    });
+    it("should use a boolean column directly", () => {
+        expect(formatPredicate(booleanColumn("suspicious"))).to.equal("suspicious");
+    });
+});
+describe("startsWith", () => {
+    it("should lower-case both sides by default", () => {
+        expect(formatPredicate(startsWith(column("url"), "/Products/"))).to.equal("lower(url) like '/products/%'");
+    });
+    it("should keep the case when asked to", () => {
+        expect(formatPredicate(startsWith(column("url"), "/Products/", { ignoreCase: false }))).to.equal("url like '/Products/%'");
+    });
+    it("should escape like metacharacters and declare the escape character", () => {
+        expect(formatPredicate(startsWith(column("url"), "/a_b"))).to.equal(String.raw `lower(url) like '/a\_b%' escape '\'`);
+    });
+});
+describe("lower and concat", () => {
+    it("should wrap a concatenation in parentheses", () => {
+        expect(concat(column("a"), column("b"))).to.equal("(a || b)");
+    });
+    it("should lower an expression", () => {
+        expect(lower(column("url"))).to.equal("lower(url)");
+    });
+});

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

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

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

@@ -0,0 +1,37 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { formatPredicate } from "../format.js";
+import { and, FALSE, leaf, not, or, TRUE } from "../predicate.js";
+const a = leaf("a = 1");
+const b = leaf("b = 2");
+const c = leaf("c = 3");
+describe("formatPredicate", () => {
+    it("should print a leaf as it is", () => {
+        expect(formatPredicate(a)).to.equal("a = 1");
+    });
+    it("should print the constants", () => {
+        expect(formatPredicate(TRUE)).to.equal("true");
+        expect(formatPredicate(FALSE)).to.equal("false");
+    });
+    it("should put every operand on its own line", () => {
+        expect(formatPredicate(and(a, b))).to.equal("a = 1\nand b = 2");
+    });
+    it("should parenthesise and indent a nested group", () => {
+        expect(formatPredicate(and(a, or(b, c)))).to.equal(["a = 1", "and (", "  b = 2", "  or c = 3", ")"].join("\n"));
+    });
+    it("should indent relative to the given level", () => {
+        expect(formatPredicate(and(a, b), { level: 1 })).to.equal("a = 1\n  and b = 2");
+    });
+    it("should parenthesise a negated comparison", () => {
+        expect(formatPredicate(not(a))).to.equal("not (a = 1)");
+    });
+    it("should not parenthesise a negated call", () => {
+        expect(formatPredicate(not(leaf("suspicious", true)))).to.equal("not suspicious");
+    });
+    it("should not parenthesise a comparison that is not negated", () => {
+        expect(formatPredicate(and(a, b))).to.equal("a = 1\nand b = 2");
+    });
+    it("should parenthesise a negated group", () => {
+        expect(formatPredicate(not(or(a, b)))).to.equal(["not (", "  a = 1", "  or b = 2", ")"].join("\n"));
+    });
+});

package/dist/services/query-builder/sql/spec/predicate.spec.d.ts

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

package/dist/services/query-builder/sql/spec/predicate.spec.js

@@ -0,0 +1,78 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { and, FALSE, isFalse, isTrue, leaf, not, or, predicateKey, TRUE, } from "../predicate.js";
+const a = leaf("a");
+const b = leaf("b");
+const c = leaf("c");
+describe("predicate and", () => {
+    it("should be true without operands", () => {
+        expect(isTrue(and())).to.equal(true);
+    });
+    it("should return the only operand unwrapped", () => {
+        expect(and(a)).to.deep.equal(a);
+    });
+    it("should drop true operands", () => {
+        expect(and(a, TRUE, b)).to.deep.equal({
+            children: [a, b],
+            kind: "and",
+        });
+    });
+    it("should collapse to false on a false operand", () => {
+        expect(isFalse(and(a, FALSE))).to.equal(true);
+    });
+    it("should flatten nested conjunctions", () => {
+        expect(and(a, and(b, c))).to.deep.equal({
+            children: [a, b, c],
+            kind: "and",
+        });
+    });
+    it("should remove duplicate operands", () => {
+        expect(and(a, b, leaf("a"))).to.deep.equal({
+            children: [a, b],
+            kind: "and",
+        });
+    });
+    it("should collapse to false on contradicting operands", () => {
+        expect(isFalse(and(a, b, not(leaf("a"))))).to.equal(true);
+    });
+    it("should keep a disjunction as an operand", () => {
+        expect(and(a, or(b, c))).to.deep.equal({
+            children: [a, { children: [b, c], kind: "or" }],
+            kind: "and",
+        });
+    });
+});
+describe("predicate or", () => {
+    it("should be false without operands", () => {
+        expect(isFalse(or())).to.equal(true);
+    });
+    it("should drop false operands", () => {
+        expect(or(a, FALSE, b)).to.deep.equal({
+            children: [a, b],
+            kind: "or",
+        });
+    });
+    it("should collapse to true on a true operand", () => {
+        expect(isTrue(or(a, TRUE))).to.equal(true);
+    });
+    it("should collapse to true on complementary operands", () => {
+        expect(isTrue(or(a, not(leaf("a"))))).to.equal(true);
+    });
+});
+describe("predicate not", () => {
+    it("should collapse a double negation", () => {
+        expect(not(not(a))).to.deep.equal(a);
+    });
+    it("should negate the constants", () => {
+        expect(isFalse(not(TRUE))).to.equal(true);
+        expect(isTrue(not(FALSE))).to.equal(true);
+    });
+});
+describe("predicateKey", () => {
+    it("should not depend on the operand order", () => {
+        expect(predicateKey(and(a, b))).to.equal(predicateKey(and(b, a)));
+    });
+    it("should differ between and and or", () => {
+        expect(predicateKey(and(a, b))).to.not.equal(predicateKey(or(a, b)));
+    });
+});

package/dist/services/query-builder/sql/spec/regex.spec.d.ts

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

package/dist/services/query-builder/sql/spec/regex.spec.js

@@ -0,0 +1,62 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { escapeRegexLiteral, toAthenaRegex } from "../regex.js";
+describe("toAthenaRegex", () => {
+    it("should keep a plain pattern", () => {
+        expect(toAthenaRegex(/^\/products\/\d+$/).pattern).to.equal(String.raw `^/products/\d+$`);
+    });
+    it("should move the i flag into the pattern", () => {
+        expect(toAthenaRegex(/^\/p\//i).pattern).to.equal(String.raw `(?i)^/p/`);
+    });
+    it("should combine the flags in a single group", () => {
+        expect(toAthenaRegex(/a.b/ims).pattern).to.equal("(?ims)a.b");
+    });
+    it("should ignore flags without a pattern equivalent", () => {
+        expect(toAthenaRegex(/abc/g).pattern).to.equal("abc");
+    });
+    it("should unescape a slash", () => {
+        expect(toAthenaRegex(/\/de\/shop/i).pattern).to.equal("(?i)/de/shop");
+    });
+    it("should keep an escaped backslash", () => {
+        expect(toAthenaRegex(/a\\b/).pattern).to.equal(String.raw `a\\b`);
+    });
+    it("should not warn about a pattern it fully supports", () => {
+        expect(toAthenaRegex(/^\/(shop|store)\/[a-z-]+$/i).warnings).to.deep.equal([]);
+    });
+    it("should keep lookahead without a warning", () => {
+        const { pattern, warnings } = toAthenaRegex(/^[^?]*\/(\?|$)/i);
+        expect(pattern).to.equal(String.raw `(?i)^[^?]*/(\?|$)`);
+        expect(warnings).to.deep.equal([]);
+    });
+    it("should warn about lookbehind", () => {
+        const { warnings } = toAthenaRegex(/(?<=\/de)\/shop/i);
+        expect(warnings).to.have.lengthOf(1);
+        expect(warnings[0]).to.contain("lookbehind");
+    });
+    it("should warn about a back reference", () => {
+        const { warnings } = toAthenaRegex(/(a)\1/);
+        expect(warnings).to.have.lengthOf(1);
+        expect(warnings[0]).to.contain("back reference");
+    });
+    it("should not read a back reference inside a character class", () => {
+        // Written through the constructor because TypeScript rejects the literal.
+        const inClass = new RegExp(String.raw `[\1]`);
+        expect(toAthenaRegex(inClass).warnings).to.deep.equal([]);
+    });
+    it("should warn about a unicode property escape", () => {
+        const { warnings } = toAthenaRegex(/\p{Letter}/u);
+        expect(warnings).to.have.lengthOf(1);
+        expect(warnings[0]).to.contain("unicode property");
+    });
+    it("should report each construct once", () => {
+        expect(toAthenaRegex(/(a)\1(b)\2/).warnings).to.have.lengthOf(1);
+    });
+});
+describe("escapeRegexLiteral", () => {
+    it("should escape the regex metacharacters", () => {
+        expect(escapeRegexLiteral("utm_source?")).to.equal(String.raw `utm_source\?`);
+    });
+    it("should leave a plain parameter name alone", () => {
+        expect(escapeRegexLiteral("gclid")).to.equal("gclid");
+    });
+});