@speedkit/cli 4.25.2 → 4.27.0

package/dist/services/prewarm/pre-warm-service.d.ts

@@ -1,19 +1,24 @@
 import { CliServiceInterface } from "../cli/index.js";
-import { AssetItemInterface } from "./index.js";
+import { AssetItemInterface, PrewarmTarget } from "./index.js";
 import { AssetApiClient } from "./assets/asset-api-client.js";
 export declare class PreWarmService {
     private assetClient;
     private cli;
-    private urls;
-    private variations;
+    private targets;
     private verbose;
     private requestsSend;
-    constructor(assetClient: AssetApiClient, cli: CliServiceInterface, urls: string[], variations: string[], verbose: boolean);
+    constructor(assetClient: AssetApiClient, cli: CliServiceInterface, targets: readonly PrewarmTarget[], verbose: boolean);
     handleAsset(assetClient: AssetApiClient, entry: AssetItemInterface): Promise<void>;
     run(): Promise<void>;
     private fetchAssetList;
     private handleProgress;
     private fetchUrls;
+    /**
+     * The request list, in the order the targets were given. The order is the
+     * caller's to decide — a list built by device interleaves the variations, so
+     * that a run cut short has warmed the busiest entries of each rather than
+     * all of one and none of the next.
+     */
     private generateAssetRequestList;
     private printSummary;
     private startProgressBar;

package/dist/services/prewarm/pre-warm-service.js

@@ -5,15 +5,13 @@ import { AssetList } from "./assets/asset-list.js";
 export class PreWarmService {
     assetClient;
     cli;
-    urls;
-    variations;
+    targets;
     verbose;
     requestsSend = 0;
-    constructor(assetClient, cli, urls, variations, verbose) {
+    constructor(assetClient, cli, targets, verbose) {
         this.assetClient = assetClient;
         this.cli = cli;
-        this.urls = urls;
-        this.variations = variations;
+        this.targets = targets;
         this.verbose = verbose;
     }
     async handleAsset(assetClient, entry) {
@@ -49,7 +47,7 @@ export class PreWarmService {
         entry.setError(new Error(`status: ${response.status}, sk-error: ${serverTimingErrorCode}`));
     }
     async run() {
-        const assetList = this.generateAssetRequestList(this.urls);
+        const assetList = this.generateAssetRequestList(this.targets);
         await this.fetchUrls(assetList);
         await this.printSummary(assetList);
         if (assetList.getRetryCount() === 0) {
@@ -58,10 +56,12 @@ export class PreWarmService {
         this.cli.write("Retry rateLimited requests.");
         // reset for minimal output
         this.requestsSend = 0;
-        const urlsToRetry = assetList
+        // Rebuilt from the items themselves: they already carry the variation they
+        // were rate-limited in, and crossing their urls with anything else would
+        // both re-expand the list and lose that pairing.
+        const retryList = this.generateAssetRequestList(assetList
             .getByStatus(ItemStatus.RETRY)
-            .map((entry) => entry.url);
-        const retryList = this.generateAssetRequestList(urlsToRetry);
+            .map(({ url, variation }) => ({ url, variation })));
         this.assetClient.setIsRetry();
         await this.fetchUrls(retryList);
         await this.printSummary(retryList);
@@ -109,12 +109,16 @@ export class PreWarmService {
         await this.fetchAssetList(assetList);
         this.stopProgressBar();
     }
-    generateAssetRequestList(urls) {
+    /**
+     * The request list, in the order the targets were given. The order is the
+     * caller's to decide — a list built by device interleaves the variations, so
+     * that a run cut short has warmed the busiest entries of each rather than
+     * all of one and none of the next.
+     */
+    generateAssetRequestList(targets) {
         const assetList = new AssetList();
-        for (const variation of this.variations) {
-            for (const url of urls) {
-                assetList.addItem(new AssetItem(url, variation));
-            }
+        for (const { url, variation } of targets) {
+            assetList.addItem(new AssetItem(url, variation));
         }
         return assetList;
     }

package/dist/services/prewarm/prewarm-targets.d.ts

@@ -0,0 +1,12 @@
+import { PrewarmRow, PrewarmTarget } from "./pre-warm-model.js";
+/**
+ * The (url, variation) pairs to warm.
+ *
+ * A list that already names a variation per url is taken as it stands — its
+ * order is the one whoever built it chose, and every pair in it was actually
+ * requested. A list of bare urls is crossed with the variations the caller
+ * named, url-major: each url is warmed in every variation before the next url
+ * is touched, so a run cut short has warmed whole pages rather than one
+ * variation of all of them.
+ */
+export declare function toPrewarmTargets(rows: readonly PrewarmRow[], variations: readonly string[]): PrewarmTarget[];

package/dist/services/prewarm/prewarm-targets.js

@@ -0,0 +1,18 @@
+/**
+ * The (url, variation) pairs to warm.
+ *
+ * A list that already names a variation per url is taken as it stands — its
+ * order is the one whoever built it chose, and every pair in it was actually
+ * requested. A list of bare urls is crossed with the variations the caller
+ * named, url-major: each url is warmed in every variation before the next url
+ * is touched, so a run cut short has warmed whole pages rather than one
+ * variation of all of them.
+ */
+export function toPrewarmTargets(rows, variations) {
+    if (rows.some((row) => row.variation)) {
+        return rows
+            .filter((row) => row.variation)
+            .map(({ url, variation }) => ({ url, variation }));
+    }
+    return rows.flatMap(({ url }) => variations.map((variation) => ({ url, variation })));
+}

package/dist/services/prewarm/prewarm-targets.spec.d.ts

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

package/dist/services/prewarm/prewarm-targets.spec.js

@@ -0,0 +1,29 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { toPrewarmTargets } from "./prewarm-targets.js";
+describe("toPrewarmTargets", () => {
+    it("should keep a paired list in the order it was given", () => {
+        // The order is the query's interleaving of the variations by hit count:
+        // grouping or sorting it here would undo the point of the split.
+        const rows = [
+            { url: "https://a.de/", variation: "mobile" },
+            { url: "https://b.de/", variation: "desktop" },
+            { url: "https://a.de/", variation: "desktop" },
+        ];
+        expect(toPrewarmTargets(rows, ["default"])).to.deep.equal(rows);
+    });
+    it("should not cross a paired list with the variations", () => {
+        expect(toPrewarmTargets([{ url: "https://a.de/", variation: "mobile" }], ["men", "women"])).to.have.lengthOf(1);
+    });
+    it("should cross a bare list url-major", () => {
+        expect(toPrewarmTargets([{ url: "https://a.de/" }, { url: "https://b.de/" }], ["desktop", "mobile"])).to.deep.equal([
+            { url: "https://a.de/", variation: "desktop" },
+            { url: "https://a.de/", variation: "mobile" },
+            { url: "https://b.de/", variation: "desktop" },
+            { url: "https://b.de/", variation: "mobile" },
+        ]);
+    });
+    it("should warm nothing when there is no variation to warm in", () => {
+        expect(toPrewarmTargets([{ url: "https://a.de/" }], [])).to.deep.equal([]);
+    });
+});

package/dist/services/query-builder/error/match-matches-nothing-error.d.ts

@@ -0,0 +1,11 @@
+import ApplicationError from "../../error-handling/error/application-error.js";
+/**
+ * A `--match` pattern the config can never let through.
+ *
+ * The query would be valid and return nothing, after a full Athena scan. This
+ * stops before the query is sent.
+ */
+export declare class MatchMatchesNothingError extends ApplicationError {
+    readonly code = "MATCH_MATCHES_NOTHING";
+    constructor(reason: string);
+}

package/dist/services/query-builder/error/match-matches-nothing-error.js

@@ -0,0 +1,17 @@
+import ApplicationError from "../../error-handling/error/application-error.js";
+/**
+ * A `--match` pattern the config can never let through.
+ *
+ * The query would be valid and return nothing, after a full Athena scan. This
+ * stops before the query is sent.
+ */
+export class MatchMatchesNothingError extends ApplicationError {
+    code = "MATCH_MATCHES_NOTHING";
+    constructor(reason) {
+        super(`--match ${reason}`);
+        this.suggestions = [
+            "the pattern is matched against the url without its scheme, e.g. www.shop.de/p/1",
+            "check the pattern against the config's enabledSites, disabledSites and blacklist",
+        ];
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The device classes a pre-warm list can be split by.
+ *
+ * These are the variation names Speed Kit computes from the user agent, not
+ * the values `rum.pi` records — see {@link DEVICE_COLUMN_VALUES} for the
+ * translation. `Robot` is not one of them: a query never counts bots.
+ *
+ * A custom variation (`desktop-pdp-a`, `abtest_b`, `men`) can never be derived
+ * from a device, so it cannot be a value here — `--variation` puts those into
+ * the list by hand.
+ */
+export declare const DEVICE_VARIATIONS: readonly ["desktop", "mobile", "tablet"];
+export type DeviceVariation = (typeof DEVICE_VARIATIONS)[number];
+/** How `rum.pi` spells each of them in its `device` column. */
+export declare const DEVICE_COLUMN_VALUES: Record<DeviceVariation, string>;
+/**
+ * The requested devices in the canonical order, without duplicates — so the
+ * same request always produces the same SQL, whatever order the flag was
+ * given in.
+ */
+export declare function normalizeDevices(devices: readonly string[] | undefined): DeviceVariation[];

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

@@ -0,0 +1,26 @@
+/**
+ * The device classes a pre-warm list can be split by.
+ *
+ * These are the variation names Speed Kit computes from the user agent, not
+ * the values `rum.pi` records — see {@link DEVICE_COLUMN_VALUES} for the
+ * translation. `Robot` is not one of them: a query never counts bots.
+ *
+ * A custom variation (`desktop-pdp-a`, `abtest_b`, `men`) can never be derived
+ * from a device, so it cannot be a value here — `--variation` puts those into
+ * the list by hand.
+ */
+export const DEVICE_VARIATIONS = ["desktop", "mobile", "tablet"];
+/** How `rum.pi` spells each of them in its `device` column. */
+export const DEVICE_COLUMN_VALUES = {
+    desktop: "Desktop",
+    mobile: "Mobile",
+    tablet: "Tablet",
+};
+/**
+ * The requested devices in the canonical order, without duplicates — so the
+ * same request always produces the same SQL, whatever order the flag was
+ * given in.
+ */
+export function normalizeDevices(devices) {
+    return DEVICE_VARIATIONS.filter((device) => devices?.includes(device));
+}

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

@@ -0,0 +1,6 @@
+export * from "./device.js";
+export * from "./page-filter.js";
+export * from "./parameter-query.js";
+export * from "./pops-query.js";
+export * from "./prewarm-query.js";
+export * from "./query-model.js";

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

@@ -0,0 +1,6 @@
+export * from "./device.js";
+export * from "./page-filter.js";
+export * from "./parameter-query.js";
+export * from "./pops-query.js";
+export * from "./prewarm-query.js";
+export * from "./query-model.js";

package/dist/services/query-builder/queries/page-filter.d.ts

@@ -0,0 +1,39 @@
+import { Predicate } from "../sql/index.js";
+import { RuleNote, RuleSubjectExpressions } from "../rules/index.js";
+import { QueryInput } from "./query-model.js";
+export interface RuleFilter {
+    readonly approximated: RuleNote[];
+    readonly dropped: RuleNote[];
+    /** Findings about the config itself, worth reporting on their own. */
+    readonly findings: RuleNote[];
+    readonly predicate: Predicate;
+    /** Rules left out because another rule already decides their pages. */
+    readonly reduced: RuleNote[];
+    readonly warnings: string[];
+}
+/**
+ * Which page impressions a query counts at all: the app's own traffic in the
+ * requested window, without the noise the caller asked to leave out.
+ *
+ * Bots are always excluded — a crawler requests pages no real user asks for,
+ * and neither pre-warming nor a parameter analysis should be driven by them.
+ * Naming the device classes to keep subsumes that: `Robot` is not one of them,
+ * and `in` leaves out a null device the same way `<> 'Robot'` does.
+ */
+export declare function buildRowFilter(input: QueryInput): Predicate;
+/**
+ * Which of those pages Speed Kit accelerates.
+ *
+ * The rule sets are combined the way the runtime evaluates them:
+ * `enabledSites` decides first and an empty set means every page, then
+ * `disabledSites` takes pages away; `whitelist` and `blacklist` do the same
+ * for the document as a resource. `disabledScopes` takes away whatever the
+ * service worker never claims in the first place.
+ *
+ * Before that, the sets are ruled against each other. Each set loses the rules
+ * a sibling already covers, and the two excluding sets additionally lose every
+ * rule that excludes pages the including sets never let through — which is
+ * most of a real blacklist, since it guards paths `enabledSites` never
+ * allowed. What remains is the part of the config the data can actually see.
+ */
+export declare function buildRuleFilter(input: QueryInput, subjects: RuleSubjectExpressions): RuleFilter;

package/dist/services/query-builder/queries/page-filter.js

@@ -0,0 +1,135 @@
+import { and, call, column, equals, FALSE, greaterOrEqual, inValues, leaf, literal, not, notEquals, TRUE, } from "../sql/index.js";
+import { absorbRules, asPathWithSearchRule, buildMatchRule, dropUnreachableRules, findShadowedRules, keepRelevantRules, reductionBudget, translateRules, } from "../rules/index.js";
+import { MatchMatchesNothingError } from "../error/match-matches-nothing-error.js";
+import { DEVICE_COLUMN_VALUES, normalizeDevices } from "./device.js";
+import { sinceDate } from "./query-model.js";
+/** The navigation types that are a full document load. */
+const HARD_NAVIGATION_TYPES = ["NAVIGATE", "RELOAD", "BACK_FORWARD"];
+/**
+ * Which page impressions a query counts at all: the app's own traffic in the
+ * requested window, without the noise the caller asked to leave out.
+ *
+ * Bots are always excluded — a crawler requests pages no real user asks for,
+ * and neither pre-warming nor a parameter analysis should be driven by them.
+ * Naming the device classes to keep subsumes that: `Robot` is not one of them,
+ * and `in` leaves out a null device the same way `<> 'Robot'` does.
+ */
+export function buildRowFilter(input) {
+    const devices = normalizeDevices(input.devices);
+    return and(equals(column("app"), literal(input.app)), greaterOrEqual(column("date"), literal(sinceDate(input.days, input.now))), devices.length > 0
+        ? inValues(column("device"), devices.map((device) => DEVICE_COLUMN_VALUES[device]))
+        : notEquals(column("device"), literal("Robot")), input.hardNavigationsOnly
+        ? inValues(column("navigationtype"), HARD_NAVIGATION_TYPES)
+        : TRUE, input.excludeSuspicious ? not(isSet("suspicious")) : TRUE, input.excludeNoindex ? not(isSet("noindex")) : TRUE);
+}
+/**
+ * Which of those pages Speed Kit accelerates.
+ *
+ * The rule sets are combined the way the runtime evaluates them:
+ * `enabledSites` decides first and an empty set means every page, then
+ * `disabledSites` takes pages away; `whitelist` and `blacklist` do the same
+ * for the document as a resource. `disabledScopes` takes away whatever the
+ * service worker never claims in the first place.
+ *
+ * Before that, the sets are ruled against each other. Each set loses the rules
+ * a sibling already covers, and the two excluding sets additionally lose every
+ * rule that excludes pages the including sets never let through — which is
+ * most of a real blacklist, since it guards paths `enabledSites` never
+ * allowed. What remains is the part of the config the data can actually see.
+ */
+export function buildRuleFilter(input, subjects) {
+    const { ruleSets } = input;
+    const approximated = [];
+    const dropped = [];
+    const reduced = [];
+    const warnings = [];
+    // One budget for the whole build, so the reductions cannot add up.
+    const budget = reductionBudget();
+    /** The rules of a set that can apply to a page impression at all. */
+    const relevant = (rules) => {
+        const result = keepRelevantRules(rules, { hosts: input.hosts });
+        approximated.push(...result.approximated);
+        dropped.push(...result.dropped);
+        return result.rules;
+    };
+    /** What a sibling rule already covers, dropped. */
+    const absorb = (rules) => {
+        const absorbed = absorbRules(rules, budget);
+        reduced.push(...absorbed.notes);
+        return absorbed.rules;
+    };
+    const translate = (rules, whenEmpty) => {
+        const translation = translateRules(rules, subjects, { whenEmpty });
+        warnings.push(...translation.warnings);
+        return translation.predicate;
+    };
+    const whitelist = absorb(relevant(ruleSets.whitelist));
+    const enabledSites = absorb(relevant(ruleSets.enabledSites));
+    // An empty including set lets everything through, so it constrains nothing.
+    const reachable = [enabledSites, whitelist].filter((set) => set.length > 0);
+    /**
+     * Reachability first, absorption second.
+     *
+     * Both shorten the query, but dropping what can never fire is the reduction
+     * that carries a real config — most of a blacklist guards pages
+     * `enabledSites` never allowed — while absorbing a sibling is cosmetic and
+     * costs a comparison for every pair of entries. Spending the budget in that
+     * order means a config that runs out of it still got the reduction worth
+     * having, and absorption then works on fewer entries.
+     */
+    const exclude = (rules) => {
+        const reachableOnly = dropUnreachableRules(rules, reachable, budget);
+        reduced.push(...reachableOnly.notes);
+        return absorb(reachableOnly.rules);
+    };
+    const excluding = [
+        relevant(ruleSets.blacklist),
+        relevant(ruleSets.disabledSites),
+        relevant(ruleSets.disabledScopes),
+    ];
+    /**
+     * The narrowing the caller asked for, held against what the config takes
+     * away.
+     *
+     * A pattern the excluding rules already cover would build a valid query,
+     * scan the whole window and return nothing, so it is refused before the
+     * query is handed over. The rules are the ones the query frame leaves, not
+     * the ones the reduction leaves: an entry dropped below because
+     * `enabledSites` never lets its pages through still says that a pattern
+     * aimed at them has nothing to warm.
+     *
+     * The comparison gets a budget of its own. It costs one comparison per
+     * excluding rule, and sharing the build's budget would mean a config large
+     * enough to spend it first is silently not checked at all.
+     */
+    const match = buildMatchRule(input.match);
+    if (match) {
+        const [shadowed] = findShadowedRules([match], excluding.flat().map(asPathWithSearchRule).filter(Boolean), reductionBudget());
+        if (shadowed) {
+            throw new MatchMatchesNothingError(shadowed.reason);
+        }
+    }
+    const [blacklist, disabledSites, disabledScopes] = excluding.map(exclude);
+    const predicate = and(translate(whitelist, TRUE), not(translate(blacklist, FALSE)), translate(enabledSites, TRUE), not(translate(disabledSites, FALSE)), 
+    // A page inside a disabled scope is served by an empty service worker, so
+    // Speed Kit never sees it at all.
+    not(translate(disabledScopes, FALSE)), 
+    // Last, so the query reads as the config's filter with the caller's
+    // narrowing applied to it.
+    match ? translate([match], TRUE) : TRUE);
+    return {
+        approximated,
+        dropped,
+        findings: findShadowedRules(enabledSites, [...disabledScopes, ...disabledSites, ...blacklist], budget),
+        predicate,
+        reduced,
+        warnings,
+    };
+}
+/**
+ * A boolean column that may be null. `not column` would drop the null rows
+ * along with the true ones, which is not what excluding a flag means.
+ */
+function isSet(name) {
+    return leaf(call("coalesce", column(name), literal(false)), true);
+}

package/dist/services/query-builder/queries/page-source.d.ts

@@ -0,0 +1,30 @@
+import { RuleSubjectExpressions } from "../rules/index.js";
+import { QueryInput } from "./query-model.js";
+/** The relation every query reads from. */
+export declare const PAGE_IMPRESSIONS = "live.rum.pi";
+/** The name of the common table expression the queries select from. */
+export declare const PAGE_SOURCE = "pages";
+export interface PageSource {
+    /** The `pages as (…)` common table expression, without the `with`. */
+    readonly cte: string;
+    /** The expressions rule conditions are matched against. */
+    readonly subjects: RuleSubjectExpressions;
+}
+export interface PageSourceOptions {
+    /**
+     * Columns of the relation to carry through, beyond `url`. Each query asks
+     * for what it reads: `createdat` is only needed where example urls are
+     * picked, `responsecause` only where 404s are filtered out.
+     */
+    readonly columns?: readonly string[];
+}
+/**
+ * The rows a query works on: the app's page impressions in the requested
+ * window, with everything a rule matches against projected once.
+ *
+ * Deriving host and path per condition would repeat the same
+ * `url_extract_path(url)` a dozen times in a single `where` clause. Naming
+ * them here keeps the query readable — which matters, because these queries
+ * are read and adjusted by hand in the Athena console.
+ */
+export declare function buildPageSource(input: QueryInput, options?: PageSourceOptions): PageSource;

package/dist/services/query-builder/queries/page-source.js

@@ -0,0 +1,79 @@
+import { column, formatPredicate } from "../sql/index.js";
+import { resolvedSubject, urlSubjects, } from "../rules/index.js";
+import { normalizeDevices } from "./device.js";
+import { buildRowFilter } from "./page-filter.js";
+/** The relation every query reads from. */
+export const PAGE_IMPRESSIONS = "live.rum.pi";
+/** The name of the common table expression the queries select from. */
+export const PAGE_SOURCE = "pages";
+const COLUMN_NAMES = {
+    host: "host",
+    path: "path",
+    pathWithSearch: "pathWithSearch",
+    url: "matchUrl",
+};
+/**
+ * The rows a query works on: the app's page impressions in the requested
+ * window, with everything a rule matches against projected once.
+ *
+ * Deriving host and path per condition would repeat the same
+ * `url_extract_path(url)` a dozen times in a single `where` clause. Naming
+ * them here keeps the query readable — which matters, because these queries
+ * are read and adjusted by hand in the Athena console.
+ */
+export function buildPageSource(input, options = {}) {
+    const inline = urlSubjects(column("url"));
+    const used = usedSubjects(input);
+    const projections = [
+        "url",
+        // The device is the variation a split list is keyed by, so it is read
+        // exactly where one was asked for.
+        ...(normalizeDevices(input.devices).length > 0 ? [column("device")] : []),
+        ...(options.columns ?? []).map((name) => column(name)),
+        ...Object.keys(COLUMN_NAMES)
+            .filter((subject) => used.has(subject))
+            .map((subject) => `${inline[subject]} as ${COLUMN_NAMES[subject]}`),
+    ];
+    const cte = `${PAGE_SOURCE} as (
+  select
+    ${projections.join(",\n    ")}
+  from ${PAGE_IMPRESSIONS}
+  where ${formatPredicate(buildRowFilter(input), { level: 2 })}
+)`;
+    // An unused subject keeps its inline expression: nothing refers to it, and
+    // that way a caller cannot accidentally read a column that is not there.
+    const subjects = Object.fromEntries(Object.keys(COLUMN_NAMES).map((subject) => [
+        subject,
+        used.has(subject)
+            ? column(COLUMN_NAMES[subject])
+            : inline[subject],
+    ]));
+    return { cte, subjects };
+}
+/** The subjects the config's rules actually match against. */
+function usedSubjects(input) {
+    const { ruleSets } = input;
+    const used = new Set();
+    // A `--match` pattern is a version 1 pathname condition, which reads the
+    // query string along with the path.
+    if (input.match && input.match.length > 0) {
+        used.add("pathWithSearch");
+    }
+    const collect = (rules) => {
+        for (const rule of rules) {
+            for (const { subject } of rule.conditions) {
+                used.add(resolvedSubject(subject, rule.ruleSetVersion));
+            }
+        }
+    };
+    collect(ruleSets.blacklist);
+    collect(ruleSets.disabledScopes);
+    collect(ruleSets.disabledSites);
+    collect(ruleSets.enabledSites);
+    collect(ruleSets.whitelist);
+    for (const rule of ruleSets.stripQueryParams) {
+        collect(rule.enabledSites ?? []);
+        collect(rule.rules ?? []);
+    }
+    return used;
+}

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

@@ -0,0 +1,14 @@
+import { BuiltQuery, QueryInput } from "./query-model.js";
+/**
+ * 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 declare function buildParameterQuery(input: QueryInput): BuiltQuery;