@speedkit/cli 4.26.0 → 4.27.1

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

@@ -1,22 +1,37 @@
-import { getSpeedKitConfigVersion } from "../../helpers/get-parsed-config.js";
-import { getBlacklistedFilter, getParameterFilter, getParameterReplaceFilter, getStrippedParameters, getWhitelistedFilter, } from "../../helpers/build-query-helper.js";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import clipboardy from "clipboardy";
 import json2Csv from "json2csv";
-import { QueryTpe, } from "./query-builder-model.js";
-import { Prewarm } from "./query/prewarm.js";
-import { Parameter } from "./query/parameter.js";
+import { QueryType } from "./query-builder-model.js";
+import { buildParameterQuery, buildPrewarmQuery, DEFAULT_QUERY_DAYS, } from "./queries/index.js";
 import { AthenaBucket } from "../athena/index.js";
+import { copyToClipboard } from "../../helpers/clipboard.js";
 import { safe } from "../../helpers/safe.js";
+/**
+ * The notes as unique lines. Each phase of the reduction reports on its own,
+ * so the same note — the budget running out, above all — can arrive more than
+ * once.
+ */
+function distinct(notes) {
+    return [
+        ...new Set(notes.map(({ reason, source }) => `Reduced ${source}: ${reason}`)),
+    ];
+}
+/**
+ * A count as it is read: grouped in thousands. Athena hands numbers over as
+ * strings, so anything that is not one is passed through untouched.
+ */
+function readable(value) {
+    const text = String(value ?? "");
+    return /^\d+$/.test(text) ? Number(text).toLocaleString("en-US") : text;
+}
 export class QueryBuilderService {
     context;
-    speedKitConfig;
+    ruleSets;
     cli;
     athenaService;
-    constructor(context, speedKitConfig, cli, athenaService) {
+    constructor(context, ruleSets, cli, athenaService) {
         this.context = context;
-        this.speedKitConfig = speedKitConfig;
+        this.ruleSets = ruleSets;
         this.cli = cli;
         this.athenaService = athenaService;
     }
@@ -25,37 +40,49 @@ export class QueryBuilderService {
         return this.context.app;
     }
     async run() {
-        this.cli.startAction(`QUERY:BUILD:${this.context.queryType}`, `build ${this.context.queryType}-query`);
-        const parameters = getStrippedParameters(this.speedKitConfig);
-        const parameterReplaceFilter = getParameterReplaceFilter(parameters, getSpeedKitConfigVersion(this.speedKitConfig));
-        const whitelistedFilter = getWhitelistedFilter(this.speedKitConfig);
-        const blacklistedFilter = getBlacklistedFilter(this.speedKitConfig);
-        const skConfigVersion = getSpeedKitConfigVersion(this.speedKitConfig);
-        const parameterFilter = getParameterFilter(parameters, skConfigVersion);
-        const result = safe(() => this.buildQuery(this.context.app, parameterFilter, whitelistedFilter, blacklistedFilter, parameterReplaceFilter));
-        this.cli.successAction(`QUERY:BUILD:${this.context.queryType}`);
+        const action = `QUERY:BUILD:${this.context.queryType}`;
+        this.cli.startAction(action, `build ${this.context.queryType}-query`);
+        const result = safe(() => this.build());
         if (result.success !== true) {
-            this.cli.failAction(`QUERY:BUILD:${this.context.queryType}`, result.error);
+            this.cli.failAction(action, result.error);
             this.cli.writeError(result.error);
             console.error(result.errorObj);
             return;
         }
-        this.cli.successAction(`QUERY:BUILD:${this.context.queryType}`);
+        this.cli.successAction(action);
+        const query = result.data;
+        if (this.context.count) {
+            if (this.context.explain) {
+                this.report(query);
+            }
+            await this.executeAndReportCounts(query.sql);
+            return;
+        }
         if (this.context.execute) {
-            await this.executeAndExport(result.data);
+            await this.executeAndExport(query.sql);
             return;
         }
         if (this.context.quiet) {
-            process.stdout.write(result.data);
+            // The query goes to stdout so it can be piped; an accounting the caller
+            // asked for goes next to it, on stderr.
+            if (this.context.explain) {
+                process.stderr.write(`${this.reportLines(query).join("\n")}\n`);
+            }
+            process.stdout.write(query.sql);
             return;
         }
-        if (!this.context.isWindows) {
-            clipboardy.writeSync(result.data);
+        this.report(query);
+        // The query is the result, the clipboard is a convenience: write it out
+        // first so nothing about the clipboard can delay or hide it.
+        this.cli.write(this.cli.style.dim.italic(query.sql));
+        if (this.context.isWindows) {
+            return;
         }
-        this.cli.write(this.cli.style.dim.italic(result.data));
-        if (!this.context.isWindows) {
+        if (await copyToClipboard(query.sql)) {
             this.cli.writeSuccess("Result has been copied to the clipboard 📋");
+            return;
         }
+        this.cli.write(this.cli.style.dim("The clipboard could not be reached 📋"));
     }
     /**
      * Build and execute the query against Athena (Baqend native path, AWS
@@ -65,12 +92,115 @@ export class QueryBuilderService {
     async execute() {
         return this.runQuery(this.query());
     }
+    /** The query as SQL. */
+    query() {
+        return this.build().sql;
+    }
+    build() {
+        const input = {
+            app: this.context.app,
+            bySet: this.context.bySet,
+            count: this.context.count,
+            days: this.context.days ?? DEFAULT_QUERY_DAYS[this.context.queryType],
+            devices: this.context.devices,
+            excludeNotFound: this.context.excludeNotFound,
+            excludeNoindex: this.context.excludeNoindex,
+            excludeSuspicious: this.context.excludeSuspicious,
+            hardNavigationsOnly: this.context.hardNavigationsOnly,
+            hosts: this.context.hosts,
+            limit: this.context.limit,
+            match: this.context.match,
+            minHits: this.context.minHits,
+            minImpressions: this.context.minImpressions,
+            ruleSets: this.ruleSets,
+            variations: this.context.variations,
+        };
+        return this.context.queryType === QueryType.prewarm
+            ? buildPrewarmQuery(input)
+            : buildParameterQuery(input);
+    }
+    /**
+     * 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.
+     */
+    report(query) {
+        for (const { reason, source } of query.findings) {
+            this.cli.writeWarning(`${source} ${reason}`);
+        }
+        for (const { reason, source } of query.dropped) {
+            this.cli.writeWarning(`Left out ${source}: ${reason}`);
+        }
+        for (const { reason, source } of query.approximated) {
+            this.cli.writeWarning(`Approximated ${source}: ${reason}`);
+        }
+        for (const warning of query.warnings) {
+            this.cli.writeWarning(warning);
+        }
+        const reduced = distinct(query.reduced);
+        if (this.context.explain) {
+            for (const line of reduced) {
+                this.cli.write(this.cli.style.dim(line));
+            }
+            return;
+        }
+        if (reduced.length > 0) {
+            this.cli.write(this.cli.style.dim(`${reduced.length} rule(s) reduced away — run with --explain to see them`));
+        }
+    }
+    /** The same accounting as {@link report}, as plain lines. */
+    reportLines(query) {
+        return [
+            ...query.findings.map(({ reason, source }) => `${source} ${reason}`),
+            ...query.dropped.map(({ reason, source }) => `Left out ${source}: ${reason}`),
+            ...query.approximated.map(({ reason, source }) => `Approximated ${source}: ${reason}`),
+            ...query.warnings,
+            ...distinct(query.reduced),
+        ];
+    }
     async runQuery(query) {
         if (!this.athenaService) {
             throw new Error("No Athena service available to execute the query");
         }
         return this.athenaService.getResult(query, [], undefined, AthenaBucket.RumPi);
     }
+    /**
+     * 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.
+     */
+    async executeAndReportCounts(query) {
+        this.cli.startAction("QUERY:COUNT", "count the pre-warm list");
+        const result = await safe(this.runQuery(query));
+        if (result.success !== true) {
+            this.cli.failAction("QUERY:COUNT");
+            this.cli.writeError(result.error);
+            return;
+        }
+        this.cli.successAction("QUERY:COUNT");
+        const rows = result.data;
+        if (rows.length === 0) {
+            this.cli.writeWarning("No page impressions in the window — the list would be empty");
+            return;
+        }
+        if (this.context.quiet) {
+            const columns = Object.keys(rows[0]);
+            process.stdout.write([
+                columns.join("\t"),
+                ...rows.map((row) => columns.map((name) => row[name]).join("\t")),
+            ].join("\n") + "\n");
+            return;
+        }
+        this.cli.table(rows, Object.fromEntries(Object.keys(rows[0]).map((name) => [
+            name,
+            { get: (row) => readable(row[name]) },
+        ])));
+    }
     /**
      * 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
@@ -80,7 +210,7 @@ export class QueryBuilderService {
         this.cli.startAction("QUERY:EXECUTE", "execute query and export csv");
         const result = await safe(this.runQuery(query));
         if (result.success !== true) {
-            this.cli.failAction("QUERY:EXECUTE", result.error);
+            this.cli.failAction("QUERY:EXECUTE");
             this.cli.writeError(result.error);
             return;
         }
@@ -93,21 +223,4 @@ export class QueryBuilderService {
         this.cli.successAction("QUERY:EXECUTE");
         this.cli.writeSuccess(`Wrote ${rows.length} rows to ${filePath} 📄`);
     }
-    query() {
-        const parameters = getStrippedParameters(this.speedKitConfig);
-        const parameterReplaceFilter = getParameterReplaceFilter(parameters, getSpeedKitConfigVersion(this.speedKitConfig));
-        const whitelistedFilter = getWhitelistedFilter(this.speedKitConfig);
-        const blacklistedFilter = getBlacklistedFilter(this.speedKitConfig);
-        const skConfigVersion = getSpeedKitConfigVersion(this.speedKitConfig);
-        const parameterFilter = getParameterFilter(parameters, skConfigVersion);
-        return this.buildQuery(this.context.app, parameterFilter, whitelistedFilter, blacklistedFilter, parameterReplaceFilter);
-    }
-    buildQuery(app, parameterFilter, whitelistedFilter, blacklistedFilter, parameterReplaceFilter) {
-        if (this.context.queryType === QueryTpe.prewarm) {
-            return new Prewarm(app, whitelistedFilter, blacklistedFilter, parameterReplaceFilter).query;
-        }
-        if (this.context.queryType === QueryTpe.parameter) {
-            return new Parameter(app, parameterFilter, whitelistedFilter, blacklistedFilter, parameterReplaceFilter).query;
-        }
-    }
 }

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

@@ -0,0 +1,27 @@
+import { Config } from "@oclif/core";
+import { ParameterOptions, PrewarmOptions } from "./queries/query-model.js";
+import { QueryFilterOptions, QueryType } from "./query-builder-model.js";
+/**
+ * The flags a query command parses; each takes the ones it offers.
+ *
+ * `--device` and `--variation` are named as the flags are, singular, and are
+ * the two the caller gives rather than the list the builder works on.
+ */
+export interface QueryCommandFlags extends ParameterOptions, Omit<PrewarmOptions, "devices" | "variations">, QueryFilterOptions {
+    readonly configName: string;
+    readonly device?: readonly string[];
+    readonly execute?: boolean;
+    readonly explain?: boolean;
+    readonly quiet?: boolean;
+    readonly variation?: readonly string[];
+    readonly workgroup?: string;
+}
+/**
+ * Builds one of the config-derived queries and hands it over.
+ *
+ * Both `sk query` commands differ only in which query they ask for, so the
+ * wiring lives here rather than twice in the command layer — the two of them
+ * drifting apart is what left a diverged copy of the parameter query behind
+ * once already.
+ */
+export declare function runQuery(queryType: QueryType, customerPath: string, flags: QueryCommandFlags, config: Config): Promise<void>;

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

@@ -0,0 +1,36 @@
+import { CliConfig } from "../../helpers/cli-config.js";
+import { QueryBuilderFactory } from "./query-builder-factory.js";
+import { normalizeDevices } from "./queries/device.js";
+/**
+ * Builds one of the config-derived queries and hands it over.
+ *
+ * Both `sk query` commands differ only in which query they ask for, so the
+ * wiring lives here rather than twice in the command layer — the two of them
+ * drifting apart is what left a diverged copy of the parameter query behind
+ * once already.
+ */
+export async function runQuery(queryType, customerPath, flags, config) {
+    const service = await new QueryBuilderFactory({
+        bySet: flags.bySet,
+        configName: flags.configName,
+        count: flags.count,
+        customerPath,
+        days: flags.days,
+        devices: normalizeDevices(flags.device),
+        excludeNotFound: flags.excludeNotFound,
+        excludeNoindex: flags.excludeNoindex,
+        excludeSuspicious: flags.excludeSuspicious,
+        execute: flags.execute,
+        explain: flags.explain,
+        hardNavigationsOnly: flags.hardNavigationsOnly,
+        isWindows: config.windows,
+        limit: flags.limit,
+        match: flags.match,
+        minHits: flags.minHits,
+        minImpressions: flags.minImpressions,
+        quiet: flags.quiet,
+        variations: flags.variation,
+        workgroup: flags.workgroup,
+    }, new CliConfig(config).load()).buildService(queryType);
+    await service.run();
+}

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

@@ -0,0 +1,8 @@
+export * from "./match-pattern.js";
+export * from "./pattern-language.js";
+export * from "./rule-model.js";
+export * from "./rule-parser.js";
+export * from "./rule-reducer.js";
+export * from "./rule-relevance.js";
+export * from "./rule-to-sql.js";
+export * from "./strip-parameters.js";

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

@@ -0,0 +1,8 @@
+export * from "./match-pattern.js";
+export * from "./pattern-language.js";
+export * from "./rule-model.js";
+export * from "./rule-parser.js";
+export * from "./rule-reducer.js";
+export * from "./rule-relevance.js";
+export * from "./rule-to-sql.js";
+export * from "./strip-parameters.js";

package/dist/services/query-builder/rules/match-pattern.d.ts

@@ -0,0 +1,51 @@
+import { NormalizedRule } from "./rule-model.js";
+/**
+ * An ad-hoc narrowing of a query, given on the command line as a regular
+ * expression over the path.
+ *
+ * It is compiled into the same shape a config rule has, so everything that
+ * follows — the check against the config, the translation to SQL, the
+ * warnings about constructs Athena reads differently — is the code that
+ * already runs for the config's own rules, and the pattern cannot come to
+ * mean something else here than it would in a config.
+ *
+ * The imports here are deliberately kept to the leaves of the rule layer: the
+ * flag definitions load this module, and pulling the automata library into
+ * every `sk` invocation to validate a pattern would be a poor trade.
+ */
+/** Where a `--match` pattern shows up in reports and errors. */
+export declare const MATCH_SOURCE = "--match";
+/**
+ * Compiles one `--match` value into a regular expression.
+ *
+ * Athena carries flags inside the pattern and JavaScript carries them beside
+ * it. The operator writes the Athena form, so a leading `(?i)` is lifted into
+ * real flags here — `new RegExp('(?i)…')` would throw — and `toAthenaRegex`
+ * puts it back when the pattern is emitted.
+ *
+ * @throws SyntaxError when the value is not a regular expression.
+ */
+export declare function parseMatchPattern(value: string): RegExp;
+/**
+ * The `--match` patterns as a rule: one condition on the pathname, its
+ * entries OR'd, so `--match a --match b` keeps the pages matching either.
+ */
+export declare function buildMatchRule(values: readonly string[] | undefined): NormalizedRule | undefined;
+/**
+ * An excluding rule restated over `path + search`, so that it can be held
+ * against a `--match` pattern — or `undefined` when it cannot be restated
+ * exactly.
+ *
+ * A version 2 `pathname` condition is matched against the path alone, a
+ * version 1 one against the path with its query string, and the reduction
+ * never compares patterns across those two subjects. Since a `--match`
+ * pattern is a version 1 condition, a version 2 rule has to be said again in
+ * that subject before the two can be compared at all.
+ *
+ * This one is used to prove that a pattern is **entirely excluded**, so the
+ * safe direction is the opposite of the usual: a rule restated wider than it
+ * is would refuse a pattern that does have pages. Anything that cannot be
+ * restated exactly is therefore left out of the comparison altogether, and
+ * missing an exclusion only costs the early break.
+ */
+export declare function asPathWithSearchRule(rule: NormalizedRule): NormalizedRule | undefined;

package/dist/services/query-builder/rules/match-pattern.js

@@ -0,0 +1,141 @@
+import { escapeRegexLiteral } from "../sql/regex.js";
+import { matchesExactly, } from "./rule-model.js";
+/**
+ * An ad-hoc narrowing of a query, given on the command line as a regular
+ * expression over the path.
+ *
+ * It is compiled into the same shape a config rule has, so everything that
+ * follows — the check against the config, the translation to SQL, the
+ * warnings about constructs Athena reads differently — is the code that
+ * already runs for the config's own rules, and the pattern cannot come to
+ * mean something else here than it would in a config.
+ *
+ * The imports here are deliberately kept to the leaves of the rule layer: the
+ * flag definitions load this module, and pulling the automata library into
+ * every `sk` invocation to validate a pattern would be a poor trade.
+ */
+/** Where a `--match` pattern shows up in reports and errors. */
+export const MATCH_SOURCE = "--match";
+/**
+ * A `--match` pattern is a version 1 `pathname` condition, whatever version
+ * the config runs under: version 1 matches a pathname against the path *and*
+ * the query string, which is the subject an operator narrowing a list wants —
+ * `^/p/` anchors at the start of the path and `[?&]size=` reaches a
+ * parameter.
+ */
+const MATCH_RULE_SET_VERSION = 1;
+/** Inline flags, the way Athena takes them: `(?i)`, `(?is)`, … */
+const INLINE_FLAGS = /^\(\?([ims]+)\)/;
+/**
+ * Compiles one `--match` value into a regular expression.
+ *
+ * Athena carries flags inside the pattern and JavaScript carries them beside
+ * it. The operator writes the Athena form, so a leading `(?i)` is lifted into
+ * real flags here — `new RegExp('(?i)…')` would throw — and `toAthenaRegex`
+ * puts it back when the pattern is emitted.
+ *
+ * @throws SyntaxError when the value is not a regular expression.
+ */
+export function parseMatchPattern(value) {
+    const inline = INLINE_FLAGS.exec(value);
+    return inline
+        ? new RegExp(value.slice(inline[0].length), inline[1])
+        : new RegExp(value);
+}
+/**
+ * The `--match` patterns as a rule: one condition on the pathname, its
+ * entries OR'd, so `--match a --match b` keeps the pages matching either.
+ */
+export function buildMatchRule(values) {
+    if (!values || values.length === 0) {
+        return undefined;
+    }
+    const patterns = values.map((value) => ({
+        kind: "regexp",
+        value: parseMatchPattern(value),
+    }));
+    const condition = { patterns, subject: "pathname" };
+    return {
+        conditions: [condition],
+        criteriaOutsideTheUrl: [],
+        matchesNothing: false,
+        ruleSetVersion: MATCH_RULE_SET_VERSION,
+        source: MATCH_SOURCE,
+    };
+}
+/**
+ * An excluding rule restated over `path + search`, so that it can be held
+ * against a `--match` pattern — or `undefined` when it cannot be restated
+ * exactly.
+ *
+ * A version 2 `pathname` condition is matched against the path alone, a
+ * version 1 one against the path with its query string, and the reduction
+ * never compares patterns across those two subjects. Since a `--match`
+ * pattern is a version 1 condition, a version 2 rule has to be said again in
+ * that subject before the two can be compared at all.
+ *
+ * This one is used to prove that a pattern is **entirely excluded**, so the
+ * safe direction is the opposite of the usual: a rule restated wider than it
+ * is would refuse a pattern that does have pages. Anything that cannot be
+ * restated exactly is therefore left out of the comparison altogether, and
+ * missing an exclusion only costs the early break.
+ */
+export function asPathWithSearchRule(rule) {
+    // A version 1 rule already matches the subject the pattern is written for.
+    if (!matchesExactly(rule.ruleSetVersion)) {
+        return rule;
+    }
+    const conditions = [];
+    for (const condition of rule.conditions) {
+        // A rule constraining anything but the path cannot cover the pattern in
+        // the first place — the reduction checks that before it builds automata.
+        if (condition.subject !== "pathname") {
+            return undefined;
+        }
+        const patterns = [];
+        for (const pattern of condition.patterns) {
+            const restated = withSearch(pattern);
+            if (!restated) {
+                return undefined;
+            }
+            patterns.push(restated);
+        }
+        conditions.push({ patterns, subject: "pathname" });
+    }
+    return { ...rule, conditions, ruleSetVersion: MATCH_RULE_SET_VERSION };
+}
+/** What may follow the path in `path + search`. */
+const SEARCH = String.raw `(?:\?[\s\S]*)?`;
+/** Anything but a single `$` at the very end. */
+const INNER_END_ANCHOR = /(?<!\\)\$(?!$)/;
+/**
+ * One entry of a version 2 path condition, said over `path + search`.
+ *
+ * Only the shapes whose meaning is unchanged by the query string are
+ * restated. A pattern anchored at the start says the same thing about both
+ * subjects; where it ends at the end of the path, the query string is spelled
+ * out instead. An unanchored pattern does not survive: it would match inside
+ * a query string the path never contained.
+ */
+function withSearch(pattern) {
+    if (pattern.kind === "string") {
+        // A version 2 string is the whole path, compared case-insensitively.
+        const value = escapeRegexLiteral(pattern.value);
+        return { kind: "regexp", value: new RegExp(`^${value}${SEARCH}$`, "i") };
+    }
+    const { flags, source } = pattern.value;
+    // An alternation may hide an anchor in a branch, which the reasoning below
+    // does not see.
+    if (!source.startsWith("^") || source.includes("|")) {
+        return undefined;
+    }
+    if (INNER_END_ANCHOR.test(source)) {
+        return undefined;
+    }
+    return {
+        kind: "regexp",
+        value: /(?<!\\)\$$/.test(source)
+            ? new RegExp(`${source.slice(0, -1)}${SEARCH}$`, flags)
+            : pattern.value,
+    };
+}

package/dist/services/query-builder/rules/pattern-language.d.ts

@@ -0,0 +1,59 @@
+import { DFA, NFA } from "refa";
+import { RuleCondition } from "./rule-model.js";
+/**
+ * The set of subjects a condition accepts, as a finite automaton.
+ *
+ * Deciding whether one rule makes another redundant means deciding whether one
+ * pattern's language contains or avoids another's — a question about regular
+ * languages, not about strings, so it is answered with automata rather than
+ * guessed. `refa` builds them from the very same JavaScript patterns the config
+ * uses.
+ */
+export type ConditionLanguage = NFA;
+/**
+ * Which side of the true language an automaton is allowed to fall on.
+ *
+ * Automata cannot express an assertion — a word boundary, or the `$` inside
+ * `/^\/shop(\/|$)/` — so a pattern using one is approximated. Approximating in
+ * an arbitrary direction would let the reducer drop a rule that does matter,
+ * so each question is asked with the bound that makes its answer sound:
+ *
+ * - `atLeast` accepts everything the pattern accepts, and possibly more. Two
+ *   of these sharing nothing proves the patterns share nothing.
+ * - `atMost` accepts only what the pattern accepts, and possibly less. An
+ *   `atLeast` language inside an `atMost` one proves containment.
+ *
+ * A pattern without assertions has one exact language, and both bounds are it.
+ */
+export type LanguageBound = "atLeast" | "atMost";
+/**
+ * The language of one condition — the union of its entries, since one matching
+ * entry satisfies the condition.
+ *
+ * Returns `undefined` when an entry has no automaton at all, and the caller
+ * then leaves the rule out of every reduction.
+ */
+export declare function conditionLanguage(condition: RuleCondition, ruleSetVersion: number, bound: LanguageBound): ConditionLanguage | undefined;
+/**
+ * Everything a language does *not* accept.
+ *
+ * Determinising a language to complement it is the expensive step of the whole
+ * reduction, and one rule is compared with many others, so a caller that asks
+ * repeatedly should build this once and reuse it.
+ */
+export type LanguageOutside = DFA;
+/** The complement of an `atMost` language. */
+export declare function outsideOf(language: ConditionLanguage): LanguageOutside | undefined;
+/**
+ * True when the language stays inside the one `outside` was built from —
+ * `language ⊆ superset ⟺ language ∩ ¬superset = ∅`.
+ *
+ * @param language - has to be an `atLeast` language.
+ * @param outside - has to come from {@link outsideOf} on an `atMost` language.
+ */
+export declare function isInside(language: ConditionLanguage, outside: LanguageOutside): boolean | undefined;
+/**
+ * True when no subject is accepted by both languages. Both have to be
+ * `atLeast` languages.
+ */
+export declare function languagesDisjoint(left: ConditionLanguage, right: ConditionLanguage): boolean | undefined;