@speedkit/cli 4.25.2 → 4.27.0

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

@@ -0,0 +1,142 @@
+import { and, call, column, formatPredicate, greaterThan, literal, raw, } from "../sql/index.js";
+import { notStrippedParameter, prepareStripParameters, } from "../rules/index.js";
+import { buildRuleFilter } from "./page-filter.js";
+import { buildPageSource, PAGE_SOURCE } from "./page-source.js";
+/**
+ * How many urls to keep per group to pick the examples from. The sample is
+ * ordered by a hash of the creation time, so it is arbitrary but stable, and
+ * three distinct urls come out of it comfortably.
+ */
+const EXAMPLE_SAMPLE = 50;
+/**
+ * The query parameters that appear on accelerated pages, ranked by how many
+ * cache entries stripping them would collapse.
+ *
+ * Ranked *per parameter*: a parameter travels in many different combinations —
+ * on a large shop a single one shows up in over a thousand of them — so a
+ * ranking over whole combinations never states what one parameter is worth,
+ * which is the question being asked. `bySet` brings the combination view back.
+ *
+ * Parameters the config already strips are filtered out, so the result only
+ * lists candidates that still need a decision.
+ */
+export function buildParameterQuery(input) {
+    const { cte, subjects } = buildPageSource(input, { columns: ["createdat"] });
+    const filter = buildRuleFilter(input, subjects);
+    const warnings = [...filter.warnings];
+    const stripParameters = prepareStripParameters(input.ruleSets.stripQueryParams, subjects, { hosts: input.hosts });
+    warnings.push(...stripParameters.warnings);
+    const kept = notStrippedParameter(stripParameters, raw("key"), warnings);
+    // Only urls that carry a query string can contribute a candidate.
+    const rows = and(filter.predicate, greaterThan(call("cardinality", call("split", column("url"), literal("?"))), literal(1)));
+    const sql = `
+with ${cte}, urlWithParams as (
+  select
+    url,
+    createdat,
+    split(url, '?')[1] as path,
+    split(split(url, '?')[2], '&') as pairs,
+    filter(
+      transform(
+        split(split(url, '?')[2], '&'),
+        (pair) -> split(pair, '=')[1]
+      ),
+      (key) -> ${formatPredicate(kept, { level: 4 })}
+    ) as keptKeys
+  from ${PAGE_SOURCE}
+  where ${formatPredicate(rows, { level: 2 })}
+), cacheKeys as (
+  select
+    url,
+    createdat,
+    path,
+    pairs,
+    path || '?' || array_join(pairs, '&') as cacheKey
+  from (
+    select
+      url,
+      createdat,
+      path,
+      ${keptPairs()} as pairs
+    from urlWithParams
+  )
+  where cardinality(pairs) > 0
+)
+
+${input.bySet ? bySetQuery(input) : byParameterQuery(input)}`;
+    return {
+        approximated: filter.approximated,
+        dropped: [...filter.dropped, ...stripParameters.dropped],
+        findings: filter.findings,
+        reduced: filter.reduced,
+        sql,
+        warnings,
+    };
+}
+/**
+ * The parameters of a url that Speed Kit keeps, sorted and deduplicated.
+ *
+ * Sorting matters twice over: it makes `?b=1&a=1` and `?a=1&b=1` one cache key
+ * rather than two — which is what Speed Kit stores, since it sorts the query
+ * string — and it stops one set of parameters from being counted as several
+ * different ones.
+ */
+function keptPairs() {
+    return `array_sort(
+        array_distinct(
+          filter(pairs, (pair) -> contains(keptKeys, split(pair, '=')[1]))
+        )
+      )`;
+}
+/** One row per parameter: what it costs, and what dropping it would save. */
+function byParameterQuery(input) {
+    return `select
+  parameter,
+  count(*) as PIs,
+  count(distinct value) as distinctValues,
+  count(distinct url) as urls,
+  count(distinct cacheKey) as cachedUrls,
+  count(distinct cacheKey) - count(distinct cacheKeyWithout) as potentialGain,
+  ${example(1)} as example1,
+  ${example(2)} as example2,
+  ${example(3)} as example3
+from (
+  select
+    url,
+    createdat,
+    cacheKey,
+    split(pair, '=')[1] as parameter,
+    if(cardinality(split(pair, '=')) > 1, split(pair, '=')[2], '') as value,
+    path || if(
+      cardinality(filter(pairs, (other) -> other <> pair)) = 0,
+      '',
+      '?' || array_join(filter(pairs, (other) -> other <> pair), '&')
+    ) as cacheKeyWithout
+  from cacheKeys
+  cross join unnest(pairs) as t(pair)
+)
+group by parameter${having(input)}
+order by potentialGain desc, PIs desc, cachedUrls desc`;
+}
+/** One row per combination of parameters, the way the query read before. */
+function bySetQuery(input) {
+    return `select
+  '[' || array_join(transform(pairs, (pair) -> split(pair, '=')[1]), ', ') || ']' as paramKeys,
+  count(distinct cacheKey) - count(distinct path) as potentialGain,
+  count(distinct cacheKey) as cachedUrls,
+  count(distinct url) as urls,
+  count(*) as PIs,
+  ${example(1)} as example1,
+  ${example(2)} as example2,
+  ${example(3)} as example3
+from cacheKeys
+group by pairs${having(input)}
+order by potentialGain desc, cachedUrls desc, PIs desc`;
+}
+function having(input) {
+    const minimum = Math.max(1, Math.floor(input.minImpressions ?? 1));
+    return minimum > 1 ? `\nhaving count(*) >= ${minimum}` : "";
+}
+function example(index) {
+    return `element_at(array_distinct(max_by(url, MD5(to_utf8(to_iso8601(createdat))), ${EXAMPLE_SAMPLE})), ${index})`;
+}

package/dist/services/query-builder/queries/pops-query.d.ts

@@ -0,0 +1,27 @@
+import { AthenaParameter } from "../../athena/index.js";
+export interface PopsQueryInput {
+    readonly app: string;
+    /** Size of the window the query looks at, in days. Defaults to a week. */
+    readonly days?: number;
+    /** The day the window is measured from. Defaults to now. */
+    readonly now?: Date;
+    /**
+     * Count page-impression beacons instead of Speed Kit's own asset requests.
+     * Needed before go-live, when there is no accelerated traffic yet.
+     */
+    readonly useRum?: boolean;
+}
+export interface PopsQuery {
+    /** The values for the query's placeholders, in order. */
+    readonly parameters: AthenaParameter[];
+    readonly sql: string;
+}
+/**
+ * Which Fastly PoPs serve an app's traffic, per origin and region.
+ *
+ * The server pre-warms the PoPs relevant for a customer whenever a document is
+ * stored; this is what tells it which ones those are. Unlike the pre-warm and
+ * parameter queries it is not derived from the Speed Kit config — the log
+ * already knows which requests belong to Speed Kit — so it takes no rules.
+ */
+export declare function buildPopsQuery(input: PopsQueryInput): PopsQuery;

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

@@ -0,0 +1,65 @@
+import { and, between, booleanColumn, call, column, concat, equals, formatPredicate, isNull, literal, notInValues, parameter, } from "../sql/index.js";
+import { DEFAULT_QUERY_DAYS, sinceDate, today } from "./query-model.js";
+/** The relation carrying Fastly's request log. */
+const FASTLY_LOGS = "fastly.logs";
+/** The common table expression the aggregation reads from. */
+const REQUESTS = "requests";
+/**
+ * The locale segment of a path, e.g. `/de/`, `/de-at/`, `/shop/de/`.
+ *
+ * Origins are configured per market, so the prefix belongs to the origin the
+ * request was served for — `https://www.shop.com/de/` is a different origin
+ * than `https://www.shop.com/fr/`.
+ */
+const LOCALE_PREFIX = String.raw `(?i)((/\w+)?/[a-z]{2}([-/_][a-z]{2})*/)`;
+/**
+ * Which Fastly PoPs serve an app's traffic, per origin and region.
+ *
+ * The server pre-warms the PoPs relevant for a customer whenever a document is
+ * stored; this is what tells it which ones those are. Unlike the pre-warm and
+ * parameter queries it is not derived from the Speed Kit config — the log
+ * already knows which requests belong to Speed Kit — so it takes no rules.
+ */
+export function buildPopsQuery(input) {
+    const days = input.days ?? DEFAULT_QUERY_DAYS.pops;
+    const sql = `
+with ${REQUESTS} as (
+  select
+    region,
+    pop,
+    origin,
+    ${originWithPrefix()} as originWithPrefix
+  from ${FASTLY_LOGS}
+  where ${formatPredicate(requestFilter(input), { level: 2 })}
+)
+
+select
+  region,
+  pop,
+  coalesce(originWithPrefix, origin) as origin,
+  count() as hits
+from ${REQUESTS}
+group by grouping sets (
+  (region, pop, origin),
+  (region, pop, origin, originWithPrefix)
+)
+having originWithPrefix is null or originWithPrefix <> 'Unknown'`;
+    return {
+        // The order has to match the placeholders in the printed SQL.
+        parameters: [sinceDate(days, input.now), today(input.now), input.app],
+        sql,
+    };
+}
+/** The origin a request was served for, including its locale prefix. */
+function originWithPrefix() {
+    const assetUrl = column("asseturl");
+    return call("coalesce", concat(literal("https://"), call("url_extract_host", assetUrl), call("regexp_extract", call("url_extract_path", assetUrl), literal(LOCALE_PREFIX), literal(0))), literal("Unknown"));
+}
+function requestFilter(input) {
+    return and(between(column("date"), parameter(), parameter()), equals(column("app"), parameter()), 
+    // Before go-live there are no Speed Kit asset requests to count, so the
+    // beacons the snippet sends stand in for them.
+    input.useRum
+        ? booleanColumn("ispibeacon")
+        : and(booleanColumn("isassetrequest"), booleanColumn("isnavigaterequest")), isNull(column("client.bot")), notInValues(column("origin"), ["Unknown", ""]));
+}

package/dist/services/query-builder/queries/prewarm-query.d.ts

@@ -0,0 +1,18 @@
+import { BuiltQuery, QueryInput } from "./query-model.js";
+/**
+ * The URLs to pre-warm, most requested first: every page Speed Kit
+ * accelerates, reduced to the cache key it would be stored under.
+ *
+ * Real traffic has a long tail — two thirds of the URLs of a ten day window
+ * are typically seen exactly once — and every URL in the list costs the origin
+ * one request per variation when the job runs. `minHits` and `limit` are there
+ * to cut that tail; `hits` is selected so a list can be judged before it is
+ * used.
+ *
+ * A list can carry the variation to warm each URL in, rather than leaving the
+ * pre-warmer to request every URL in every variation: `devices` reads it off
+ * the traffic, `variations` writes the caller's own set into it. Neither takes
+ * anything away from the URL list itself — `minHits`, `limit` and the 404 rule
+ * keep judging URLs, so `--limit 5000` is still 5000 pages.
+ */
+export declare function buildPrewarmQuery(input: QueryInput): BuiltQuery;

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

@@ -0,0 +1,227 @@
+import { and, call, column, formatPredicate, greaterOrEqual, isTrue, leaf, literal, lower, raw, TRUE, } from "../sql/index.js";
+import { prepareStripParameters, strippedUrlExpression, } from "../rules/index.js";
+import { normalizeDevices } from "./device.js";
+import { buildRuleFilter } from "./page-filter.js";
+import { buildPageSource, PAGE_SOURCE } from "./page-source.js";
+/** The response cause Speed Kit records when the origin answered with a 404. */
+const NOT_FOUND = "OriginStatusNotFound";
+/** Two spaces per level, as everywhere in the emitted queries. */
+const INDENT = "  ";
+/** The name of the common table expression holding one row per impression. */
+const IMPRESSIONS = "impressions";
+/** The name of the common table expression holding one row per url. */
+const URLS = "urls";
+/** The name of the common table expression holding one row per url and variation. */
+const PAIRS = "pairs";
+/**
+ * The URLs to pre-warm, most requested first: every page Speed Kit
+ * accelerates, reduced to the cache key it would be stored under.
+ *
+ * Real traffic has a long tail — two thirds of the URLs of a ten day window
+ * are typically seen exactly once — and every URL in the list costs the origin
+ * one request per variation when the job runs. `minHits` and `limit` are there
+ * to cut that tail; `hits` is selected so a list can be judged before it is
+ * used.
+ *
+ * A list can carry the variation to warm each URL in, rather than leaving the
+ * pre-warmer to request every URL in every variation: `devices` reads it off
+ * the traffic, `variations` writes the caller's own set into it. Neither takes
+ * anything away from the URL list itself — `minHits`, `limit` and the 404 rule
+ * keep judging URLs, so `--limit 5000` is still 5000 pages.
+ */
+export function buildPrewarmQuery(input) {
+    const devices = normalizeDevices(input.devices);
+    const { cte, subjects } = buildPageSource(input, {
+        columns: input.excludeNotFound ? ["responsecause"] : [],
+    });
+    const filter = buildRuleFilter(input, subjects);
+    const warnings = [...filter.warnings];
+    const stripParameters = prepareStripParameters(input.ruleSets.stripQueryParams, subjects, { hosts: input.hosts });
+    warnings.push(...stripParameters.warnings);
+    const cacheKey = tidyQueryString(strippedUrlExpression(stripParameters, column("url"), warnings));
+    const impressions = impressionSelect(input, cacheKey, filter.predicate, {
+        byDevice: devices.length > 0,
+    });
+    return {
+        approximated: filter.approximated,
+        dropped: [...filter.dropped, ...stripParameters.dropped],
+        findings: filter.findings,
+        reduced: filter.reduced,
+        sql: assemble(input, cte, impressions, devices.length > 0),
+        warnings,
+    };
+}
+/**
+ * The three shapes of the list, and the count of whichever one was asked for.
+ * Without any of the flags the query is the one it always was, down to the
+ * byte — every one of them is opt-in, and the checked-in golden queries are
+ * the proof of it.
+ */
+function assemble(input, pages, impressions, byDevice) {
+    if (input.count) {
+        return assembleCount(input, pages, impressions, byDevice);
+    }
+    if (byDevice) {
+        // Ordered by the pair's hits, so the variations interleave: a run that is
+        // aborted or rate-limited into the ground has warmed the busiest entries
+        // of every device class, not all of one and none of the next.
+        return `
+with ${pages},
+${IMPRESSIONS} as (
+${impressions}
+),
+${URLS} as (
+${keptUrlSelect(input, IMPRESSIONS, 1)}
+)
+
+${pairSelect({ ordered: true })}`;
+    }
+    const variations = input.variations ?? [];
+    if (variations.length > 0) {
+        // Nothing says which url carries which custom variation, so every url gets
+        // every one of them. Ordering can only be url-major here.
+        return `
+with ${pages},
+${IMPRESSIONS} as (
+${impressions}
+),
+${URLS} as (
+${keptUrlSelect(input, IMPRESSIONS, 1)}
+)
+
+select ${URLS}.url, variation, ${URLS}.hits
+from ${URLS}
+  cross join unnest(array[${variations.map((variation) => literal(variation)).join(", ")}]) as t (variation)
+order by ${URLS}.hits desc, variation`;
+    }
+    return `
+with ${pages}
+
+${keptUrlSelect(input, `(\n${impressions}\n)`)}`;
+}
+/**
+ * How large the list is, instead of what is in it.
+ *
+ * Every cut the list makes is still made — the same relations are built from
+ * the same options, only the final projection counts them instead of
+ * selecting them. So a count of 4200 is the promise that the list is 4200 urls
+ * long, and a `--limit` shows up as the count stopping at the limit.
+ *
+ * `impressions` is what those urls stood for in the window: it says whether a
+ * `--minHits` cut away a tail or a third of the traffic.
+ */
+function assembleCount(input, pages, impressions, byDevice) {
+    // All three shapes count the same relations, so they are built once —
+    // unlike the list itself, a count has no reason to inline anything.
+    const relations = `
+with ${pages},
+${IMPRESSIONS} as (
+${impressions}
+),
+${URLS} as (
+${keptUrlSelect(input, IMPRESSIONS, 1)}
+)`;
+    if (byDevice) {
+        // Counted over the pairs, not over the urls: the total is what the
+        // pre-warmer would request, which is every url once per variation it was
+        // seen in — and that is more than there are urls.
+        //
+        // The column is qualified throughout because the projection names its
+        // result `variation` too, and an unqualified `grouping(variation)` in the
+        // order by resolves to that output alias, which Athena rejects.
+        return `${relations},
+${PAIRS} as (
+${pairSelect({ level: 1 })}
+)
+
+select coalesce(${PAIRS}.variation, 'total') as variation, count(*) as urls, sum(hits) as impressions
+from ${PAIRS}
+group by rollup(${PAIRS}.variation)
+order by grouping(${PAIRS}.variation) desc, 2 desc`;
+    }
+    // Every url carries every custom variation, so a row per variation would be
+    // the same number written out n times. The product is the row instead.
+    const variations = input.variations ?? [];
+    const projections = [
+        "count(*) as urls",
+        ...(variations.length > 0
+            ? [`${variations.length} * count(*) as requests`]
+            : []),
+        "sum(hits) as impressions",
+    ];
+    return `${relations}
+
+select ${projections.join(", ")}
+from ${URLS}`;
+}
+/**
+ * One row per url and variation, for a list split by device class: the urls
+ * the list keeps, each paired with the variations it was requested in.
+ */
+function pairSelect(options = {}) {
+    const indent = INDENT.repeat(options.level ?? 0);
+    return [
+        `${indent}select ${IMPRESSIONS}.url, ${IMPRESSIONS}.variation, count(*) as hits`,
+        `${indent}from ${IMPRESSIONS}`,
+        `${indent}${INDENT}join ${URLS} on ${URLS}.url = ${IMPRESSIONS}.url`,
+        `${indent}group by 1, 2`,
+        ...(options.ordered ? [`${indent}order by 3 desc`] : []),
+    ].join("\n");
+}
+/**
+ * One row per page impression, reduced to the cache key its url would be
+ * stored under — and, for a split list, the variation it was requested in.
+ */
+function impressionSelect(input, cacheKey, predicate, options) {
+    const projections = [
+        `${cacheKey} as url`,
+        ...(options.byDevice ? [`${lower(column("device"))} as variation`] : []),
+        ...(input.excludeNotFound ? [column("responsecause")] : []),
+    ];
+    return [
+        `${INDENT}select`,
+        `${INDENT.repeat(2)}${projections.join(`,\n${INDENT.repeat(2)}`)}`,
+        `${INDENT}from ${PAGE_SOURCE}`,
+        `${INDENT}where ${formatPredicate(predicate, { level: 2 })}`,
+    ].join("\n");
+}
+/**
+ * The urls worth pre-warming, most requested first — the whole query when
+ * there is no split, and the relation the split is judged against when there
+ * is one. Either way it counts urls, not rows.
+ */
+function keptUrlSelect(input, source, level = 0) {
+    const kept = keptUrls(input);
+    const indent = INDENT.repeat(level);
+    return [
+        `${indent}select url, count(*) as hits`,
+        `${indent}from ${source}`,
+        `${indent}group by url`,
+        ...(kept
+            ? [`${indent}having ${formatPredicate(kept, { level: level + 1 })}`]
+            : []),
+        `${indent}order by hits desc`,
+        ...(input.limit
+            ? [`${indent}limit ${Math.max(1, Math.floor(input.limit))}`]
+            : []),
+    ].join("\n");
+}
+/** Which of the grouped urls are worth pre-warming. */
+function keptUrls(input) {
+    const minHits = Math.max(1, Math.floor(input.minHits ?? 1));
+    const predicate = and(minHits > 1 ? greaterOrEqual(raw("count(*)"), literal(minHits)) : TRUE, 
+    // A url the origin answers with a 404 more often than not is gone; only
+    // the majority decides, because a single 404 among real hits says nothing.
+    input.excludeNotFound
+        ? leaf(`2 * count_if(responsecause = ${literal(NOT_FOUND)}) < count(*)`)
+        : TRUE);
+    return isTrue(predicate) ? undefined : predicate;
+}
+/**
+ * Repairs the URL after the stripped parameters were cut out of it: a query
+ * string that lost its first parameter starts with `&`, and one that lost all
+ * of them ends in a bare `?`.
+ */
+function tidyQueryString(url) {
+    return call("regexp_replace", call("regexp_replace", url, literal("(^[^&?]*)&"), literal("$1?")), literal("\\?$"), literal(""));
+}

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

@@ -0,0 +1,97 @@
+import { ParsedRuleSets, RuleNote } from "../rules/index.js";
+import { DeviceVariation } from "./device.js";
+/** How far back a query looks, per query type. */
+export declare const DEFAULT_QUERY_DAYS: {
+    readonly parameter: 30;
+    readonly pops: 7;
+    readonly prewarm: 10;
+};
+/** Options that shape the pre-warm query's result. */
+export interface PrewarmOptions {
+    /**
+     * Report how large the list is instead of what is in it: one row of counts,
+     * one per variation where the list carries variations.
+     *
+     * Every other option still applies — the count is the size of the list the
+     * same command would produce, `--limit` and `--minHits` included.
+     */
+    readonly count?: boolean;
+    /**
+     * Split the list by device class, so every row carries the variation its
+     * url was actually requested in. Mutually exclusive with {@link variations}.
+     *
+     * A device class not named here is dropped: a url only ever seen on a
+     * tablet produces no row when tablets are not asked for.
+     */
+    readonly devices?: readonly DeviceVariation[];
+    /** Keep only the most requested urls. */
+    readonly limit?: number;
+    /**
+     * Drop urls whose page impressions are mostly answered by an origin 404 —
+     * pre-warming them fetches a page that is not there.
+     */
+    readonly excludeNotFound?: boolean;
+    /** Keep only urls requested at least this often in the window. */
+    readonly minHits?: number;
+    /**
+     * Keep only urls matching one of these regular expressions, on top of what
+     * the config already decides. The subject is the url a rule sees — without
+     * scheme and fragment, e.g. `www.shop.de/p/1`.
+     */
+    readonly match?: readonly string[];
+    /**
+     * Pair every url of the list with each of these variations. Mutually
+     * exclusive with {@link devices}.
+     *
+     * No data says which url carries which custom variation, so this is the
+     * caller's guess, written into the list instead of applied to it later.
+     */
+    readonly variations?: readonly string[];
+}
+/** Options that shape the parameter query's result. */
+export interface ParameterOptions {
+    /**
+     * Rank whole sets of parameters, the way the query did before there was a
+     * per-parameter ranking. Useful to see which parameters travel together.
+     */
+    readonly bySet?: boolean;
+    /** Leave out parameters seen on fewer page impressions than this. */
+    readonly minImpressions?: number;
+}
+/** Everything a query is built from. */
+export interface QueryInput extends ParameterOptions, PrewarmOptions {
+    readonly app: string;
+    /** 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;
+    /** Hosts of the app's origins, used to recognise rules that cannot fire. */
+    readonly hosts?: readonly string[];
+    /** The day the window is measured from. Defaults to now. */
+    readonly now?: Date;
+    readonly ruleSets: ParsedRuleSets;
+}
+export interface BuiltQuery {
+    /** Rules whose emitted filter is wider than the rule itself. */
+    readonly approximated: RuleNote[];
+    /** Rules left out because they can never apply to a page impression. */
+    readonly dropped: RuleNote[];
+    /** Findings about the config the reduction turned up. */
+    readonly findings: RuleNote[];
+    /** Rules left out because another rule already decides their pages. */
+    readonly reduced: RuleNote[];
+    readonly sql: string;
+    /** Patterns whose meaning may differ between the browser and Athena. */
+    readonly warnings: string[];
+}
+/** Today, as `YYYY-MM-DD` — the format of the `date` partition column. */
+export declare function today(now?: Date): string;
+/**
+ * The day the query starts at, `days` before now, as `YYYY-MM-DD` — the
+ * format of the `date` partition column.
+ */
+export declare function sinceDate(days: number, now?: Date): string;

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

@@ -0,0 +1,19 @@
+/** How far back a query looks, per query type. */
+export const DEFAULT_QUERY_DAYS = {
+    parameter: 30,
+    pops: 7,
+    prewarm: 10,
+};
+/** Today, as `YYYY-MM-DD` — the format of the `date` partition column. */
+export function today(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/**
+ * The day the query starts at, `days` before now, as `YYYY-MM-DD` — the
+ * format of the `date` partition column.
+ */
+export function sinceDate(days, now = new Date()) {
+    const window = Math.max(1, Math.floor(days));
+    const since = new Date(now.getTime() - window * 24 * 60 * 60 * 1000);
+    return since.toISOString().slice(0, 10);
+}

package/dist/services/query-builder/queries/spec/golden-configs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Config shapes the query builder has to get right, each one standing for a
+ * class of real customer configs.
+ *
+ * These feed the golden queries in `golden.spec.ts`: the whole emitted SQL and
+ * the whole accounting are checked in next to them, so any change to the
+ * builder shows up as a reviewable diff instead of as a surprise in a
+ * pre-warm run.
+ */
+export interface GoldenConfig {
+    /** The evaluated `window.speedKit` of a customer config. */
+    readonly config: Record<string, unknown>;
+    /** Why this shape is here. */
+    readonly describes: string;
+    readonly hosts: readonly string[];
+    readonly name: string;
+}
+export declare const GOLDEN_CONFIGS: readonly GoldenConfig[];