@speedkit/cli 4.26.0 → 4.27.1

package/dist/services/query-builder/queries/spec/queries.spec.js

@@ -0,0 +1,312 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { parseRuleSets } from "../../rules/index.js";
+import { buildParameterQuery } from "../parameter-query.js";
+import { buildPrewarmQuery } from "../prewarm-query.js";
+import { sinceDate } from "../query-model.js";
+function inputFor(config, options = {}) {
+    return {
+        app: "shop-de",
+        days: 10,
+        hosts: ["www.shop.de"],
+        ruleSets: parseRuleSets(config),
+        ...options,
+    };
+}
+const CONFIG = {
+    blacklist: [{ contentType: ["image"], pathname: [/\/media\//i] }],
+    enabledSites: [{ host: "www.shop.de", pathname: [/^\/p\//i] }],
+    ruleSetConfig: { version: 2 },
+    stripQueryParams: [{ params: ["gclid"] }],
+    whitelist: [{ host: ["www.shop.de"] }],
+};
+/** A config whose enabled scope is wide enough for a guard to survive. */
+const WIDE_CONFIG = {
+    disabledScopes: ["/checkout", "/cart"],
+    enabledSites: [{ pathname: [/^\//i] }],
+    ruleSetConfig: { version: 2 },
+};
+describe("sinceDate", () => {
+    it("should count back from the given day", () => {
+        expect(sinceDate(10, new Date("2026-09-04T08:00:00Z"))).to.equal("2026-08-25");
+    });
+    it("should keep a window of at least one day", () => {
+        expect(sinceDate(0, new Date("2026-09-04T08:00:00Z"))).to.equal("2026-09-03");
+    });
+});
+describe("the row filter of both queries", () => {
+    const queries = {
+        parameter: buildParameterQuery,
+        prewarm: buildPrewarmQuery,
+    };
+    for (const [name, build] of Object.entries(queries)) {
+        describe(name, () => {
+            it("should read the app and the window", () => {
+                const { sql } = build(inputFor(CONFIG));
+                expect(sql).to.contain("app = 'shop-de'");
+                expect(sql).to.contain(`date >= '${sinceDate(10)}'`);
+            });
+            it("should always exclude bots", () => {
+                expect(build(inputFor(CONFIG)).sql).to.contain("device <> 'Robot'");
+            });
+            it("should not filter navigations unless asked to", () => {
+                expect(build(inputFor(CONFIG)).sql).to.not.contain("navigationtype");
+            });
+            it("should keep hard navigations only when asked to", () => {
+                const { sql } = build(inputFor(CONFIG, { hardNavigationsOnly: true }));
+                expect(sql).to.contain("navigationtype in ('NAVIGATE', 'RELOAD', 'BACK_FORWARD')");
+            });
+            it("should exclude suspicious page impressions when asked to", () => {
+                const { sql } = build(inputFor(CONFIG, { excludeSuspicious: true }));
+                // Null has to count as not suspicious, or the rows vanish with it.
+                expect(sql).to.contain("not coalesce(suspicious, false)");
+                expect(sql).to.not.contain("noindex");
+            });
+            it("should exclude noindex pages when asked to", () => {
+                const { sql } = build(inputFor(CONFIG, { excludeNoindex: true }));
+                expect(sql).to.contain("not coalesce(noindex, false)");
+            });
+            it("should read the relation only through the page source", () => {
+                const { sql } = build(inputFor(CONFIG));
+                expect(sql.match(/live\.rum\.pi/g)).to.have.lengthOf(1);
+                expect(sql).to.contain("from pages");
+            });
+            it("should leave out a rule that cannot apply to a document", () => {
+                const { dropped, sql } = build(inputFor(CONFIG));
+                expect(sql).to.not.contain("/media/");
+                expect(dropped.map(({ source }) => source)).to.contain("blacklist[0]");
+            });
+            it("should exclude the pages a disabled scope claims", () => {
+                // The service worker never runs there, so Speed Kit never sees them.
+                const { sql } = build(inputFor(WIDE_CONFIG));
+                expect(sql).to.contain("regexp_like(path, '^/checkout')");
+                expect(sql).to.contain("regexp_like(path, '^/cart')");
+            });
+            it("should reduce away a scope no enabled page can reach", () => {
+                const { reduced, sql } = build(inputFor({
+                    ...WIDE_CONFIG,
+                    enabledSites: [{ pathname: [/^\/p\//i] }],
+                }));
+                expect(sql).to.not.contain("checkout");
+                expect(reduced.map(({ source }) => source)).to.contain("disabledScopes[0]");
+            });
+            it("should project only the subjects the rules use", () => {
+                const { sql } = build(inputFor(CONFIG));
+                expect(sql).to.contain("as host");
+                expect(sql).to.contain("as path");
+                expect(sql).to.not.contain("as pathWithSearch");
+                expect(sql).to.not.contain("as matchUrl");
+            });
+        });
+    }
+});
+describe("buildPrewarmQuery", () => {
+    it("should group the stripped urls by request count", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG));
+        expect(sql).to.contain("select url, count(*) as hits");
+        expect(sql).to.contain("group by url");
+        expect(sql).to.contain("order by hits desc");
+    });
+    it("should keep the whole list unless asked to cut it", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG));
+        expect(sql).to.not.contain("having");
+        expect(sql).to.not.contain("limit");
+    });
+    it("should drop urls below the hit threshold", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { minHits: 5 }));
+        expect(sql).to.contain("having count(*) >= 5");
+    });
+    it("should keep only the most requested urls when limited", () => {
+        expect(buildPrewarmQuery(inputFor(CONFIG, { limit: 5000 })).sql).to.contain("limit 5000");
+    });
+    it("should drop urls the origin mostly answers with a 404", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { excludeNotFound: true }));
+        expect(sql).to.contain("responsecause");
+        expect(sql).to.contain("2 * count_if(responsecause = 'OriginStatusNotFound') < count(*)");
+    });
+    it("should not read the response cause unless it filters on it", () => {
+        expect(buildPrewarmQuery(inputFor(CONFIG)).sql).to.not.contain("responsecause");
+    });
+    it("should not carry createdat through the prewarm query", () => {
+        // Only the parameter query picks example urls by creation time.
+        expect(buildPrewarmQuery(inputFor(CONFIG)).sql).to.not.contain("createdat");
+    });
+    it("should strip the configured parameters from the url", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG));
+        expect(sql).to.contain("(?i)[?&](gclid)(=[^&]*)?(?=&|$)");
+    });
+});
+describe("the --device split", () => {
+    const DEVICES = inputFor(CONFIG, { devices: ["desktop", "mobile"] });
+    it("should read the device classes asked for, and no other", () => {
+        const { sql } = buildPrewarmQuery(DEVICES);
+        expect(sql).to.contain("device in ('Desktop', 'Mobile')");
+        // Naming them subsumes the bot exclusion.
+        expect(sql).to.not.contain("device <> 'Robot'");
+        expect(sql).to.not.contain("'Tablet'");
+    });
+    it("should carry the device as the variation of the row", () => {
+        expect(buildPrewarmQuery(DEVICES).sql).to.contain("lower(device) as variation");
+    });
+    it("should count the pairs and rank them by their own hits", () => {
+        const { sql } = buildPrewarmQuery(DEVICES);
+        expect(sql).to.contain("select impressions.url, impressions.variation, count(*) as hits");
+        expect(sql).to.contain("join urls on urls.url = impressions.url");
+        expect(sql).to.contain("group by 1, 2");
+        expect(sql).to.contain("order by 3 desc");
+    });
+    it("should still limit urls rather than rows", () => {
+        // The limit belongs to the relation that has one row per url, so
+        // `--limit 5000` is 5000 pages, not 5000 pre-warm requests.
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { devices: ["desktop"], limit: 5000, minHits: 5 }));
+        expect(sql).to.contain("urls as (\n  select url, count(*) as hits\n  from impressions\n  group by url\n  having count(*) >= 5\n  order by hits desc\n  limit 5000\n)");
+    });
+    it("should ignore the order the devices were given in", () => {
+        expect(buildPrewarmQuery(inputFor(CONFIG, { devices: ["mobile", "desktop"] }))
+            .sql).to.equal(buildPrewarmQuery(DEVICES).sql);
+    });
+    it("should not read the device unless it splits by it", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG));
+        expect(sql).to.not.contain("as variation");
+        expect(sql).to.not.contain("impressions");
+    });
+});
+describe("the --variation pairing", () => {
+    const VARIATIONS = inputFor(CONFIG, { variations: ["men", "women"] });
+    it("should pair every url with every variation", () => {
+        const { sql } = buildPrewarmQuery(VARIATIONS);
+        expect(sql).to.contain("cross join unnest(array['men', 'women']) as t (variation)");
+        expect(sql).to.contain("select urls.url, variation, urls.hits");
+        expect(sql).to.contain("order by urls.hits desc, variation");
+    });
+    it("should not pretend the traffic knows the variation", () => {
+        const { sql } = buildPrewarmQuery(VARIATIONS);
+        expect(sql).to.contain("device <> 'Robot'");
+        expect(sql).to.not.contain("lower(device)");
+    });
+    it("should quote a variation that carries a quote", () => {
+        expect(buildPrewarmQuery(inputFor(CONFIG, { variations: ["it's"] })).sql).to.contain("array['it''s']");
+    });
+});
+describe("the --count report", () => {
+    it("should count the urls and the traffic they stand for", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { count: true }));
+        expect(sql).to.contain("select count(*) as urls, sum(hits) as impressions\nfrom urls");
+        expect(sql).to.not.contain("select url, count(*) as hits\nfrom");
+    });
+    it("should count the list every other option leaves", () => {
+        // Nothing about counting relaxes a cut: the number is the size of the
+        // list the same flags would produce, limit included.
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { count: true, limit: 5000, minHits: 5 }));
+        expect(sql).to.contain("urls as (\n  select url, count(*) as hits\n  from impressions\n  group by url\n  having count(*) >= 5\n  order by hits desc\n  limit 5000\n)");
+    });
+    it("should count a split list per variation, plus a total", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { count: true, devices: ["desktop", "mobile"] }));
+        // Over the pairs, so the total is what the pre-warmer would request —
+        // every url once per device class it was seen in.
+        expect(sql).to.contain("pairs as (");
+        expect(sql).to.contain("select coalesce(pairs.variation, 'total') as variation, count(*) as urls, sum(hits) as impressions");
+        expect(sql).to.contain("group by rollup(pairs.variation)");
+        // Qualified: an unqualified argument would resolve to the output alias of
+        // the same name, which Athena rejects in a grouping() expression.
+        expect(sql).to.contain("order by grouping(pairs.variation) desc, 2 desc");
+    });
+    it("should count custom variations as a product", () => {
+        // Every url carries every one of them, so a row per variation would be
+        // the same number written out three times.
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { count: true, variations: ["men", "women", "kids"] }));
+        expect(sql).to.contain("select count(*) as urls, 3 * count(*) as requests, sum(hits) as impressions");
+        expect(sql).to.not.contain("cross join unnest");
+    });
+    it("should leave the list itself alone", () => {
+        const options = { devices: ["desktop"], limit: 10, minHits: 2 };
+        const list = buildPrewarmQuery(inputFor(CONFIG, options)).sql;
+        const count = buildPrewarmQuery(inputFor(CONFIG, { ...options, count: true })).sql;
+        // Same relations, different projection: everything up to the final select
+        // is what the list is built from.
+        expect(count).to.contain(list.slice(0, list.indexOf("\n\nselect")));
+    });
+});
+describe("the --match narrowing", () => {
+    it("should filter on the path and its query string", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { match: ["^/p/"] }));
+        // A version 1 pathname condition, whatever version the config runs under.
+        expect(sql).to.contain("as pathWithSearch");
+        expect(sql).to.contain("regexp_like(pathWithSearch, '^/p/')");
+    });
+    it("should reach a query parameter", () => {
+        expect(buildPrewarmQuery(inputFor(CONFIG, { match: ["[?&]size="] })).sql).to.contain("regexp_like(pathWithSearch, '[?&]size=')");
+    });
+    it("should keep the pages matching any of several patterns", () => {
+        const { sql } = buildPrewarmQuery(inputFor(CONFIG, { match: ["^/p/", "^/c/"] }));
+        expect(sql).to.contain("(\n      regexp_like(pathWithSearch, '^/p/')\n      or regexp_like(pathWithSearch, '^/c/')\n    )");
+    });
+    it("should carry inline flags over to Athena", () => {
+        // `new RegExp('(?i)…')` throws, so the flag is lifted out and put back.
+        expect(buildPrewarmQuery(inputFor(CONFIG, { match: ["(?i)^/P/"] })).sql).to.contain("regexp_like(pathWithSearch, '(?i)^/P/')");
+    });
+    it("should not project the subject when nothing matches on it", () => {
+        expect(buildPrewarmQuery(inputFor(CONFIG)).sql).to.not.contain("pathWithSearch");
+    });
+    it("should refuse a pattern the config excludes again", () => {
+        // The scope is disabled, so nothing under it is ever served by Speed Kit.
+        expect(() => buildPrewarmQuery(inputFor(WIDE_CONFIG, { match: ["^/checkout/thanks"] }))).to.throw(/--match is completely excluded again by disabledScopes/);
+    });
+    it("should restate a version 2 guard over the query string", () => {
+        // The guard is matched against the path, the pattern against path and
+        // query string; without the restatement the two are never compared.
+        const config = {
+            disabledSites: [{ pathname: [/^\/checkout$/] }],
+            enabledSites: [{ pathname: [/^\//] }],
+            ruleSetConfig: { version: 2 },
+        };
+        expect(() => buildPrewarmQuery(inputFor(config, { match: ["^/checkout\\?step="] }))).to.throw(/--match is completely excluded again by disabledSites/);
+    });
+    it("should not refuse a pattern the config only partly excludes", () => {
+        expect(() => buildPrewarmQuery(inputFor(WIDE_CONFIG, { match: ["^/"] }))).to.not.throw();
+    });
+    it("should not refuse a pattern an unanchored guard seems to cover", () => {
+        // /checkout/ says nothing about where in the path it sits, so it cannot
+        // be restated over the query string and takes part in no comparison.
+        const config = {
+            disabledSites: [{ pathname: [/checkout/] }],
+            enabledSites: [{ pathname: [/^\//] }],
+            ruleSetConfig: { version: 2 },
+        };
+        expect(() => buildPrewarmQuery(inputFor(config, { match: ["^/checkout/"] }))).to.not.throw();
+    });
+});
+describe("buildParameterQuery", () => {
+    it("should keep a parameter the config does not strip", () => {
+        const { sql } = buildParameterQuery(inputFor(CONFIG));
+        expect(sql).to.contain("(key) -> not (lower(key) = 'gclid')");
+    });
+    it("should count only urls that carry a query string", () => {
+        expect(buildParameterQuery(inputFor(CONFIG)).sql).to.contain("cardinality(split(url, '?')) > 1");
+    });
+    it("should build the cache key from the parameters it keeps", () => {
+        const { sql } = buildParameterQuery(inputFor(CONFIG));
+        expect(sql).to.contain("path || '?' || array_join(pairs, '&') as cacheKey");
+        expect(sql).to.contain("count(distinct cacheKey) as cachedUrls");
+    });
+    it("should sort and deduplicate the parameters of a url", () => {
+        // Speed Kit sorts the query string, so `?b=1&a=1` and `?a=1&b=1` are one
+        // cache key — and one group, not two.
+        expect(buildParameterQuery(inputFor(CONFIG)).sql).to.contain("array_sort(\n        array_distinct(");
+    });
+    it("should rank one row per parameter", () => {
+        const { sql } = buildParameterQuery(inputFor(CONFIG));
+        expect(sql).to.contain("group by parameter");
+        expect(sql).to.contain("count(distinct value) as distinctValues");
+        expect(sql).to.contain("count(distinct cacheKey) - count(distinct cacheKeyWithout) as potentialGain");
+    });
+    it("should rank whole sets when asked to", () => {
+        const { sql } = buildParameterQuery(inputFor(CONFIG, { bySet: true }));
+        expect(sql).to.contain("group by pairs");
+        expect(sql).to.contain("as paramKeys");
+        expect(sql).to.not.contain("group by parameter");
+    });
+    it("should leave out parameters below the impression threshold", () => {
+        expect(buildParameterQuery(inputFor(CONFIG, { minImpressions: 30 })).sql).to.contain("having count(*) >= 30");
+    });
+});

package/dist/services/query-builder/queries/spec/reported-bugs.spec.d.ts

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

package/dist/services/query-builder/queries/spec/reported-bugs.spec.js

@@ -0,0 +1,86 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { parseRuleSets } from "../../rules/index.js";
+import { buildParameterQuery } from "../parameter-query.js";
+import { buildPrewarmQuery } from "../prewarm-query.js";
+/**
+ * The bugs that prompted the rework, each with the config that reported it.
+ *
+ * A golden query shows the whole output; these name the defect, so a
+ * regression fails with the ticket it belongs to rather than as an
+ * unexplained diff.
+ */
+function inputFor(config, hosts) {
+    return {
+        app: "shop",
+        days: 30,
+        hosts,
+        now: new Date("2026-09-04T09:30:00Z"),
+        ruleSets: parseRuleSets(config),
+    };
+}
+describe("ED-277: a query from whitelisted pathnames", () => {
+    // The whitelist carried the page scope, and only its host was ever read, so
+    // the pathnames never reached the query.
+    const config = {
+        whitelist: [
+            {
+                contentType: ["navigate"],
+                host: ["www.hugendubel.de"],
+                pathname: [/\/de$/, /\/category/, /\.html/],
+            },
+        ],
+    };
+    const { sql } = buildPrewarmQuery(inputFor(config, ["www.hugendubel.de"]));
+    it("should filter on the whitelisted host", () => {
+        expect(sql).to.contain("lower(host) like 'www.hugendubel.de%'");
+    });
+    it("should filter on every whitelisted pathname", () => {
+        expect(sql).to.contain(String.raw `regexp_like(pathWithSearch, '/de$')`);
+        expect(sql).to.contain(String.raw `regexp_like(pathWithSearch, '/category')`);
+        expect(sql).to.contain(String.raw `regexp_like(pathWithSearch, '\.html')`);
+    });
+    it("should or the pathnames and and them with the host", () => {
+        const clause = sql.slice(sql.indexOf("  where lower(host)"));
+        expect(clause).to.match(/where lower\(host\) like[^\n]*\n {4}and \(/);
+        expect(clause).to.contain("\n      or regexp_like(pathWithSearch");
+    });
+    it("should match the pathname the way the rule set version does", () => {
+        // No ruleSetConfig means version 1, where the runtime tests a pathname
+        // against `pathname + search` — not against the path alone.
+        expect(sql).to.not.contain("regexp_like(path,");
+    });
+});
+describe("ED-408: a pathname-scoped stripQueryParams rule", () => {
+    // `params: /.*/` was applied to every key of every page, so no key ever
+    // survived the filter and the analysis came back empty.
+    const config = {
+        ruleSetConfig: { version: 2 },
+        stripQueryParams: [
+            { params: /.*/, rules: [{ pathname: "/hoteldetail/" }] },
+            { params: ["_ga"] },
+        ],
+        whitelist: [{ host: ["www.alltours.de"] }],
+    };
+    const { sql } = buildParameterQuery(inputFor(config, ["www.alltours.de"]));
+    it("should reject a key only on the scoped pathname", () => {
+        expect(sql).to.contain([
+            "(key) -> not (",
+            "          lower(path) = '/hoteldetail/'",
+            "          and regexp_like(key, '.*')",
+            "        )",
+        ].join("\n"));
+    });
+    it("should keep rejecting the unscoped parameters everywhere", () => {
+        expect(sql).to.contain("and not (lower(key) = '_ga')");
+    });
+    it("should scope the cache key the same way", () => {
+        // The cache key is built from the parameters that survive the very same
+        // filter, so the scope cannot apply to one and not the other.
+        expect(sql).to.contain("filter(pairs, (pair) -> contains(keptKeys, split(pair, '=')[1]))");
+        expect(sql).to.contain("path || '?' || array_join(pairs, '&') as cacheKey");
+    });
+    it("should never strip every parameter unconditionally", () => {
+        expect(sql).to.not.contain("(key) -> not regexp_like(key, '.*')");
+    });
+});

package/dist/services/query-builder/query-builder-factory.d.ts

@@ -1,11 +1,11 @@
 import { QueryBuilderService } from "./query-builder-service.js";
-import { QueryBuilderFactoryContext, QueryTpe } from "./query-builder-model.js";
+import { QueryBuilderFactoryContext, QueryType } from "./query-builder-model.js";
 import { UserCliConfig } from "../../helpers/cli-config.js";
 export declare class QueryBuilderFactory {
     private context;
     private userConfig;
     constructor(context: QueryBuilderFactoryContext, userConfig: UserCliConfig);
-    buildService(queryType: QueryTpe): Promise<QueryBuilderService>;
+    buildService(queryType: QueryType): Promise<QueryBuilderService>;
     private getIntegrationFiles;
     private getSpeedKitConfig;
 }

package/dist/services/query-builder/query-builder-factory.js

@@ -1,4 +1,5 @@
 import { QueryBuilderService } from "./query-builder-service.js";
+import { parseRuleSets } from "./rules/index.js";
 import { IntegrationApiContext, IntegrationApiFactory, } from "../integration-api/index.js";
 import { INTEGRATION_FILES } from "../../models/files.js";
 import { CliServiceFactory } from "../cli/index.js";
@@ -18,21 +19,37 @@ export class QueryBuilderFactory {
         const files = await this.getIntegrationFiles();
         const customerConfig = files.getCustomerConfig().config;
         const app = customerConfig.app;
-        const origin = customerConfig.origins[0];
+        const origins = customerConfig.origins ?? [];
         const speedKitConfigFile = files.getByName(INTEGRATION_FILES.CONFIG.SPEED_KIT);
-        const speedKitConfig = await this.getSpeedKitConfig(app, origin, speedKitConfigFile);
+        const speedKitConfig = await this.getSpeedKitConfig(app, origins[0], speedKitConfigFile);
         const serviceContext = {
             app,
-            queryType,
+            bySet: this.context.bySet,
+            count: this.context.count,
+            days: this.context.days,
+            devices: this.context.devices,
+            excludeNotFound: this.context.excludeNotFound,
+            excludeNoindex: this.context.excludeNoindex,
+            excludeSuspicious: this.context.excludeSuspicious,
+            execute: this.context.execute,
+            explain: this.context.explain,
+            hardNavigationsOnly: this.context.hardNavigationsOnly,
+            hosts: toHosts(origins),
             isWindows: this.context.isWindows,
+            limit: this.context.limit,
+            match: this.context.match,
+            minHits: this.context.minHits,
+            minImpressions: this.context.minImpressions,
+            queryType,
             quiet: this.context.quiet,
-            execute: this.context.execute,
+            variations: this.context.variations,
         };
-        // The Athena service is only needed when the query is executed directly.
-        const athenaService = this.context.execute
-            ? await new AthenaServiceFactory(app).getService()
+        // The Athena service is only needed when the query is executed directly —
+        // which `--count` is, a count query being of no use as text.
+        const athenaService = this.context.execute || this.context.count
+            ? await new AthenaServiceFactory(app, this.context.workgroup).getService()
             : undefined;
-        return new QueryBuilderService(serviceContext, speedKitConfig, cli, athenaService);
+        return new QueryBuilderService(serviceContext, parseRuleSets(speedKitConfig), cli, athenaService);
     }
     async getIntegrationFiles() {
         const integrationApiContext = new IntegrationApiContext(this.context.customerPath, this.context.configName, ["config_SpeedKit"]);
@@ -49,3 +66,14 @@ export class QueryBuilderFactory {
         return result.data;
     }
 }
+/** The host of every origin, ignoring the ones that are not a URL. */
+function toHosts(origins) {
+    const hosts = [];
+    for (const origin of origins) {
+        const result = safe(() => new URL(origin).host);
+        if (result.success === true) {
+            hosts.push(result.data);
+        }
+    }
+    return hosts;
+}

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

@@ -1,24 +1,38 @@
-export interface QueryBuilderContext {
-    isWindows?: boolean;
-    quiet?: boolean;
-    execute?: boolean;
-    queryType: QueryTpe;
-    app: string;
+import { ParameterOptions, PrewarmOptions } from "./queries/query-model.js";
+export declare enum QueryType {
+    parameter = "parameter",
+    prewarm = "prewarm"
 }
-export interface QueryBuilderFactoryContext {
-    readonly customerPath: string;
-    readonly configName: string;
+/** Options that narrow the rows a query looks at. */
+export interface QueryFilterOptions {
+    /** Size of the window the query looks at, in days. */
+    readonly days?: number;
+    /** Drop page impressions of pages marked `noindex`. */
+    readonly excludeNoindex?: boolean;
+    /** Drop page impressions Speed Kit classified as suspicious. */
+    readonly excludeSuspicious?: boolean;
+    /** Keep hard navigations only, dropping soft (SPA) navigations. */
+    readonly hardNavigationsOnly?: boolean;
+}
+export interface QueryBuilderContext extends ParameterOptions, PrewarmOptions, QueryFilterOptions {
+    readonly app: string;
+    readonly execute?: boolean;
+    /** Report every rule the query leaves out, reduces or approximates. */
+    readonly explain?: boolean;
+    /** Hosts of the app's origins. */
+    readonly hosts?: readonly string[];
     readonly isWindows?: boolean;
+    readonly queryType: QueryType;
     readonly quiet?: boolean;
-    readonly execute?: boolean;
-}
-export declare enum QueryTpe {
-    prewarm = "prewarm",
-    parameter = "parameter"
 }
-export interface SpeedKitConfig {
-    ruleSetConfig?: {
-        version?: string;
-    };
-    [key: string]: any;
+export interface QueryBuilderFactoryContext extends ParameterOptions, PrewarmOptions, QueryFilterOptions {
+    readonly configName: string;
+    readonly customerPath: string;
+    readonly execute?: boolean;
+    /** Report every rule the query leaves out, reduces or approximates. */
+    readonly explain?: boolean;
+    readonly isWindows?: boolean;
+    readonly quiet?: boolean;
+    /** Athena workgroup to execute in, when the query is executed at all. */
+    readonly workgroup?: string;
 }

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

@@ -1,5 +1,5 @@
-export var QueryTpe;
-(function (QueryTpe) {
-    QueryTpe["prewarm"] = "prewarm";
-    QueryTpe["parameter"] = "parameter";
-})(QueryTpe || (QueryTpe = {}));
+export var QueryType;
+(function (QueryType) {
+    QueryType["parameter"] = "parameter";
+    QueryType["prewarm"] = "prewarm";
+})(QueryType || (QueryType = {}));

package/dist/services/query-builder/query-builder-service.d.ts

@@ -1,12 +1,13 @@
-import { QueryBuilderContext, SpeedKitConfig } from "./query-builder-model.js";
+import { QueryBuilderContext } from "./query-builder-model.js";
+import { ParsedRuleSets } from "./rules/index.js";
 import { CliServiceInterface } from "../cli/index.js";
 import { AthenaService } from "../athena/index.js";
 export declare class QueryBuilderService {
     private context;
-    private speedKitConfig;
+    private ruleSets;
     private cli;
     private athenaService?;
-    constructor(context: QueryBuilderContext, speedKitConfig: SpeedKitConfig, cli: CliServiceInterface, athenaService?: AthenaService);
+    constructor(context: QueryBuilderContext, ruleSets: ParsedRuleSets, cli: CliServiceInterface, athenaService?: AthenaService);
     /** The app the query targets, as read from the customer config. */
     get app(): string;
     run(): Promise<void>;
@@ -16,13 +17,33 @@ export declare class QueryBuilderService {
      * directly instead of exporting it (e.g. `auto-prewarm`).
      */
     execute<T>(): Promise<T[]>;
+    /** The query as SQL. */
+    query(): string;
+    private build;
+    /**
+     * Points out where the query is not exactly what the config says — a rule
+     * left out, a rule the query can only approximate, a pattern Athena reads
+     * differently than the browser — plus what the config itself gets wrong.
+     *
+     * Reductions are silent unless asked for: a rule another rule already
+     * decides is not a divergence, it is arithmetic.
+     */
+    private report;
+    /** The same accounting as {@link report}, as plain lines. */
+    private reportLines;
     private runQuery;
+    /**
+     * Execute the count query and put its handful of rows on the terminal — a
+     * count is read, not filed, so nothing is written to disk.
+     *
+     * Under `--quiet` the rows go to stdout as tab separated values, so a count
+     * can be read by something other than a person.
+     */
+    private executeAndReportCounts;
     /**
      * Execute the built query against Athena (Baqend native path, AWS fallback)
      * and write the rows to a `<app>-<YYYY-MM-DD>-<queryType>.csv` file in the
      * current working directory.
      */
     private executeAndExport;
-    query(): string;
-    private buildQuery;
 }