@remotex-labs/xbuild 2.5.0 → 3.0.0

package/dist/bash.d.ts

@@ -3,3 +3,3138 @@
  * DO NOT EDIT MANUALLY.
  */
 
+import { BuildOptions, BuildResult, Loader, Message, Metafile, OnLoadArgs, OnLoadResult, OnResolveArgs, OnResolveResult, OnStartResult, PartialMessage, Platform, PluginBuild } from 'esbuild';
+import { NextType, Observable, ObserverInterface, UnsubscribeType } from '@remotex-labs/xobservable';
+import { Options } from 'yargs';
+import { Stats } from 'fs';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Runs a whole configuration - every variant it declares, in the order their dependencies allow.
+ *
+ * @remarks
+ * Owns the configuration for a run and the event stream the variants report on,
+ * while each variant owns the build it runs.
+ * A variant is constructed for every entry the configuration declares and reused from then on,
+ * so re-reading an edited configuration adds what it gained and leaves the rest running.
+ *
+ * @example
+ * ```ts
+ * const build = new BuildService(config, { watch: true });
+ * build.subscribe(event => event.type); // 'start', then 'end'
+ *
+ * const results = await build.build();
+ * results.length; // 2 - one per variant
+ * ```
+ *
+ * @see VariantService
+ * @see ConfigurationInterface
+ *
+ * @since 3.0.0
+ */
+declare class BuildService {
+    private argv;
+    /**
+     * The stream every variant reports its start and end on.
+     *
+     * @remarks
+     * Handed to each variant as it is constructed, so one stream carries the whole run
+     * rather than a reader subscribing to each variant in turn.
+     * Kept private and reached through `pipe` and `subscribe`,
+     * which is what keeps a reader from pushing an event of its own onto it.
+     *
+     * @see LifecycleEventsType
+     * @since 3.0.0
+     */
+    private readonly events$;
+    /**
+     * The configuration service this run reads and writes through.
+     *
+     * @remarks
+     * The injected instance rather than one of its own, and the same instance every variant selects from,
+     * so a change written here reaches the variants without being handed to them.
+     *
+     * @see ConfigurationService
+     * @since 3.0.0
+     */
+    private readonly config$;
+    /**
+     * Applies a configuration and constructs a variant for every entry it declares.
+     *
+     * @param config - Configuration to run, merged over whatever the service already holds
+     * @param argv - Parsed command line the build was started with, empty when the caller passes none
+     *
+     * @remarks
+     * The configuration is patched rather than put in place of what is there,
+     * so the built-in defaults survive underneath what a configuration file states.
+     * The subscription that follows is called at once with the merged configuration,
+     * which is what constructs the variants before the constructor returns,
+     * and it keeps them current with every later change.
+     *
+     * @example
+     * ```ts
+     * const build = new BuildService({ logLevel: 'warning', variants: { esm } }, { watch: true });
+     * ```
+     *
+     * @see ConfigurationService.patch
+     * @since 3.0.0
+     */
+    constructor(config: ConfigurationInterface, argv?: Record<string, unknown>);
+    /**
+     * The event stream's `pipe`, bound to the stream.
+     *
+     * @remarks
+     * Hands out the operator chain without handing out the subject,
+     * so a reader composes on the run's events and cannot report one of its own.
+     *
+     * @example
+     * ```ts
+     * const ended = build.pipe(filter(event => event.type === 'end'));
+     * ended.subscribe(report);
+     * ```
+     *
+     * @see BuildService.subscribe
+     * @since 3.0.0
+     */
+    get pipe(): typeof this.events$.pipe;
+    /**
+     * The event stream's `subscribe`, bound to the stream.
+     *
+     * @remarks
+     * The plain way to watch a run, for a reader wanting every event rather than a filtered view.
+     * Answers with the handle that ends the subscription, as the stream's own `subscribe` does.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = build.subscribe(event => event.type); // 'start', then 'end'
+     * unsubscribe();
+     * ```
+     *
+     * @see BuildService.pipe
+     * @since 3.0.0
+     */
+    get subscribe(): typeof this.events$.subscribe;
+    /**
+     * Starts the configuration again from the one this service was constructed with.
+     *
+     * @param config - Configuration to apply over the initial one
+     *
+     * @remarks
+     * Reloads rather than patches, so whatever accumulated since construction is dropped,
+     * and only the initial configuration survives underneath.
+     * That is what re-reading an edited file wants, since patching a list would extend it rather than replace it.
+     * Assigning is also what ends a variant,
+     * since one the new configuration no longer declares disposes of itself as the change reaches it.
+     *
+     * @example
+     * ```ts
+     * build.configuration = { common: { esbuild: { minify: false } } };
+     * ```
+     *
+     * @see ConfigurationService.reload
+     * @since 3.0.0
+     */
+    set configuration(config: DeepPartialType<ConfigurationInterface>);
+    /**
+     * Builds the variants named, or every variant the configuration declares, in the order `dependOn` asks for.
+     *
+     * @param names - Variants to build, building every variant the configuration declares when omitted
+     * @returns One result per variant asked for, in the order they were named
+     * @throws xBuildError - When a `dependOn` chain closes on itself, or names a variant that does not exist
+     *
+     * @remarks
+     * Naming variants builds those and whatever they wait for, leaving everything else alone.
+     * A name no variant answers to is passed over rather than reported as an error,
+     * so a list naming nothing this configuration declares builds nothing at all.
+     * A dependency built along the way reports on the event stream like any other build
+     * while staying out of the results, which carry the variants that were asked for.
+     * The whole graph is wired before any variant runs, and every variant waits on the same gate,
+     * so a chain that turns out to be broken builds nothing at all rather than part of the output.
+     * A variant that several others depend on is built once and its result shared,
+     * since the graph is walked through a cache keyed by name.
+     * A build that fails does not reject here - its errors arrive on its own result.
+     * A dependency counts as failed where it produced no output, whether it threw or only reported errors.
+     * The variant waiting on it is skipped rather than built,
+     * and the result {@link skipped} shapes carries no output either, so its own dependents skip in turn.
+     *
+     * @example
+     * ```ts
+     * const results = await build.build();
+     * results.length; // 2 - the types variant first, then the bundle that depends on it
+     *
+     * const [ app ] = await build.build([ 'app' ]); // types builds too, since app waits for it
+     * await build.build([ 'umd' ]);                 // [] - no variant answers to the name
+     * ```
+     *
+     * @see BuildResultInterface
+     * @since 3.0.0
+     */
+    build(names?: Array<string>): Promise<Array<BuildResultInterface>>;
+    /**
+     * Type-checks the variants named, or every variant the configuration declares, without building any of them.
+     *
+     * @param names - Variants to check, checking every variant the configuration declares when omitted
+     * @returns The messages each variant's check reported, keyed by the variant's name
+     *
+     * @remarks
+     * The variants are checked one at a time rather than together,
+     * since every variant carries a TypeScript program of its own.
+     * Each variant answers with the buckets a build would file its messages under,
+     * so a diagnostic reads at the level the configuration gives it rather than in the compiler's own shape.
+     * A variant that checks clean is present with its buckets empty rather than left out,
+     * so a reader tells a clean variant from one that was never checked.
+     * Only the variants named are checked, dependencies among them or not,
+     * since a variant is checked against the files its own build reaches,
+     * and what another variant reaches is that variant's own to report.
+     * A name is matched against the variants rather than looked up,
+     * so one no variant answers to is passed over,
+     * and a list naming nothing this configuration declares checks nothing at all.
+     *
+     * @example
+     * ```ts
+     * const { esm } = await build.typeChack();
+     * esm.error.length; // 0 - nothing to report
+     *
+     * await build.typeChack([ 'esm' ]); // { esm: { ... } } - cjs is left alone
+     * await build.typeChack([ 'umd' ]); // {} - no variant answers to the name
+     * ```
+     *
+     * @see LifecycleLogsType
+     * @since 3.0.0
+     */
+    typeChack(names?: Array<string>): Promise<Record<string, LifecycleLogsType>>;
+    /**
+     * Re-reads the TypeScript configuration from disk.
+     *
+     * @remarks
+     * Reparses the configuration so a later check or build reads it as it now stands,
+     * which is what a watch cycle needs after an edit to `tsconfig.json`.
+     * The list of files reparsed is dropped rather than passed on, so a caller learns only that the reparse ran.
+     * Nothing here waits on anything, so the promise settles at once.
+     *
+     * @example
+     * ```ts
+     * await build.reload(); // the TypeScript configuration is read again
+     * ```
+     *
+     * @see TypescriptService.reload
+     * @since 3.0.0
+     */
+    reload(): Promise<void>;
+    /**
+     * Constructs a variant for every entry the configuration declares.
+     *
+     * @param config - Configuration as it now stands
+     * @throws xBuildError - When there is no configuration to read variants from
+     *
+     * @remarks
+     * A name that already has a variant is passed over,
+     * so re-reading a configuration adds what it gained
+     * and leaves the variants it kept running rather than replacing them.
+     * Nothing is removed here,
+     * since a variant the configuration stopped declaring watches its own entry and disposes of itself.
+     *
+     * @see VariantService
+     * @since 3.0.0
+     */
+    private parseVariants;
+    /**
+     * Shapes the result of a variant that was skipped rather than run and reports it as an end.
+     *
+     * @param name - Variant that was not built
+     * @param dependencies - Names of the dependencies that failed, in the order the variant declared them
+     * @returns A result carrying one error naming them, and nothing at any other level
+     *
+     * @remarks
+     * Shaped as a build result rather than as a thrown error,
+     * so a skipped variant reads like a failed one to whatever reports the run.
+     * It carries no metafile, which is what makes its own dependents skip in turn,
+     * since a dependency that produced no output is what the graph reads as a failure.
+     * Nothing was compiled, so every bucket but `errors` comes back empty.
+     * The result is built from the buckets the context carries rather than from a second literal,
+     * so a level cannot be named in one and missing from the other,
+     * and a reader of the event and a reader of the result are looking at the same messages.
+     * The same result goes out on the event stream as an end,
+     * since a variant that never ran reports no end of its own.
+     * A reader would otherwise see the run finish, with one variant missing from the count.
+     * The context is assembled here rather than taken from a build,
+     * so its options are the ones the configuration states, and its duration is zero.
+     *
+     * @example
+     * ```ts
+     * const { errors } = this.skipped('app', [ 'types' ]);
+     * errors[0].text; // 'Variant "app" was not built, because "types" failed'
+     * ```
+     *
+     * @see BuildResultInterface
+     * @since 3.0.0
+     */
+    private skipped;
+    /**
+     * Returns the variants one variant waits for.
+     *
+     * @param name - Variant whose dependencies are wanted
+     * @returns The names it depends on, empty when it depends on none
+     *
+     * @remarks
+     * Read from the configuration as it stands rather than from a copy taken when the run began.
+     * A single name is flattened into a list, so both forms `dependOn` accepts read the same way here.
+     *
+     * @see VariantConfigurationInterface
+     * @since 3.0.0
+     */
+    private getDependOn;
+}
+/**
+ * The messages a build has collected, filed under the level each was reported at.
+ *
+ * @remarks
+ * Keyed by every level but `silent`, since a message reported at `silent` is dropped rather than kept.
+ * Each bucket holds esbuild messages in the order they arrived,
+ * so a reporter reads the level it cares about instead of filtering the rest out itself.
+ *
+ * @example
+ * ```ts
+ * const logs: LifecycleLogsType = { debug: [], info: [], warning: [], error: [] };
+ * logs.error.length; // 0 - nothing has failed yet
+ * ```
+ *
+ * @see LogLevelType
+ * @see PartialMessage
+ *
+ * @since 3.0.0
+ */
+type LifecycleLogsType = Record<Exclude<LogLevelType, 'silent'>, Array<PartialMessage>>;
+/**
+ * The scratch state the hooks of a single build share.
+ *
+ * @remarks
+ * Reset at the start of every build, with the time it began stamped and its two sets empty,
+ * so nothing carries over from the build before it.
+ * The index signature is what lets one hook leave a value behind for a later one to read.
+ *
+ * @example
+ * ```ts
+ * context.stage.startTime;      // when this build began
+ * context.stage.loaded = 12;    // read back in a later hook
+ * ```
+ *
+ * @see LifecycleContextInterface
+ * @since 2.0.0
+ */
+interface LifecycleStageInterface {
+    /**
+     * When the build began.
+     *
+     * @remarks
+     * Stamped as the build starts and left alone afterward,
+     * so a hook needing an elapsed time subtracts it rather than timing the build itself.
+     *
+     * @example
+     * ```ts
+     * Date.now() - context.stage.startTime.getTime(); // 1284
+     * ```
+     *
+     * @since 2.0.0
+     */
+    startTime: Date;
+    /**
+     * The names of the macro bindings in this build are to drop.
+     *
+     * @remarks
+     * What {@link analyzeMacros} collected from the build's inputs, left here for the stages that run after it,
+     * so a hook rewriting a source reads the set rather than analyzing the file for itself.
+     * Empty when no input declares a conditional macro.
+     *
+     * @example
+     * ```ts
+     * context.stage.dropped.has('$$dev'); // true - its flag resolved to 'false'
+     * ```
+     *
+     * @see analyzeMacros
+     * @since 3.0.0
+     */
+    dropped: Set<string>;
+    /**
+     * The inputs this build reaches, as the dependency scan named them.
+     *
+     * @remarks
+     * The setup stage collects them from a scan of the entry points with the plugins stripped,
+     * so a hook needing the whole input list reads the set rather than walking the graph itself.
+     * {@link analyzeMacros} reads the same set,
+     * which is what resolves a conditional binding against every file the build reaches.
+     * Filled for a bundled build and an unbundled one alike, and empty until the setup stage fills it.
+     *
+     * @example
+     * ```ts
+     * context.stage.reachableFiles.has('src/index.ts'); // true
+     * ```
+     *
+     * @see analyzeMacros
+     * @since 3.0.0
+     */
+    reachableFiles: Set<string>;
+    /**
+     * Any other value a hook chooses to leave on the stage.
+     *
+     * @remarks
+     * Typed as `unknown`, so whatever reads a key back narrows it before use.
+     *
+     * @example
+     * ```ts
+     * context.stage.loaded = 12;
+     * context.stage.loaded as number; // 12
+     * ```
+     *
+     * @since 2.0.0
+     */
+    [key: string]: unknown;
+}
+/**
+ * An esbuild build result, widened with the levels esbuild does not report on one.
+ *
+ * @remarks
+ * esbuild returns `errors` and `warnings` alone.
+ * The two fields beside them carry the messages collected at the quieter levels,
+ * so an end hook sees everything the build said and not only what failed it.
+ *
+ * @example
+ * ```ts
+ * const result: BuildResultInterface = { ...buildResult, info: [], debugs: [] };
+ * result.errors.length; // 0
+ * result.debugs.length; // 4
+ * ```
+ *
+ * @see BuildResultType
+ * @see EndContextInterface
+ *
+ * @since 3.0.0
+ */
+interface BuildResultInterface extends BuildResultType {
+    /**
+     * The messages this build reported at the `info` level.
+     *
+     * @remarks
+     * Carries no fault, so a reader printing a build summary shows these without treating the build as broken.
+     *
+     * @example
+     * ```ts
+     * result.info.length; // 3
+     * ```
+     *
+     * @since 3.0.0
+     */
+    info: Array<Message>;
+    /**
+     * The messages this build reported at the `debug` level.
+     *
+     * @remarks
+     * The quietest level, kept for a run asking to see it and ignored by everything else.
+     *
+     * @example
+     * ```ts
+     * result.debugs.map(message => message.text); // [ 'resolved src/index.ts' ]
+     * ```
+     *
+     * @since 3.0.0
+     */
+    verbose: Array<Message>;
+}
+/**
+ * What every hook of a build is handed, whichever stage it runs in.
+ *
+ * @remarks
+ * One object for the whole build, so a value a hook writes onto `stage` is still there for the next one.
+ * Everything beside `stage` describes the build itself:
+ * which variant it is, the options it runs under, the arguments that started it, and what it has reported so far.
+ *
+ * @example
+ * ```ts
+ * const lifecycle: LifecycleHooksInterface = {
+ *     onStart: ({ context }) => {
+ *         context.variantName;   // 'esm'
+ *         context.stage.count = 0;
+ *     }
+ * };
+ * ```
+ *
+ * @see LifecycleHooksInterface
+ * @see LifecycleStageInterface
+ *
+ * @since 3.0.0
+ */
+interface LifecycleContextInterface {
+    /**
+     * The arguments the build was started with.
+     *
+     * @remarks
+     * The parsed command line, so a hook follows a flag without reading `process.argv` itself.
+     *
+     * @example
+     * ```ts
+     * context.argv; // { watch: true, build: 'esm' }
+     * ```
+     *
+     * @since 2.0.0
+     */
+    argv: Record<string, unknown>;
+    /**
+     * The name of the variant being built.
+     *
+     * @remarks
+     * The key the variant is written under in the configuration,
+     * which is also what labels its messages and what the `--build` flag selects.
+     *
+     * @example
+     * ```ts
+     * context.variantName; // 'esm'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    variantName: string;
+    /**
+     * The esbuild options this build runs under.
+     *
+     * @remarks
+     * The common block and the variant are already merged,
+     * so it reads as what esbuild was given rather than as what the configuration file wrote.
+     *
+     * @example
+     * ```ts
+     * context.options.format; // 'esm'
+     * context.options.outdir; // 'dist/esm'
+     * ```
+     *
+     * @since 2.2.0
+     */
+    options: BuildOptions;
+    /**
+     * The messages this build has collected so far.
+     *
+     * @remarks
+     * Filled as the build runs, so a hook reading it early sees only what has been reported up to that point.
+     *
+     * @example
+     * ```ts
+     * context.logs.warning.length; // 2
+     * context.logs.error.length;   // 0 - nothing has failed yet
+     * ```
+     *
+     * @see LifecycleLogsType
+     * @since 3.0.0
+     */
+    logs: LifecycleLogsType;
+    /**
+     * The scratch state this build's hooks share.
+     *
+     * @remarks
+     * The one part of the context a hook is meant to write to, and the only one reset between builds.
+     *
+     * @example
+     * ```ts
+     * context.stage.startTime; // when this build began
+     * ```
+     *
+     * @see LifecycleStageInterface
+     * @since 2.0.0
+     */
+    stage: LifecycleStageInterface;
+    /**
+     * The level each esbuild message is reported at, keyed by its message id or by a pattern matching one.
+     *
+     * @remarks
+     * Lifts or lowers one message without moving the level everything else is reported at,
+     * and `silent` drops it rather than filing it under a bucket.
+     * The table is the one the configuration declared, read as written rather than in a form prepared for the build,
+     * so a hook inspecting it sees the keys a reader of the configuration file would.
+     * Each key is matched against a message id once per build and the outcome held,
+     * so an entry added while a build runs governs only the ids that the build has yet to report.
+     *
+     * @example
+     * ```ts
+     * context.overrides['unsupported-require-call']; // 'silent'
+     * ```
+     *
+     * @see LogOverridesType
+     * @since 3.0.0
+     */
+    overrides: LogOverridesType;
+}
+/**
+ * What an `onStart` hook is handed.
+ *
+ * @remarks
+ * Adds esbuild itself to the shared context, so a start hook can transform or build something of its own
+ * before the run it belongs to reads a file.
+ * It is the only stage given esbuild, since the ones after it run while the build is already under way.
+ *
+ * @example
+ * ```ts
+ * const onStart: LifecycleHooksInterface['onStart'] = async ({ esbuild, context }) => {
+ *     const out = await esbuild.transform('let a = 1', { minify: true });
+ *     out.code; // 'let a=1;\n'
+ * };
+ * ```
+ *
+ * @see LifecycleContextInterface
+ * @since 3.0.0
+ */
+interface StartContextInterface {
+    /**
+     * The esbuild module driving this build.
+     *
+     * @remarks
+     * The instance the build resolved, so a hook calling `transform` or `build` on it works against
+     * the same version rather than the one it imported for itself.
+     *
+     * @example
+     * ```ts
+     * const out = await esbuild.transform('let a = 1', { minify: true });
+     * out.code; // 'let a=1;\n'
+     * ```
+     *
+     * @since 3.0.0
+     */
+    esbuild: PluginBuild['esbuild'];
+    /**
+     * The context shared by every hook of this build.
+     *
+     * @remarks
+     * Already populated when a start hook runs, `stage` carrying the time the build began
+     * along with what the setup stage left on it.
+     *
+     * @example
+     * ```ts
+     * context.variantName; // 'esm'
+     * ```
+     *
+     * @see LifecycleContextInterface
+     * @since 3.0.0
+     */
+    context: LifecycleContextInterface;
+}
+/**
+ * What an `onEnd` or an `onSuccess` hook is handed.
+ *
+ * @remarks
+ * Adds the finished result and the time it took to the shared context.
+ * `onEnd` receives it. However, the build turned out `onSuccess` only when nothing failed,
+ * so a hook reading `buildResult.errors` is guarding the first case rather than the second.
+ *
+ * @example
+ * ```ts
+ * const onEnd: LifecycleHooksInterface['onEnd'] = ({ duration, buildResult }) => {
+ *     `${ buildResult.errors.length } errors in ${ duration }ms`; // '0 errors in 1284ms'
+ * };
+ * ```
+ *
+ * @see BuildResultInterface
+ * @see LifecycleContextInterface
+ *
+ * @since 3.0.0
+ */
+interface EndContextInterface {
+    /**
+     * The context shared by every hook of this build.
+     *
+     * @remarks
+     * Carries whatever the earlier stages left on `stage`, which is how an end hook reaches what they counted.
+     *
+     * @example
+     * ```ts
+     * context.stage.loaded; // 12
+     * ```
+     *
+     * @see LifecycleContextInterface
+     * @since 3.0.0
+     */
+    context: LifecycleContextInterface;
+    /**
+     * How long the build took, in milliseconds.
+     *
+     * @remarks
+     * Measured from `context.stage.startTime` to the moment the build finished,
+     * so a hook reports the figure rather than timing the build itself.
+     *
+     * @example
+     * ```ts
+     * duration; // 1284
+     * ```
+     *
+     * @since 3.0.0
+     */
+    duration: number;
+    /**
+     * The finished build, with every level of message it produced.
+     *
+     * @remarks
+     * esbuild's own result, widened with the quieter levels it does not return on one.
+     *
+     * @example
+     * ```ts
+     * buildResult.errors.length;   // 0
+     * buildResult.warnings.length; // 2
+     * ```
+     *
+     * @see BuildResultInterface
+     * @since 3.0.0
+     */
+    buildResult: BuildResultInterface;
+}
+/**
+ * What an `onLoad` hook is handed.
+ *
+ * @remarks
+ * Carries the contents and the loader as they stand at this point in the chain,
+ * so a hook returning a new pair of hands it to the hook after it rather than straight back to esbuild.
+ * Returning nothing leaves both as they are.
+ *
+ * @example
+ * ```ts
+ * const onLoad: LifecycleHooksInterface['onLoad'] = ({ args, contents, loader }) => {
+ *     args.path;                                 // '/src/index.ts'
+ *     return { contents: contents.trim(), loader };
+ * };
+ * ```
+ *
+ * @see LifecycleContextInterface
+ * @since 3.0.0
+ */
+interface LoadContextInterface {
+    /**
+     * The file esbuild is loading.
+     *
+     * @remarks
+     * Names the path and the namespace it is loaded under, along with anything a resolve hook attached to it.
+     *
+     * @example
+     * ```ts
+     * args.path;      // '/src/index.ts'
+     * args.namespace; // 'file'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    args: OnLoadArgs;
+    /**
+     * The loader the contents are to be read with.
+     *
+     * @remarks
+     * `undefined` until something in the chain names one,
+     * after which esbuild reads the contents as that language instead of inferring it from the extension.
+     *
+     * @example
+     * ```ts
+     * loader; // undefined - esbuild picks one from the extension
+     * ```
+     *
+     * @since 2.0.0
+     */
+    loader: Loader | undefined;
+    /**
+     * The context shared by every hook of this build.
+     *
+     * @remarks
+     * The same object on every file loaded, which is what makes `stage` a place to count them.
+     *
+     * @example
+     * ```ts
+     * context.variantName; // 'esm'
+     * ```
+     *
+     * @see LifecycleContextInterface
+     * @since 3.0.0
+     */
+    context: LifecycleContextInterface;
+    /**
+     * The source as it stands at this point in the chain.
+     *
+     * @remarks
+     * The file as it was read for the first hook, and whatever the hook before returned for the ones after it.
+     *
+     * @example
+     * ```ts
+     * contents.includes('export default'); // true
+     * ```
+     *
+     * @since 3.0.0
+     */
+    contents: string;
+}
+/**
+ * What an `onResolve` hook is handed.
+ *
+ * @remarks
+ * Carries the import as it was written and the file that wrote it,
+ * which is what a hook needs to point a path elsewhere, mark it externally, or move it into a namespace of its own.
+ * Returning nothing leaves the path to esbuild.
+ *
+ * @example
+ * ```ts
+ * const onResolve: LifecycleHooksInterface['onResolve'] = ({ args }) => {
+ *     if (!args.path.startsWith('node:')) return undefined;
+ *
+ *     return { path: args.path, external: true }; // left as an import in the output
+ * };
+ * ```
+ *
+ * @see LifecycleContextInterface
+ * @since 3.0.0
+ */
+interface ResolveContextInterface {
+    /**
+     * The import being resolved.
+     *
+     * @remarks
+     * Names the path as written, the file importing it, the directory a relative path resolves from,
+     * and the kind of import it came from.
+     *
+     * @example
+     * ```ts
+     * args.path;     // './utils'
+     * args.importer; // '/src/index.ts'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    args: OnResolveArgs;
+    /**
+     * The context shared by every hook of this build.
+     *
+     * @remarks
+     * The same object on every import resolved, so a hook deciding by variant reads `variantName` off it.
+     *
+     * @example
+     * ```ts
+     * context.variantName; // 'esm'
+     * ```
+     *
+     * @see LifecycleContextInterface
+     * @since 3.0.0
+     */
+    context: LifecycleContextInterface;
+}
+/**
+ * A build starting or finishing, tagged with which of the two it is.
+ *
+ * @remarks
+ * Discriminated on `type`, so narrowing on it gives the fields of the matching stage.
+ * The two per-build stages alone are in the union,
+ * since load and resolve fire once per file and have nothing to say about the build as a whole.
+ *
+ * @example
+ * ```ts
+ * const event: LifecycleEventsType = { type: 'end', context, duration: 1284, buildResult };
+ * event.type === 'end' && event.duration; // 1284
+ * ```
+ *
+ * @see EndContextInterface
+ * @see StartContextInterface
+ *
+ * @since 3.0.0
+ */
+type LifecycleEventsType = EndContextInterface & {
+    type: 'end';
+} | StartContextInterface & {
+    type: 'start';
+};
+/**
+ * The hooks a configuration attaches to a build.
+ *
+ * @remarks
+ * Every hook is optional, and each runs at one point of the build:
+ * `onStart` before any file is read, `onResolve` as each import is resolved, `onLoad` as each file is loaded,
+ * and `onEnd` once the build has finished.
+ * `onSuccess` takes the same context as `onEnd` and runs only when the build produced no errors.
+ *
+ * @example
+ * ```ts
+ * const lifecycle: LifecycleHooksInterface = {
+ *     onStart: ({ context }) => {
+ *         context.stage.loaded = 0;
+ *     },
+ *     onLoad: ({ context, contents, loader }) => ({
+ *         contents: contents.replaceAll('__DEV__', 'false'),
+ *         loader
+ *     }),
+ *     onEnd: ({ duration }) => {
+ *         `done in ${ duration }ms`; // 'done in 1284ms'
+ *     }
+ * };
+ * ```
+ *
+ * @see LifecycleContextInterface
+ * @since 3.0.0
+ */
+interface LifecycleHooksInterface {
+    /**
+     * Runs once the build has finished. However, it turned out.
+     *
+     * @remarks
+     * The place to report on a build or clean up after it, since it is handed the result and the elapsed time.
+     * Work that only makes sense when nothing failed belongs on `onSuccess` instead.
+     *
+     * @example
+     * ```ts
+     * onEnd: ({ duration, buildResult }) => {
+     *     `${ buildResult.errors.length } errors in ${ duration }ms`; // '0 errors in 1284ms'
+     * }
+     * ```
+     *
+     * @see EndContextInterface
+     * @since 3.0.0
+     */
+    onEnd?: (options: EndContextInterface) => MaybeVoidPromiseType<void>;
+    /**
+     * Runs once the build has finished with no errors.
+     *
+     * @remarks
+     * The same context as `onEnd`, narrowed to the case where nothing failed,
+     * so a hook publishing or deploying the output does not check `buildResult.errors` for itself.
+     *
+     * @example
+     * ```ts
+     * onSuccess: async ({ context }) => {
+     *     await publish(context.options.outdir); // 'dist/esm'
+     * }
+     * ```
+     *
+     * @see EndContextInterface
+     * @since 3.0.0
+     */
+    onSuccess?: (options: EndContextInterface) => MaybeVoidPromiseType<void>;
+    /**
+     * Runs before the build reads its first file.
+     *
+     * @remarks
+     * The place to prepare whatever the later stages read, since it runs once and before anything is resolved.
+     * Returning an `OnStartResult` reports errors or warnings against the build instead of throwing at it.
+     *
+     * @example
+     * ```ts
+     * onStart: ({ context }) => {
+     *     if (context.options.outdir) return undefined;
+     *
+     *     return { errors: [{ text: 'no outdir' }] }; // the build reports it and stops
+     * }
+     * ```
+     *
+     * @see StartContextInterface
+     * @since 3.0.0
+     */
+    onStart?: (options: StartContextInterface) => MaybeVoidPromiseType<OnStartResult>;
+    /**
+     * Runs as each file is read, before esbuild parses it.
+     *
+     * @remarks
+     * Handed the contents and the loader as they stand, and may return a new pair,
+     * which is how a hook rewrites a source or teaches the build an extension it does not know.
+     * Returning nothing leaves both untouched.
+     *
+     * @example
+     * ```ts
+     * onLoad: ({ contents, loader }) => ({
+     *     contents: contents.replaceAll('__DEV__', 'false'), // the next hook sees the replaced source
+     *     loader
+     * })
+     * ```
+     *
+     * @see LoadContextInterface
+     * @since 3.0.0
+     */
+    onLoad?: (options: LoadContextInterface) => MaybeUndefinedPromiseType<OnLoadResult>;
+    /**
+     * Runs as each import is resolved, before esbuild looks for it on disk.
+     *
+     * @remarks
+     * Returning a path takes the resolution over, whether to redirect it, mark it externally,
+     * or move it into a namespace the build serves itself.
+     * Returning nothing leaves esbuild to resolve it.
+     *
+     * @example
+     * ```ts
+     * onResolve: ({ args }) => args.path.startsWith('node:')
+     *     ? { path: args.path, external: true } // left as an import in the output
+     *     : undefined
+     * ```
+     *
+     * @see ResolveContextInterface
+     * @since 3.0.0
+     */
+    onResolve?: (options: ResolveContextInterface) => MaybeUndefinedPromiseType<OnResolveResult>;
+}
+/**
+ * A named set of lifecycle hooks, packaged so several can stand beside one another on one build.
+ *
+ * @remarks
+ * The hooks of {@link LifecycleHooksInterface}, with a name to report them under and two of its own.
+ * `onSetup` runs before every build of the variant,
+ * and it is the one place a plugin changes the options a build receives.
+ * `onDispose` runs once as the variant goes away.
+ * Reach for a plugin where the hooks are shared between builds or projects and want naming,
+ * and for `lifecycle` where they belong to a single configuration.
+ *
+ * @example
+ * ```ts
+ * const timing: LifecyclePluginInterface = {
+ *     name: 'timing',
+ *     onSetup: ({ options }) => {
+ *         options.minify = false; // this build runs unminified
+ *     },
+ *     onEnd: ({ duration }) => {
+ *         `done in ${ duration }ms`; // 'done in 1284ms'
+ *     }
+ * };
+ * ```
+ *
+ * @see LifecycleHooksInterface
+ * @see LifecycleContextInterface
+ *
+ * @since 3.0.0
+ */
+interface LifecyclePluginInterface extends LifecycleHooksInterface {
+    /**
+     * The name this plugin is known by.
+     *
+     * @remarks
+     * Labels the plugin wherever a build reports it,
+     * so a message coming out of one set of hooks names the set it came from.
+     *
+     * @example
+     * ```ts
+     * plugin.name; // 'timing'
+     * ```
+     *
+     * @since 3.0.0
+     */
+    name: string;
+    /**
+     * Runs before each build of the variant.
+     *
+     * @remarks
+     * Handed the context that the rest of the build's hooks share, while it is still open to change,
+     * so writing to `options` here decides the options esbuild receives.
+     * It runs on every build rather than once, which is what lets a watch cycle rebuild under different options.
+     * A hook that shapes the build belongs here, and one that only runs at its start belongs on `onStart`.
+     * Returning a promise holds the build until it settles.
+     *
+     * @example
+     * ```ts
+     * onSetup: ({ options, stage }) => {
+     *     options.minify = false; // this build runs unminified
+     *     stage.loaded = 0;       // every later hook of this build reads it back
+     * }
+     * ```
+     *
+     * @see LifecycleContextInterface
+     * @since 3.0.0
+     */
+    onSetup?: (setup: LifecycleContextInterface) => MaybeVoidPromiseType;
+}
+/**
+ * The severity a build message is reported under.
+ *
+ * @remarks
+ * `verbose` and `info` are for messages that carry no fault, `warning` and `error` for the ones that do,
+ * and `silent` drops the message instead of collecting it.
+ * The other four name the buckets a collected message is filed under,
+ * which is why the log record excludes `silent` from its keys.
+ *
+ * @example
+ * ```ts
+ * const level: LogLevelType = 'warning';
+ * ```
+ *
+ * @see LogOverridesType
+ * @since 3.0.0
+ */
+type LogLevelType = 'verbose' | 'info' | 'warning' | 'error' | 'silent';
+/**
+ * The level a message is reported under, keyed by the id it is reported with.
+ *
+ * @remarks
+ * A key is read as a whole id first, so an id written out verbatim stands for itself and is matched by name alone.
+ * A key carrying regular-expression syntax is read as an anchored pattern instead,
+ * which is how one entry can claim a family of ids.
+ * Verbatim keys win over patterns, and the first pattern a configuration declared wins over the ones after it.
+ *
+ * @example
+ * ```ts
+ * const overrides: LogOverridesType = {
+ *     'direct-eval': 'silent',   // this id alone
+ *     'TS-2\\d{3}': 'warning'    // every TypeScript diagnostic in the 2000 range
+ * };
+ * ```
+ *
+ * @see LogLevelType
+ * @see resolveLevel
+ *
+ * @since 3.0.0
+ */
+type LogOverridesType = Record<string, LogLevelType>;
+/**
+ * A copy of a type with every property optional, all the way down.
+ *
+ * @remarks
+ * Recurses into object properties rather than stopping at the top level,
+ * which is what lets a patch name one deeply nested setting and leave its siblings standing.
+ * It is the shape a partial update takes, not the shape anything is stored in.
+ *
+ * @example
+ * ```ts
+ * type Config = { common: { esbuild: { minify: boolean, outdir: string } } };
+ *
+ * const patch: DeepPartialType<Config> = { common: { esbuild: { minify: false } } };
+ * ```
+ *
+ * @since 2.0.0
+ */
+type DeepPartialType<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartialType<T[K]> : T[K];
+};
+/**
+ * Any value that is not an object.
+ *
+ * @remarks
+ * The whole set of primitives, `null` and `undefined` among them,
+ * so a value of this type compares with `===` and carries nothing worth walking.
+ *
+ * @example
+ * ```ts
+ * const port: PrimitiveType = 8080;
+ * const absent: PrimitiveType = null;
+ * ```
+ *
+ * @see PrimitiveOrObjectType
+ * @since 3.0.0
+ */
+type PrimitiveType = string | number | boolean | bigint | symbol | null | undefined;
+/**
+ * A function that supplies a value when the build runs rather than when it is configured.
+ *
+ * @remarks
+ * Receives the name it is producing a value for and the arguments the build was given,
+ * so a setting can follow a flag without the configuration file reading the command line itself.
+ * The result is primitive, since what it produces is substituted into the source as a literal.
+ *
+ * @example
+ * ```ts
+ * const release: RuntimeHandlerType = (name, args) => args.production === true;
+ * ```
+ *
+ * @see PrimitiveType
+ * @since 3.0.0
+ */
+type RuntimeHandlerType = (name: string, args: Record<string, unknown>) => PrimitiveType;
+/**
+ * A primitive, or a plain object keyed by name or symbol.
+ *
+ * @remarks
+ * Widens {@link PrimitiveType} to cover a value that is substituted whole rather than as a single literal.
+ *
+ * @example
+ * ```ts
+ * const flag: PrimitiveOrObjectType = true;
+ * const table: PrimitiveOrObjectType = { region: 'eu', retries: 3 };
+ * ```
+ *
+ * @see PrimitiveType
+ * @since 3.0.0
+ */
+type PrimitiveOrObjectType = PrimitiveType | object | Record<string | symbol, unknown>;
+/**
+ * What a hook returns when answering is optional.
+ *
+ * @typeParam T - The value a hook returns when it has one
+ *
+ * @remarks
+ * Accepts the value itself, `void`, or a promise of either,
+ * so a hook can be written synchronously or asynchronously and can decline to answer either way.
+ * `null` belongs to the union only where `T` names it, which is what the default `T = null` does,
+ * so the bare form describes a hook that never has an answer to give.
+ *
+ * @example
+ * ```ts
+ * const onStart: () => MaybeVoidPromiseType<OnStartResult> = () => undefined;
+ * const onStartAsync: () => MaybeVoidPromiseType<OnStartResult> = async () => ({ warnings: [] });
+ * const setup: () => MaybeVoidPromiseType = () => null;
+ * ```
+ *
+ * @see MaybeUndefinedPromiseType
+ * @since 3.0.0
+ */
+type MaybeVoidPromiseType<T = null> = void | T | Promise<void | T>;
+/**
+ * The same as {@link MaybeVoidPromiseType}, for a hook whose empty answer is `undefined`.
+ *
+ * @remarks
+ * Used where esbuild reads the absence of a result as "carry on with the default",
+ * which its load and resolve callbacks spell as `undefined` rather than as `void`.
+ *
+ * @example
+ * ```ts
+ * const onLoad: () => MaybeUndefinedPromiseType<OnLoadResult> = () => undefined;
+ * ```
+ *
+ * @see MaybeVoidPromiseType
+ * @since 2.0.0
+ */
+type MaybeUndefinedPromiseType<T> = undefined | null | T | Promise<undefined | null | T>;
+/**
+ * The result shape every build helper in this package returns.
+ *
+ * @remarks
+ * Each helper fixes `metafile: true` after the caller's options, so a metafile is always there at runtime.
+ * The type does not say so, since esbuild only drops the `undefined` from `metafile` when the options it is given
+ * carry the literal `true`, which `BuildOptions & Metafile` does not.
+ * A caller reading the field therefore still asserts it.
+ *
+ * @example
+ * ```ts
+ * const result: BuildResultType = await buildFiles({ entryPoints: [ 'src/index.ts' ] });
+ * Object.keys(result.metafile!.inputs); // [ 'src/index.ts' ]
+ * ```
+ *
+ * @see buildFiles
+ * @since 3.0.0
+ */
+type BuildResultType = BuildResult<BuildOptions & Metafile>;
+/**
+ * The esbuild options a configuration is allowed to state.
+ *
+ * @remarks
+ * esbuild's own options, less the ones this package assembles itself.
+ * Plugins, defines, banners, footers, and the two logging settings are all built from the fields beside `esbuild`,
+ * so a build has a single place to state each of them and no way to state one twice.
+ *
+ * @example
+ * ```ts
+ * const options: EsbuildOptionsType = { minify: true, format: 'esm', target: 'node20' };
+ * ```
+ *
+ * @see BaseConfigurationInterface
+ * @since 3.0.0
+ */
+type EsbuildOptionsType = Omit<BuildOptions, 'plugins' | 'define' | 'banner' | 'footer' | 'logOverride' | 'logLevel'>;
+/**
+ * Code injected into the output, either written out or produced when the build runs.
+ *
+ * @remarks
+ * A string is injected as it stands, while a function is called at build time and its result injected instead,
+ * which is what lets a banner carry a version or a timestamp the configuration file cannot know.
+ *
+ * @example
+ * ```ts
+ * const fixed: InjectableCodeType = '#!/usr/bin/env node';
+ * const dynamic: InjectableCodeType = (name, args) => args.production === true;
+ * ```
+ *
+ * @see RuntimeHandlerType
+ * @since 3.0.0
+ */
+type InjectableCodeType = string | RuntimeHandlerType;
+/**
+ * How declaration files are emitted for a build that wants more than on or off.
+ *
+ * @remarks
+ * The long form of `declaration`, reached only when the plain boolean will not do.
+ *
+ * @example
+ * ```ts
+ * const declaration: DeclarationOptionsInterface = { outDir: 'types' };
+ * ```
+ *
+ * @see BaseConfigurationInterface
+ * @since 2.0.0
+ */
+interface DeclarationOptionsInterface {
+    /**
+     * Directory the declarations are written to.
+     *
+     * @remarks
+     * Overrides what the TypeScript configuration would have chosen, so declarations can land apart from the code
+     * without editing `tsconfig.json`.
+     *
+     * @example
+     * ```ts
+     * { outDir: 'types' } // dist/index.js beside types/index.d.ts
+     * ```
+     *
+     * @since 2.0.0
+     */
+    outDir?: string;
+}
+/**
+ * How type checking behaves for a build that wants more than on or off.
+ *
+ * @remarks
+ * The long form of `types`, reached only when the plain boolean will not do.
+ *
+ * @example
+ * ```ts
+ * const types: TypeCheckOptionsInterface = { failOnError: true };
+ * ```
+ *
+ * @see BaseConfigurationInterface
+ * @since 2.0.0
+ */
+interface TypeCheckOptionsInterface {
+    /**
+     * Whether a type error stops the build rather than only being reported.
+     *
+     * @remarks
+     * Left off, a build carries on and emits despite the errors, which suits a watch cycle where the report is enough.
+     *
+     * @example
+     * ```ts
+     * { failOnError: true } // a type error fails the run
+     * ```
+     *
+     * @since 2.0.0
+     */
+    failOnError?: boolean;
+}
+/**
+ * The settings a build understands, shared by the common block and every variant.
+ *
+ * @remarks
+ * Every field is optional here, so a variant states only what it changes and inherits the rest from `common`.
+ * The esbuild options it carries are stripped of the ones this package owns, since those are assembled from the
+ * fields beside them rather than passed through.
+ *
+ * @example
+ * ```ts
+ * const common: BaseConfigurationInterface = {
+ *     types: true,
+ *     declaration: { outDir: 'types' },
+ *     esbuild: { minify: true, target: 'esnext' }
+ * };
+ * ```
+ *
+ * @see VariantConfigurationInterface
+ * @since 3.0.0
+ */
+interface BaseConfigurationInterface {
+    /**
+     * Whether the build type-checks and how strictly.
+     *
+     * @remarks
+     * `true` checks and reports. The object form also decides whether an error stops the build.
+     *
+     * @example
+     * ```ts
+     * { types: true }                       // check and report
+     * { types: { failOnError: true } }      // check and fail on an error
+     * ```
+     *
+     * @see TypeCheckOptionsInterface
+     * @since 2.0.0
+     */
+    types?: boolean | TypeCheckOptionsInterface;
+    /**
+     * The hooks this configuration attaches to a build.
+     *
+     * @remarks
+     * One set per configuration, merged hook by hook with whatever `common` supplied,
+     * so a variant naming a hook replaces that hook alone and leaves the rest of the shared set standing.
+     * Where a build wants several named sets instead, `plugins` takes a list of them.
+     * {@link LifecycleHooksInterface} documents what each hook receives and when it runs.
+     *
+     * @example
+     * ```ts
+     * { lifecycle: { onEnd: ({ duration }) => report(duration) } }
+     * ```
+     *
+     * @see LifecycleHooksInterface
+     * @since 3.0.0
+     */
+    lifecycle?: LifecycleHooksInterface;
+    /**
+     * The plugins this configuration attaches to a build.
+     *
+     * @remarks
+     * Each is a named set of the same hooks that `lifecycle` takes, and the list applies in the order written.
+     * A variant appends to the list `common` supplied rather than replacing it,
+     * so a shared plugin runs ahead of the one a variant adds for itself.
+     *
+     * @example
+     * ```ts
+     * { plugins: [ timing, copyAssets ] } // timing first, then copyAssets
+     * ```
+     *
+     * @see LifecyclePluginInterface
+     * @since 3.0.0
+     */
+    plugins?: Array<LifecyclePluginInterface>;
+    /**
+     * Values substituted into the source wherever their name appears.
+     *
+     * @remarks
+     * A plain value is substituted as written, while a function is called at build time and its result substituted
+     * instead, so a substituted value can follow a flag.
+     *
+     * @example
+     * ```ts
+     * { define: { __VERSION: '1.0.0', __DEV: (name, args) => args.watch === true } }
+     * ```
+     *
+     * @see RuntimeHandlerType
+     * @since 3.0.0
+     */
+    define?: Record<string, PrimitiveOrObjectType | RuntimeHandlerType>;
+    /**
+     * Code placed at the top of each output file, keyed by the format it belongs to.
+     *
+     * @example
+     * ```ts
+     * { banner: { js: '#!/usr/bin/env node' } }
+     * ```
+     *
+     * @see InjectableCodeType
+     * @since 2.0.0
+     */
+    banner?: Record<string, InjectableCodeType>;
+    /**
+     * Code placed at the bottom of each output file, keyed by the format it belongs to.
+     *
+     * @example
+     * ```ts
+     * { footer: { js: '//# sourceMappingURL=index.js.map' } }
+     * ```
+     *
+     * @see InjectableCodeType
+     * @since 2.0.0
+     */
+    footer?: Record<string, InjectableCodeType>;
+    /**
+     * Severity to report a given esbuild message under.
+     *
+     * @remarks
+     * Keyed by esbuild's own message name, so a warning a project has decided to live with can be silenced without
+     * silencing the rest.
+     * A key carrying regular-expression syntax is read as an anchored pattern instead of as a name,
+     * which is how a family of messages is claimed by one entry.
+     *
+     * @example
+     * ```ts
+     * { logOverride: { 'direct-eval': 'silent' } }        // this message alone
+     * { logOverride: { 'TS-2\\d{3}': 'warning' } }         // every TypeScript diagnostic in the 2000 range
+     * ```
+     *
+     * @see LogOverridesType
+     * @since 3.0.0
+     */
+    logOverride?: LogOverridesType;
+    /**
+     * Whether declaration files are emitted and how.
+     *
+     * @remarks
+     * `true` emits them beside the code, following what the TypeScript configuration chose.
+     * The object form also decides where they land.
+     *
+     * @example
+     * ```ts
+     * { declaration: true }                     // beside the code
+     * { declaration: { outDir: 'types' } }      // apart from it
+     * ```
+     *
+     * @see DeclarationOptionsInterface
+     * @since 2.0.0
+     */
+    declaration?: boolean | DeclarationOptionsInterface;
+    /**
+     * esbuild options passed through to the bundler.
+     *
+     * @remarks
+     * Optional here, unlike on a variant, since the common block states what every variant starts from
+     * rather than a build of its own.
+     *
+     * @example
+     * ```ts
+     * { esbuild: { minify: true, format: 'esm', target: 'node20' } }
+     * ```
+     *
+     * @see EsbuildOptionsType
+     * @since 3.0.0
+     */
+    esbuild?: EsbuildOptionsType;
+}
+/**
+ * One named build, with everything it does not state inherited from the common block.
+ *
+ * @remarks
+ * The same settings as {@link BaseConfigurationInterface}, except that `esbuild` is required,
+ * since a variant exists to produce an output and needs at least the options describing it.
+ *
+ * @example
+ * ```ts
+ * const esm: VariantConfigurationInterface = {
+ *     esbuild: { format: 'esm', outdir: 'dist/esm' }
+ * };
+ * ```
+ *
+ * @see BaseConfigurationInterface
+ * @since 3.0.0
+ */
+interface VariantConfigurationInterface extends BaseConfigurationInterface {
+    /**
+     * Variants that must finish before this one starts.
+     *
+     * @remarks
+     * Names another variant, or several, so a build that consumes the output of an earlier one runs after it rather
+     * than beside it.
+     *
+     * @example
+     * ```ts
+     * { dependOn: 'types', esbuild: { outdir: 'dist' } }
+     * ```
+     *
+     * @since 2.0.0
+     */
+    dependOn?: string | Array<string>;
+    /**
+     * esbuild options this variant builds under.
+     *
+     * @remarks
+     * Required rather than optional, unlike on the common block, and merged over whatever `common` supplied.
+     *
+     * @example
+     * ```ts
+     * { esbuild: { format: 'cjs', outdir: 'dist/cjs' } }
+     * ```
+     *
+     * @see EsbuildOptionsType
+     * @since 3.0.0
+     */
+    esbuild: EsbuildOptionsType;
+}
+/**
+ * A whole xBuild configuration, as a configuration file, exports it.
+ *
+ * @remarks
+ * `variants` is what the build runs, one output per entry, while `common` is what each of them starts from.
+ * A configuration with a single variant is the ordinary case, several being for a package that ships more than one
+ * module format.
+ *
+ * @example
+ * ```ts
+ * const config: ConfigurationInterface = {
+ *     common: { types: true, esbuild: { minify: true } },
+ *     variants: {
+ *         esm: { esbuild: { format: 'esm', outdir: 'dist/esm' } },
+ *         cjs: { esbuild: { format: 'cjs', outdir: 'dist/cjs' } }
+ *     }
+ * };
+ * ```
+ *
+ * @see ConfigurationService
+ * @see VariantConfigurationInterface
+ *
+ * @since 3.0.0
+ */
+interface ConfigurationInterface {
+    /**
+     * Settings every variant inherits.
+     *
+     * @remarks
+     * Merged under each variant, so a variant naming the same setting wins and one that stays quiet takes this.
+     *
+     * @example
+     * ```ts
+     * { common: { types: true, esbuild: { minify: true } } }
+     * ```
+     *
+     * @see BaseConfigurationInterface
+     * @since 2.0.0
+     */
+    common?: BaseConfigurationInterface;
+    /**
+     * The builds to run, keyed by the name each is known by.
+     *
+     * @remarks
+     * The key names the variant in logs, in `dependOn`, and on the `--build` flag that selects one.
+     *
+     * @example
+     * ```ts
+     * { variants: { esm: { esbuild: { format: 'esm' } } } }
+     * ```
+     *
+     * @see VariantConfigurationInterface
+     * @since 3.0.0
+     */
+    variants: Record<string, VariantConfigurationInterface>;
+}
+/**
+ * A configuration with every top-level field optional.
+ *
+ * @remarks
+ * What a partly filled configuration is typed as, the built-in defaults among them,
+ * since those describe `common` alone and name no variants at all.
+ *
+ * @example
+ * ```ts
+ * const defaults: PartialConfigurationType = { common: { types: true } };
+ * ```
+ *
+ * @see ConfigurationInterface
+ * @since 3.0.0
+ */
+type PartialConfigurationType = Partial<ConfigurationInterface>;
+/**
+ * Turns what a run reports into what a terminal shows.
+ *
+ * @remarks
+ * Every event of a run arrives here: a build starting and ending, a server answering, a check reporting.
+ * Each one becomes a printed line, the groups of messages under it, and a word on the status line,
+ * so the scrollback carries the whole run while the bar carries only what is happening now.
+ * A singleton, since a run has one terminal and the level it reports at is read from every corner of it.
+ *
+ * @example
+ * ```ts
+ * const screen = inject(Screen, () => build.build());
+ * build.subscribe(screen.buildEvent.bind(screen));
+ *
+ * screen.toggleVerbose(); // 'verbose' - and the bar says so
+ * ```
+ *
+ * @see LifecycleEventsType
+ * @since 3.0.0
+ */
+declare class Screen {
+    private readonly build;
+    /**
+     * The configuration service the reporting level is read and written through.
+     *
+     * @remarks
+     * The injected instance rather than one of its own,
+     * so a level a key changes here is the level every other reader of the configuration sees.
+     *
+     * @example
+     * ```ts
+     * screen.config$.getValue().logLevel; // 'info'
+     * ```
+     *
+     * @see ConfigurationService
+     * @since 3.0.0
+     */
+    readonly config$: ConfigurationService<Required<import("../providers/interfaces/config-file-provider.interface").xBuildConfigInterface>>;
+    /**
+     * The address a running server answers on, absent while none is running.
+     *
+     * @remarks
+     * Written as the server reports its start and cleared as it stops,
+     * so the status line offers a URL only while there is one to open.
+     *
+     * @since 3.0.0
+     */
+    private serverUrl?;
+    /**
+     * The level to go back to once reporting is turned down again.
+     *
+     * @remarks
+     * Held so that turning `verbose` off restores the level the run was started at rather than a default,
+     * which is what makes the toggle reversible for a run started at `error`.
+     *
+     * @since 3.0.0
+     */
+    private restoreLevel;
+    /**
+     * Takes the build a key or a watch asks for, and settles the level to fall back to.
+     *
+     * @param build - What to run when a rebuild is asked for
+     *
+     * @remarks
+     * The build arrives as a callback rather than as a service,
+     * so the screen starts a run without knowing what a run is made of.
+     * A run already started at `verbose` has no quieter level to remember, so `info` stands in as the one to return to.
+     *
+     * @example
+     * ```ts
+     * const screen = inject(Screen, runBuild); // runBuild is what a key or a watch will call
+     * ```
+     *
+     * @since 3.0.0
+     */
+    constructor(build: () => Promise<void>);
+    /**
+     * Sets the level the run reports at.
+     *
+     * @param value - Level to report at from now on
+     *
+     * @remarks
+     * Written through the configuration rather than held here,
+     * so a variant reading the level for its own messages and the screen reading it for its groups agree.
+     *
+     * @example
+     * ```ts
+     * screen.logLevel = 'warning'; // info and verbose stop printing
+     * ```
+     *
+     * @see LogLevelType
+     * @since 3.0.0
+     */
+    set logLevel(value: LogLevelType);
+    /**
+     * The level the run is reporting at.
+     *
+     * @returns The configured level, `info` where the configuration names none
+     *
+     * @example
+     * ```ts
+     * screen.logLevel; // 'info'
+     * ```
+     *
+     * @see LogLevelType
+     * @since 3.0.0
+     */
+    get logLevel(): LogLevelType;
+    /**
+     * The address the running server answers on.
+     *
+     * @returns The URL, empty while no server is running
+     *
+     * @remarks
+     * Empty rather than absent, so a caller writing it into a line needs no guard of its own.
+     *
+     * @example
+     * ```ts
+     * screen.url; // 'http://localhost:3000'
+     * ```
+     *
+     * @since 3.0.0
+     */
+    get url(): string;
+    /**
+     * Records the address a server has begun answering on.
+     *
+     * @param value - URL the server bound to
+     *
+     * @example
+     * ```ts
+     * screen.url = 'http://localhost:3000';
+     * ```
+     *
+     * @since 3.0.0
+     */
+    set url(value: string);
+    /**
+     * Reports either end of a build: its start or its finish.
+     *
+     * @param event - What the variant reported, carrying its context and, at the end, its result
+     *
+     * @remarks
+     * A start says which variant is building and no more, since nothing has been found out yet.
+     * An end prints the messages first and the outcome last,
+     * so a reader scrolling up meets the verdict before its reasons.
+     * A build that wrote no output is the failing case, whether it threw or only reported errors,
+     * and it sets the exit code, which is what lets a pipeline read the run without reading its output.
+     * Reporting at `verbose` lists every output rather than the largest few.
+     *
+     * @example
+     * ```ts
+     * build.subscribe(screen.buildEvent.bind(screen));
+     * // [xBuild] → build esm
+     * // [xBuild] ✓ esm in 128 ms
+     * ```
+     *
+     * @see LifecycleEventsType
+     * @since 3.0.0
+     */
+    buildEvent(event: LifecycleEventsType): void;
+    /**
+     * Reports what the development server is doing.
+     *
+     * @param event - What the server reported: its start, its stop, a request, or a failure
+     *
+     * @remarks
+     * A start is where the address comes from, and a stop is what takes it away again,
+     * so the status line offers the URL for exactly as long as something answers on it.
+     * A stop is reported only where a server was running, since a stop is worth a line only where something was answering.
+     * Requests are reported only at `verbose`, one line being worth little against a page that fetches thirty files.
+     * A failed `favicon.ico` is dropped whatever the level, since browsers ask for one unprompted on every visit.
+     *
+     * @example
+     * ```ts
+     * server.subscribe(screen.serverEvent.bind(screen));
+     * // [xBuild] → serve http://localhost:3000
+     * ```
+     *
+     * @see ServerEventsType
+     * @since 3.0.0
+     */
+    serverEvent(event: ServerEventsType): void;
+    /**
+     * Reports a type check and ends the process on what it found.
+     *
+     * @param diagnostics - Messages each variant's check reported, keyed by the variant's name
+     *
+     * @remarks
+     * Every variant gets a heading carrying what it found, followed by its groups,
+     * so a clean variant is still reported rather than left out of a run that named it.
+     * The count is of everything the check reported rather than of what the level prints,
+     * which is what keeps a quiet run from reading as a clean one.
+     * The process leaves from here, and an error anywhere leaves with `1`,
+     * since a check is the whole of what a run asking for one wanted.
+     *
+     * @example
+     * ```ts
+     * screen.diagnostics(await build.typeChack());
+     * // [xBuild] → type-check esm 2 to look at
+     * ```
+     *
+     * @see LifecycleLogsType
+     * @since 3.0.0
+     */
+    diagnostics(diagnostics: Record<string, LifecycleLogsType>): void;
+    /**
+     * Clears what the last build left, takes up any configuration change, says what asked for this build, and runs it.
+     *
+     * @param reason - What asked for the build, such as the files that changed or the key that was pressed
+     * @param force - Whether every TypeScript project reparses its configuration even where its file has not moved
+     *
+     * @remarks
+     * Every rebuild of a watch goes through here, so the screen is cleared and the run announced the same way
+     * whichever asked for it.
+     * The build itself is the one the run handed over when the screen was made.
+     * The TypeScript configurations are reloaded here rather than by the watch,
+     * so a rebuild started by a key reads them as freshly as one started by a changed file.
+     * A configuration that has stayed put costs a lookup and nothing more.
+     * Forcing reparses every project regardless, which is what the reload key asks for
+     * and what catches a change the configuration file's own version misses.
+     *
+     * @example
+     * ```ts
+     * await screen.rebuild('2 files changed'); // [xBuild] rebuild 2 files changed
+     * await screen.rebuild('reloading', true); // the same, with every tsconfig reparsed first
+     * ```
+     *
+     * @see TypescriptService.reload
+     * @since 3.0.0
+     */
+    rebuild(reason: string, force?: boolean): Promise<void>;
+    /**
+     * Turns reporting all the way up, or back to what it was before it was turned up.
+     *
+     * @returns The level the run now reports at
+     *
+     * @remarks
+     * The level the run was set to is remembered rather than assumed,
+     * so a run started at `error` goes back to `error` rather than to the default.
+     * The level is written back through the configuration, so everything reading it follows in the same breath.
+     *
+     * @example
+     * ```ts
+     * screen.toggleVerbose(); // 'verbose'
+     * screen.toggleVerbose(); // 'info' - what it was before
+     * ```
+     *
+     * @since 3.0.0
+     */
+    toggleVerbose(): LogLevelType;
+    /**
+     * Writes a line to the scrollback and says the same thing on the status line.
+     *
+     * @param activity - What is happening, as the bar says it
+     * @param line - The line printed to the scrollback
+     *
+     * @remarks
+     * The two are worded apart rather than shared, since the bar carries no prefix and has one row to say it in,
+     * while the printed line stands on its own long after the run has moved past it.
+     *
+     * @see setActivity
+     * @since 3.0.0
+     */
+    private say;
+    /**
+     * Prints the message groups the current level allows.
+     *
+     * @param logs - Messages to print, filed under the level each was reported at
+     *
+     * @remarks
+     * The groups run loudest first, so what failed a build is read before what merely remarked on it.
+     * Each group is compared against the level the run is set to,
+     * which is what leaves a quiet run its errors and drops everything under them.
+     * An error always carries its code window and its trace, since that is what an error is read for,
+     * while the quieter groups carry theirs only at `verbose`.
+     *
+     * @see Levels
+     * @see printGroup
+     *
+     * @since 3.0.0
+     */
+    private groups;
+}
+/**
+ * Holds the build configuration and lets the rest of the build watch it change.
+ *
+ * @typeParam T - Shape of the configuration, at least a {@link ConfigurationInterface}
+ *
+ * @remarks
+ * The configuration is not settled once and read forever: a watch reloads the file behind it, so whatever depends on
+ * a setting has to be told when it moves rather than reading it once at startup.
+ * That is what {@link select} is for - it reports only when the value that a caller actually asked for has changed,
+ * so a change elsewhere in the configuration wakes nobody.
+ * Updates merge rather than replace, so an update says what changes and leaves the rest standing.
+ * Registered as a singleton, so every consumer reads and watches the same configuration.
+ *
+ * @example
+ * ```ts
+ * const configuration = inject(ConfigurationService);
+ *
+ * configuration.getValue(config => config.logLevel);  // info
+ * configuration.select(config => config.variants)
+ *     .subscribe(variants => rebuild(variants));     // told whenever the variants change
+ * configuration.patch({ verbose: true });            // the variant's watcher hears nothing
+ * ```
+ *
+ * @see xBuildConfigInterface
+ * @see ConfigurationInterface
+ *
+ * @since 2.0.0
+ */
+declare class ConfigurationService<T extends ConfigurationInterface = Required<xBuildConfigInterface>> {
+    private initialConfig;
+    /**
+     * The configuration and everything watching it.
+     *
+     * @remarks
+     * A behavior subject rather than a plain one, so a subscriber arriving late is handed the configuration as it
+     * stands instead of waiting for the next change.
+     *
+     * @since 2.0.0
+     */
+    private readonly config$;
+    /**
+     * Creates the service around a starting configuration.
+     *
+     * @param initialConfig - Configuration to start from the built-in defaults when omitted
+     *
+     * @remarks
+     * The configuration is copied on the way in, so the object handed over is never written to - which is what makes
+     * the frozen defaults usable as a starting point.
+     * It is also kept as it was passed, since {@link reload} needs something to return to.
+     *
+     * @example
+     * ```ts
+     * const configuration = new ConfigurationService({ variants: { esm: { esbuild: { format: 'esm' } } } });
+     * configuration.getValue().variants.esm; // { esbuild: { format: 'esm' } }
+     * ```
+     *
+     * @see DefaultsCommonConfig
+     * @since 2.0.0
+     */
+    constructor(initialConfig?: T);
+    /**
+     * Reads the whole configuration as it stands.
+     *
+     * @returns The current configuration
+     *
+     * @example
+     * ```ts
+     * configuration.getValue().verbose; // false
+     * ```
+     *
+     * @since 2.0.0
+     */
+    getValue(): T;
+    /**
+     * Reads one value out of the configuration as it stands.
+     *
+     * @typeParam R - What the selector returns
+     * @param selector - Picks the value to read
+     * @returns Whatever the selector returned
+     *
+     * @remarks
+     * The one-off counterpart of {@link select}: it answers once and never again, which suits a decision taken at a
+     * point in time rather than something that has to follow the configuration.
+     *
+     * @example
+     * ```ts
+     * configuration.getValue(config => Object.keys(config.variants)); // [ 'esm', 'cjs' ]
+     * ```
+     *
+     * @since 2.0.0
+     */
+    getValue<R>(selector: (config: T) => R): R;
+    /**
+     * Watches the whole configuration.
+     *
+     * @param observer - Called with the configuration, now and on every change
+     * @returns A function that stops the watching
+     *
+     * @remarks
+     * Called straight away with the configuration as it stands, so a subscriber needs no separate first read.
+     * It hears every change, whatever moved, which is why {@link select} is the better choice for anything that cares
+     * about one corner of the configuration.
+     *
+     * @example
+     * ```ts
+     * const stop = configuration.subscribe(config => console.log(config.verbose)); // logs at once
+     * configuration.patch({ verbose: true });                                      // logs again
+     * stop();
+     * ```
+     *
+     * @see select
+     * @since 1.0.0
+     */
+    subscribe(observer: (value: T) => void): UnsubscribeType;
+    /**
+     * Watches one value in the configuration.
+     *
+     * @typeParam R - What the selector returns
+     * @param selector - Picks the value to watch
+     * @returns A stream of that value, reporting only when it has actually changed
+     *
+     * @remarks
+     * The selector runs on every change, but its result is compared against the one before and only a real difference
+     * is passed on - so a change elsewhere costs a comparison rather than the work behind a subscriber.
+     * The comparison is structural, so a selector that builds an equal object each time still reports nothing.
+     *
+     * @example
+     * ```ts
+     * configuration.select(config => config.common?.esbuild?.minify)
+     *     .subscribe(minify => console.log(minify)); // true, then again only when it changes
+     *
+     * configuration.patch({ verbose: true });        // nothing reported - minify did not move
+     * ```
+     *
+     * @see equals
+     * @see subscribe
+     *
+     * @since 2.0.0
+     */
+    select<R>(selector: (config: T) => R): Observable<R>;
+    /**
+     * Merges changes into the configuration and reports them.
+     *
+     * @param partial - The parts to change, nested as deeply as needed
+     *
+     * @remarks
+     * Merged over what is there now, so anything left out keeps its value and only the corners named are touched.
+     * Arrays are concatenated rather than replaced, so patching a list adds to it - which is a reason to reach for
+     * {@link reload} when a list has to be replaced rather than extended.
+     * Every subscriber is told, while a {@link select} passes it on only if the value it picked actually moved.
+     *
+     * @example
+     * ```ts
+     * configuration.patch({ common: { esbuild: { minify: false } } });
+     * configuration.getValue().common?.esbuild?.format; // 'cjs' - untouched
+     * ```
+     *
+     * @see reload
+     * @since 1.0.0
+     */
+    patch(partial: DeepPartialType<T>): void;
+    /**
+     * Starts again from the initial configuration, with the given one merged over it.
+     *
+     * @param config - Configuration to apply over the initial one
+     *
+     * @remarks
+     * Not a replacement: the result is the configuration this service was constructed with,
+     * merged with what is passed here.
+     * What the initial configuration carried therefore survives, and only what accumulated since is dropped.
+     * That is what re-reading an edited file wants, since a patch has no way to take something back.
+     * To be rid of the initial configuration too, construct another service.
+     *
+     * @example
+     * ```ts
+     * configuration.patch({ verbose: true });
+     * configuration.reload({ common: { types: false } });
+     * configuration.getValue().verbose; // false again - the patch is gone
+     * ```
+     *
+     * @see patch
+     * @since 2.0.0
+     */
+    reload(config: DeepPartialType<T>): void;
+}
+/**
+ * The shape a configuration file exports.
+ *
+ * @remarks
+ * Every field of a whole configuration, each one optional,
+ * so a file may state one setting and leave the rest to the defaults.
+ * The four fields beside them are the ones only a file carries:
+ * the reporting level, the command line options it declares, the server it asks for, and the watcher it tunes.
+ *
+ * @example
+ * ```ts
+ * const config: xBuildConfigInterface = {
+ *     common: { types: true },
+ *     watch: { debounce: 50 },
+ *     userArgv: { release: { type: 'boolean' } }
+ * };
+ * ```
+ *
+ * @see configFileProvider
+ * @see PartialConfigurationType
+ *
+ * @since 3.0.0
+ */
+interface xBuildConfigInterface extends PartialConfigurationType {
+    /**
+     * The reporting level for the whole run.
+     *
+     * @remarks
+     * It sits on the file itself rather than inside `common` or a variant,
+     * so one level covers every variant the file declares.
+     * The esbuild options a file passes through do not accept a `logLevel`, which is why the setting lives here.
+     * `silent` drops a message rather than filing it under a bucket.
+     *
+     * @example
+     * ```ts
+     * { logLevel: 'warning' } // warnings and errors alone
+     * ```
+     *
+     * @see LogLevelType
+     * @since 3.0.0
+     */
+    logLevel?: LogLevelType;
+    /**
+     * The command line options this configuration declares.
+     *
+     * @remarks
+     * Each entry is a yargs option keyed by the flag it defines,
+     * so a project can take a flag of its own and read the parsed value back through the `argv` of a lifecycle hook.
+     *
+     * @example
+     * ```ts
+     * { userArgv: { release: { type: 'boolean', describe: 'build for release' } } }
+     * ```
+     *
+     * @see LifecycleContextInterface
+     * @since 2.0.0
+     */
+    userArgv?: Record<string, Options>;
+    /**
+     * The static server this configuration asks for.
+     *
+     * @remarks
+     * `dir` names the directory served, and it is required rather than inferred from the build output.
+     * `start` asks for the server to come up with the build rather than wait to be started.
+     *
+     * @example
+     * ```ts
+     * { serve: { dir: 'dist', start: true } }
+     * ```
+     *
+     * @since 2.0.0
+     */
+    serve?: ServerConfigurationInterface & {
+        dir: string;
+        start?: boolean;
+    };
+    /**
+     * The watcher settings configuration tunes.
+     *
+     * @remarks
+     * Every setting of the watcher is optional, so a file names only what it changes - the debounce window, the
+     * recursion, the dotfiles, or the filters - and whatever it leaves out keeps its default.
+     * A `filter` named here joins the two globs {@link configFileProvider} supplies rather than replacing them.
+     *
+     * @example
+     * ```ts
+     * { watch: { debounce: 50, recursive: true } }
+     * ```
+     *
+     * @see configFileProvider
+     * @see WatchOptionsInterface
+     *
+     * @since 3.0.0
+     */
+    watch?: WatchOptionsInterface;
+}
+/**
+ * The kind of change carried by a watch event.
+ *
+ * @remarks
+ * The union of the numeric codes exposed by {@link ChangeTypes}.
+ *
+ * @example
+ * ```ts
+ * const type: ChangeType = ChangeTypes.Added; // 0
+ * ```
+ *
+ * @see ChangeTypes
+ * @since 3.0.0
+ */
+type ChangeType = typeof ChangeTypes[keyof typeof ChangeTypes];
+/**
+ * A single entry describing what happened to one watched path.
+ *
+ * @remarks
+ * Used as the value side of {@link WatchEventType}, keyed by the path relative to the watched base.
+ *
+ * @example
+ * ```ts
+ * const change: WatchChangeInterface = { type: ChangeTypes.Change, stats };
+ * ```
+ *
+ * @see ChangeType
+ * @since 3.0.0
+ */
+interface WatchChangeInterface {
+    /**
+     * The kind of change that occurred.
+     *
+     * @example
+     * ```ts
+     * if (change.type === ChangeTypes.Deleted) forget(path);
+     * ```
+     *
+     * @see ChangeType
+     * @since 3.0.0
+     */
+    type: ChangeType;
+    /**
+     * The followed `stat` result for the path at the time of the event.
+     *
+     * @remarks
+     * Reflects the symlink target rather than the link itself.
+     * Absent for a deleted entry, whose path no longer resolves.
+     *
+     * @example
+     * ```ts
+     * change.stats?.mtimeMs; // 1754000000000
+     * change.stats;          // undefined - the path was deleted
+     * ```
+     *
+     * @since 3.0.0
+     */
+    stats?: Stats;
+}
+/**
+ * A batch of path changes accumulated within one debounce window.
+ *
+ * @remarks
+ * Keys are paths relative to the watched base, and each value describes the change on that path.
+ * One object is emitted per flush, coalescing every event seen since the previous emission.
+ *
+ * @example
+ * ```ts
+ * watcher.subscribe((batch: WatchEventType) => {
+ *     Object.keys(batch); // [ 'src/index.ts', 'src/app.ts' ]
+ * });
+ * ```
+ *
+ * @see WatchChangeInterface
+ * @since 3.0.0
+ */
+type WatchEventType = Record<string, WatchChangeInterface>;
+/**
+ * The subscriber form accepted when observing the watch stream.
+ *
+ * @remarks
+ * Either a full {@link ObserverInterface} carrying `next`, `error`, and `complete`,
+ * or a bare `next` callback that receives each emitted {@link WatchEventType} batch.
+ * A callback form leaves `error` and `complete` to be supplied as separate arguments.
+ *
+ * @example
+ * ```ts
+ * watcher.subscribe((batch) => rebuild(batch));                 // the callback form
+ * watcher.subscribe({ next: rebuild, error: report });          // the observer form
+ * ```
+ *
+ * @see WatchEventType
+ * @since 3.0.0
+ */
+type ObserverType = ObserverInterface<WatchEventType> | NextType<WatchEventType>;
+/**
+ * Options controlling which paths a watcher tracks and how it reports them.
+ *
+ * @remarks
+ * Every field is optional, so an omitted object watches the base itself,
+ * emits every non-dot path it sees, and coalesces those events over 150 milliseconds.
+ *
+ * @example
+ * ```ts
+ * new WatchService('src', { recursive: true, filter: [ '**\/*.ts' ], debounce: 100 });
+ * ```
+ *
+ * @see WatchService
+ * @since 3.0.0
+ */
+interface WatchOptionsInterface {
+    /**
+     * Whether to include dotfiles and dot-directories.
+     *
+     * @remarks
+     * When `false` or omitted, any path with a segment beginning with `.` is skipped and the filter hides dotfiles.
+     * When `true`, dot paths are watched and eligible to match the filter.
+     *
+     * @example
+     * ```ts
+     * new WatchService('.', { dot: true }); // reports changes under .github
+     * ```
+     *
+     * @since 3.0.0
+     */
+    dot?: boolean;
+    /**
+     * Glob patterns selecting which paths emit change events.
+     *
+     * @remarks
+     * A leading `!` marks an exclusion.
+     * A path passes when it matches an include and no exclusion.
+     * An empty or omitted list matches every path.
+     *
+     * @example
+     * ```ts
+     * new WatchService('src', { filter: [ '**\/*.ts', '!**\/*.spec.ts' ] });
+     * ```
+     *
+     * @see createMatcher
+     * @since 3.0.0
+     */
+    filter?: Array<string>;
+    /**
+     * Milliseconds to coalesce events before emitting a batch.
+     *
+     * @remarks
+     * Each event restarts the window, so a burst of rapid changes yields a single {@link WatchEventType} emission.
+     * Defaults to 150 when omitted.
+     *
+     * @example
+     * ```ts
+     * new WatchService('src', { debounce: 0 }); // emit as soon as the event loop allows
+     * ```
+     *
+     * @since 3.0.0
+     */
+    debounce?: number;
+    /**
+     * Whether to watch nested directories as well as the base.
+     *
+     * @example
+     * ```ts
+     * new WatchService('src', { recursive: true }); // src/models/files.model.ts reports too
+     * ```
+     *
+     * @since 3.0.0
+     */
+    recursive?: boolean;
+    /**
+     * Whether to place additional watchers on symbolic links.
+     *
+     * @remarks
+     * `fs.watch` does not follow links,
+     * so when `true` the base is scanned once, and every symlink found is watched directly.
+     * Links appearing later are picked up from their parent directory's events.
+     *
+     * @example
+     * ```ts
+     * new WatchService('src', { followSymlinks: true }); // a linked package reports its own changes
+     * ```
+     *
+     * @since 3.0.0
+     */
+    followSymlinks?: boolean;
+}
+/**
+ * Numeric codes for the kind of change reported for a watched path.
+ *
+ * @remarks
+ * A `const enum`, so every reference inlines to its literal value at compile time, and no runtime object is emitted.
+ * Used internally by the watcher on the event path.
+ * The runtime-visible counterpart consumers import is {@link ChangeTypes}.
+ *
+ * @example
+ * ```ts
+ * if (change.type === ChangeCode.Deleted) forget(path);
+ * ```
+ *
+ * @see ChangeTypes
+ * @since 3.0.0
+ */
+declare const enum ChangeCode {
+    /**
+     * A path seen for the first time, recognized by its `birthtime` and `mtime` being equal.
+     *
+     * @since 3.0.0
+     */
+    Added = 0,
+    /**
+     * A later modification to a path the watcher already knew about.
+     *
+     * @since 3.0.0
+     */
+    Change = 1,
+    /**
+     * A path that no longer resolves on the disk, after which its watcher is closed.
+     *
+     * @since 3.0.0
+     */
+    Deleted = 2
+}
+/**
+ * Runtime map of watch change kinds, keyed by name.
+ *
+ * @remarks
+ * Mirrors {@link ChangeCode} as a real exported object,
+ * so consumers can reference the codes at runtime - to validate or label the `type` of an emitted
+ * {@link WatchChangeInterface}, among other uses.
+ * The companion {@link ChangeType} type narrows to the union of these codes.
+ *
+ * @example
+ * ```ts
+ * ChangeTypes.Added;   // 0
+ * ChangeTypes.Deleted; // 2
+ * ```
+ *
+ * @see ChangeCode
+ * @since 3.0.0
+ */
+declare const ChangeTypes: {
+    /**
+     * A path seen for the first time.
+     *
+     * @see ChangeCode.Added
+     * @since 3.0.0
+     */
+    readonly Added: ChangeCode.Added;
+    /**
+     * A later modification to a path already known.
+     *
+     * @see ChangeCode.Change
+     * @since 3.0.0
+     */
+    readonly Change: ChangeCode.Change;
+    /**
+     * A path that no longer resolves on the disk.
+     *
+     * @see ChangeCode.Deleted
+     * @since 3.0.0
+     */
+    readonly Deleted: ChangeCode.Deleted;
+};
+/**
+ * How a server listens and what it does with requests.
+ *
+ * @remarks
+ * Every field is optional, a server with no configuration at all listening on a system-assigned port of `localhost`
+ * and serving its root directory as it stands.
+ * The object is kept by the server rather than copied, and written back to: the defaults land on it when the server
+ * is constructed, and the port does once it is listening.
+ *
+ * @example
+ * ```ts
+ * const config: ServerConfigurationInterface = { port: 0, verbose: true };
+ * const server = new ServerModule(config, 'dist');
+ *
+ * await server.start();
+ * config.port; // 54321 - no longer the 0 that was passed in
+ * ```
+ *
+ * @since 2.0.0
+ */
+interface ServerConfigurationInterface {
+    /**
+     * Port to listen on, or `0` to let the system choose one.
+     *
+     * @remarks
+     * Defaults to `0`, which is also what an explicit `0` means: the operating system picks a free port, and it is
+     * written back here once bound, so this field is how the chosen port is read afterward.
+     * That is the value to leave it at when several servers run at once and a fixed port would collide.
+     *
+     * @example
+     * ```ts
+     * config.port; // 0 before starting, 54321 after
+     * ```
+     *
+     * @since 2.0.0
+     */
+    port?: number;
+    /**
+     * Interface to bind to.
+     *
+     * @remarks
+     * Defaults to `localhost`, which accepts only connections from the machine itself.
+     * `0.0.0.0` binds every interface, which is what makes the server reachable from another device or from outside a
+     * container - and worth choosing deliberately, the directory being served to whoever can reach the port.
+     *
+     * @example
+     * ```ts
+     * config.host; // 'localhost'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    host?: string;
+    /**
+     * Path of the private key to serve HTTPS with.
+     *
+     * @remarks
+     * Read once at startup, and only when {@link https} is set.
+     * Left out, the key shipped with the framework stands in.
+     *
+     * @example
+     * ```ts
+     * config.key; // './certs/server.key'
+     * ```
+     *
+     * @see cert
+     * @since 2.0.0
+     */
+    key?: string;
+    /**
+     * Path of the certificate to serve HTTPS with.
+     *
+     * @remarks
+     * Read once at startup, and only when {@link https} is set.
+     * Left out, the certificate shipped with the framework stands in - self-signed, so a browser will ask before
+     * trusting it.
+     *
+     * @example
+     * ```ts
+     * config.cert; // './certs/server.crt'
+     * ```
+     *
+     * @see key
+     * @since 2.0.0
+     */
+    cert?: string;
+    /**
+     * Whether to serve over HTTPS rather than HTTP.
+     *
+     * @remarks
+     * Decides which server is created, and so which scheme the `onStart` hook reports.
+     * Neither {@link key} nor {@link cert} is required alongside it, the framework's own pair standing in.
+     *
+     * @example
+     * ```ts
+     * config.https; // true - onStart reports a https:// url
+     * ```
+     *
+     * @since 2.0.0
+     */
+    https?: boolean;
+    /**
+     * Whether to log every request as it arrives.
+     *
+     * @remarks
+     * Logs the requested url and nothing else, so the output stays readable while a page loads its assets.
+     *
+     * @example
+     * ```ts
+     * config.verbose; // true - '[xBuild] Request /index.js' per request
+     * ```
+     *
+     * @since 2.0.0
+     */
+    verbose?: boolean;
+    /**
+     * Hook given every request before the server handles it.
+     *
+     * @param req - Request as it arrived
+     * @param res - Response to write to
+     * @param next - The static-file handling, to call or to skip
+     *
+     * @remarks
+     * Calling `next` hands the request back to the server.
+     * Not calling it takes the request over entirely, which is how a route or a single-page fallback is served
+     * alongside the files.
+     * It runs before the path is resolved, so a request that would be refused as outside the root still reaches it.
+     *
+     * @example
+     * ```ts
+     * config.onRequest = (req, res, next) => {
+     *     if (req.url !== '/api/health') return next();
+     *     res.end('ok');
+     * };
+     * ```
+     *
+     * @since 2.0.0
+     */
+    onRequest?: (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+    /**
+     * Hook called once the server is listening.
+     *
+     * @remarks
+     * Runs from the listen callback, after the assigned port has been written back,
+     * so what it is handed is what was actually bound rather than what was asked for.
+     * That is how the url of a server given port `0` is learned.
+     *
+     * @example
+     * ```ts
+     * config.onStart = ({ url }) => console.log(url); // 'http://localhost:54321'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    onStart?: (config: ServerAddressInterface) => void;
+}
+/**
+ * Where a server ended up listening.
+ *
+ * @remarks
+ * What a port of `0` resolves to is known only once the system has answered,
+ * so this is how a caller learns what was bound rather than what was asked for.
+ *
+ * @example
+ * ```ts
+ * const address: ServerAddressInterface = { host: 'localhost', port: 61355, url: 'http://localhost:61355' };
+ * ```
+ *
+ * @since 3.0.0
+ */
+interface ServerAddressInterface {
+    /**
+     * Host the server is listening on.
+     *
+     * @since 3.0.0
+     */
+    host: string;
+    /**
+     * Port it was given, which is the one the system assigned where none was asked for.
+     *
+     * @since 3.0.0
+     */
+    port: number;
+    /**
+     * The two above as an address, under the scheme the server was started with.
+     *
+     * @since 3.0.0
+     */
+    url: string;
+}
+/**
+ * Something the server did, tagged with which of the four it is.
+ *
+ * @remarks
+ * The server says what happened and writes none of it, so what reaches a terminal - and whether anything does -
+ * is the reader's to decide rather than the server's.
+ * Discriminated on `type`, so narrowing on it gives the fields of the matching event:
+ *
+ * - **start** - listening, carrying the address it settled on
+ * - **stop** - closed, `running` telling a server that was up from one that never was
+ * - **request** - a request arrived, named by what it asked for
+ * - **error** - a request failed or reached nothing, carrying the failure and what was asked for
+ *
+ * @example
+ * ```ts
+ * server.subscribe(event => {
+ *     if (event.type === 'start') event.url; // 'http://localhost:61355'
+ * });
+ * ```
+ *
+ * @see ServerModule.subscribe
+ * @since 3.0.0
+ */
+type ServerEventsType = ServerAddressInterface & {
+    type: 'start';
+} | {
+    type: 'stop';
+    running: boolean;
+} | {
+    type: 'request';
+    url: string;
+} | {
+    type: 'error';
+    error: Error;
+    url?: string;
+};
+/**
+ * Options a configuration file adds to the command line.
+ *
+ * @remarks
+ * Each key becomes a flag and each value declares it the way yargs does, so a configuration reaches the same type,
+ * alias, and validation handling xBuild's own options get.
+ * They are registered alongside the built-in options and listed under a heading of their own in help, which is what
+ * keeps a project's flags distinguishable from the tool's.
+ *
+ * @example
+ * ```ts
+ * const userExtensions: UserExtensionInterface = {
+ *     env: { describe: 'Build environment', type: 'string', choices: [ 'dev', 'prod' ] }
+ * };
+ *
+ * argv.enhancedParse(process.argv, userExtensions).env; // 'prod'
+ * ```
+ *
+ * @see ArgumentsInterface
+ * @since 2.0.0
+ */
+interface UserExtensionInterface {
+    /**
+     * Declaration of one added flag, named by its key.
+     *
+     * @remarks
+     * A yargs `Options` object, so type, alias, default, and choices all mean what they mean there.
+     *
+     * @example
+     * ```ts
+     * userExtensions.env; // { describe: 'Build environment', type: 'string', choices: [ 'dev', 'prod' ] }
+     * ```
+     *
+     * @since 2.0.0
+     */
+    [key: string]: Options;
+}
+/**
+ * What every parse produces, whatever options were declared.
+ *
+ * @remarks
+ * The two fields yargs always fills, plus an index signature for the flags a given pass happened to declare.
+ * It is what the early passes return, their option set being deliberately partial, and what
+ * {@link ArgumentsInterface} builds on once the whole set is known.
+ *
+ * @example
+ * ```ts
+ * // xBuild src/app.ts src/worker.ts
+ * args._;  // [ 'src/app.ts', 'src/worker.ts' ]
+ * args.$0; // 'xBuild'
+ * ```
+ *
+ * @see ArgumentsInterface
+ * @since 2.0.0
+ */
+interface BaseArgumentsInterface {
+    /**
+     * Values given without a flag in front of them.
+     *
+     * @remarks
+     * Numbers as well as strings, yargs converting a value that reads as one.
+     * In the full parse these are claimed by the default command and surface as `entryPoints` instead, so what
+     * remains here is whatever that command did not take.
+     *
+     * @example
+     * ```ts
+     * args._; // [ 'src/app.ts' ]
+     * ```
+     *
+     * @since 2.0.0
+     */
+    _: Array<string | number>;
+    /**
+     * Name the script was invoked as.
+     *
+     * @remarks
+     * Filled by yargs and used in the usage line it prints.
+     *
+     * @example
+     * ```ts
+     * args.$0; // 'xBuild'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    $0: string;
+    /**
+     * Any other flag the parse declared.
+     *
+     * @remarks
+     * Open-ended because a configuration file can add flags this package never sees, so what a result carries is
+     * decided at run time rather than by this declaration.
+     *
+     * @example
+     * ```ts
+     * args['env']; // 'prod' - a flag a configuration added
+     * ```
+     *
+     * @since 2.0.0
+     */
+    [argName: string]: unknown;
+}
+/**
+ * The result of the full parse, with xBuild's own options named.
+ *
+ * @remarks
+ * Every field is optional: an option that was not typed is absent rather than defaulted, defaults being applied while
+ * the configuration is resolved, so this type describes what was asked for rather than what the build settles on.
+ * Flags a configuration file added are reachable through the inherited index signature.
+ *
+ * @example
+ * ```ts
+ * // xBuild src/index.ts --bundle --minify --format esm
+ * args.entryPoints; // [ 'src/index.ts' ]
+ * args.bundle;      // true
+ * args.watch;       // undefined - not typed, not defaulted
+ * ```
+ *
+ * @see ArgsDefaultOptions
+ * @see BaseArgumentsInterface
+ *
+ * @since 2.0.0
+ */
+interface ArgumentsInterface extends BaseArgumentsInterface {
+    /**
+     * Entry points reserved for development builds.
+     *
+     * @remarks
+     * Declared for configuration handling to read.
+     * No command-line flag produces it, so it never arrives from a parse.
+     *
+     * @example
+     * ```ts
+     * args.dev; // [ 'src/dev-tools.ts' ]
+     * ```
+     *
+     * @since 2.0.0
+     */
+    dev?: Array<string>;
+    /**
+     * Whether to type check while building.
+     *
+     * @remarks
+     * Runs the checker alongside the build rather than instead of it, which is what separates it from
+     * {@link typeCheck}.
+     * Whether a reported error stops the build is {@link failOnError}'s to decide.
+     *
+     * @example
+     * ```ts
+     * args.types; // true - typed as --types or --btc
+     * ```
+     *
+     * @since 2.0.0
+     */
+    types?: boolean;
+    /**
+     * Entry points reserved for debug builds.
+     *
+     * @remarks
+     * Declared for configuration handling to read.
+     * No command-line flag produces it, so it never arrives from a parse.
+     *
+     * @example
+     * ```ts
+     * args.debug; // [ 'src/debug-logger.ts' ]
+     * ```
+     *
+     * @since 2.0.0
+     */
+    debug?: Array<string>;
+    /**
+     * Directory to serve the build output from.
+     *
+     * @remarks
+     * Carries the directory rather than a flag, so serving and choosing where to serve from are the one option.
+     *
+     * @example
+     * ```ts
+     * args.serve; // 'dist'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    serve?: string;
+    /**
+     * Directory the build output is written to.
+     *
+     * @remarks
+     * Overrides whatever the configuration set, the command line being the later word.
+     *
+     * @example
+     * ```ts
+     * args.outdir; // 'dist'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    outdir?: string;
+    /**
+     * Whether to rebuild as files change.
+     *
+     * @example
+     * ```ts
+     * args.watch; // true
+     * ```
+     *
+     * @since 2.0.0
+     */
+    watch?: boolean;
+    /**
+     * Path of the configuration file to load.
+     *
+     * @remarks
+     * The one option read before the others, {@link ArgsConfigPath} standing in when it is not typed, so it is always
+     * present in a parsed result.
+     *
+     * @example
+     * ```ts
+     * args.config; // 'config.xbuild.ts'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    config?: string;
+    /**
+     * Whether to minify the output.
+     *
+     * @example
+     * ```ts
+     * args.minify; // true
+     * ```
+     *
+     * @since 2.0.0
+     */
+    minify?: boolean;
+    /**
+     * Whether to pull imported modules into the output.
+     *
+     * @remarks
+     * Left unset, the module structure is preserved and the imports have to resolve at run time instead.
+     *
+     * @example
+     * ```ts
+     * args.bundle; // true
+     * ```
+     *
+     * @since 2.0.0
+     */
+    bundle?: boolean;
+    /**
+     * Module format the output is written in.
+     *
+     * @remarks
+     * Checked while parsing, so a value outside the three fails on the command line rather than in the build.
+     *
+     * @example
+     * ```ts
+     * args.format; // 'esm'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    format?: 'cjs' | 'esm' | 'iife';
+    /**
+     * Whether to report errors with their stack traces.
+     *
+     * @example
+     * ```ts
+     * args.verbose; // true
+     * ```
+     *
+     * @since 2.0.0
+     */
+    verbose?: boolean;
+    /**
+     * Runtime the output targets.
+     *
+     * @remarks
+     * Decides how modules resolve and which built-ins are assumed, `neutral` assuming neither browser nor Node.
+     * Checked while parsing, like {@link format}.
+     *
+     * @example
+     * ```ts
+     * args.platform; // 'node'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    platform?: Platform;
+    /**
+     * Path of the TypeScript configuration to use.
+     *
+     * @remarks
+     * Governs both the type check and the declarations, the two coming from the same compiler.
+     *
+     * @example
+     * ```ts
+     * args.tsconfig; // 'tsconfig.build.json'
+     * ```
+     *
+     * @since 2.0.0
+     */
+    tsconfig?: string;
+    /**
+     * Whether to type check instead of building.
+     *
+     * @remarks
+     * Nothing is emitted, which is what separates it from {@link types}.
+     *
+     * @example
+     * ```ts
+     * args.typeCheck; // true - typed as --typeCheck or --tc
+     * ```
+     *
+     * @since 2.0.0
+     */
+    typeCheck?: boolean;
+    /**
+     * Whether to emit declaration files beside the output.
+     *
+     * @example
+     * ```ts
+     * args.declaration; // true
+     * ```
+     *
+     * @since 2.0.0
+     */
+    declaration?: boolean;
+    /**
+     * Files to build, glob patterns included.
+     *
+     * @remarks
+     * Filled from the files named without a flag as well as from `--entryPoints`, so the usual invocation needs no
+     * flag at all.
+     *
+     * @example
+     * ```ts
+     * args.entryPoints; // [ 'src/index.ts' ]
+     * ```
+     *
+     * @since 2.0.0
+     */
+    entryPoints?: Array<string>;
+    /**
+     * Whether a type error should stop the build.
+     *
+     * @remarks
+     * Reads on the errors {@link types} produces: left unset they are reported and the build carries on.
+     *
+     * @example
+     * ```ts
+     * args.failOnError; // true - typed as --failOnError or --foe
+     * ```
+     *
+     * @since 2.0.0
+     */
+    failOnError?: boolean;
+    /**
+     * Names of the configuration's build variants to run.
+     *
+     * @remarks
+     * Left unset, every variant the configuration defines is built.
+     * Naming some builds only those, which is what a pipeline that ships one target at a time wants.
+     * Repeat the flag to name more than one.
+     *
+     * @example
+     * ```ts
+     * // xBuild --build development --xb staging
+     * args.build; // [ 'development', 'staging' ]
+     * ```
+     *
+     * @see ArgsConfigPath
+     * @since 2.0.0
+     */
+    build?: Array<string>;
+    /**
+     * Whether to clear the artifacts of an earlier build before this one runs.
+     *
+     * @remarks
+     * The one option the parser gives a default,
+     * so a result carries `false` where the flag was not typed rather than leaving it out as the others do.
+     * Nothing reads it yet, so typing it changes a parsed result and nothing else.
+     *
+     * @example
+     * ```ts
+     * args.clean; // true - typed as --clean
+     * ```
+     *
+     * @since 3.0.0
+     */
+    clean?: boolean;
+}
+/**
+ * Replaces the declared variants with one built from the entry points the command line named.
+ *
+ * @param config - Configuration read from the file, modified in place
+ * @param args - Parsed command line the run was started with
+ *
+ * @remarks
+ * Files named on the command line are a run of their own rather than an addition to what the file declares,
+ * so the variants it declares are put aside, and a single variant named `argv` takes their place.
+ * A command line naming no entry point leaves the configuration as the file wrote it.
+ *
+ * @example
+ * ```ts
+ * // xBuild src/index.ts
+ * configureEntryPoints(config, args);
+ * config.variants; // { argv: { esbuild: { entryPoints: [ 'src/index.ts' ] } } }
+ * ```
+ *
+ * @since 3.0.0
+ */
+declare function configureEntryPoints(config: xBuildConfigInterface, args: ArgumentsInterface): void;
+/**
+ * Writes the flags the command line typed onto every variant.
+ *
+ * @param config - Configuration the overrides are written onto, modified in place
+ * @param args - Parsed command line the run was started with
+ *
+ * @remarks
+ * A flag left untyped is left alone rather than written as its default,
+ * so what a configuration file states survives everything the command line did not say.
+ * The overrides reach every variant, since a flag names what the run is for rather than which variant it is about.
+ * Each output directory is also excluded from the watch as it is settled,
+ * without which a build would write into the tree it is watching and set off the next one.
+ *
+ * @example
+ * ```ts
+ * // xBuild --outdir build --minify
+ * applyCommandLineOverrides(config, args);
+ * config.watch.filter; // [ '!build/**' ]
+ * ```
+ *
+ * @since 3.0.0
+ */
+declare function applyCommandLineOverrides(config: xBuildConfigInterface, args: ArgumentsInterface): void;
+/**
+ * Starts the development server where either the command line or the configuration asks for one.
+ *
+ * @param config - Configuration read for its `serve` block
+ * @param args - Parsed command line the run was started with
+ * @param screen - Screen the server reports through
+ * @returns A promise settling once the server is listening, at once when none was asked for
+ *
+ * @remarks
+ * `--serve` carries the directory to serve, so asking for a server and choosing what it serves are the one flag,
+ * and a configuration that starts one of its own is honored even where the flag is absent.
+ * The directory falls back to the configured one and then to `dist`, which is where a build writes by default.
+ * The server reports through the screen rather than to the console,
+ * so its address reaches the status line and its requests are held to the level the run reports at.
+ *
+ * @example
+ * ```ts
+ * // xBuild --serve dist
+ * await startServer(config, args, screen);
+ * // [xBuild] → serve http://localhost:3000
+ * ```
+ *
+ * @see ServerModule
+ * @since 3.0.0
+ */
+declare function startServer(config: xBuildConfigInterface, args: ArgumentsInterface, screen: Screen): Promise<void>;
+/**
+ * Watches the project, rebuilds on a change, and takes the terminal for the shortcuts.
+ *
+ * @param buildService - Service the rebuilds run through
+ * @param config - Configuration read for its `watch` block, and replaced when its file changes
+ * @param args - Parsed command line the run was started with
+ * @param screen - Screen the rebuilds are announced on
+ * @returns A promise settling once the keys are listened for, at once when no watch was asked for
+ *
+ * @remarks
+ * A run is watched where `--watch` asked for it, and also where a server is serving,
+ * since output nobody rebuilds is not worth serving.
+ * A change refreshes the file model before anything is rebuilt,
+ * so the rebuild reads the files as they now are rather than as they were read the first time.
+ * Reloading the TypeScript configuration belongs to the screen rather than to the watch,
+ * which puts a rebuild started by a key on the same footing as one started by a change.
+ * The configuration file is watched by its own version rather than by its path,
+ * so an edit to it is reparsed and reapplied while every other change goes straight to a rebuild.
+ * The shortcuts are listened for last, since they take the last row of the terminal,
+ * and a run that never reaches here leaves the terminal as it found it.
+ *
+ * @example
+ * ```ts
+ * // xBuild --watch
+ * await startWatchMode(build, config, args, screen);
+ * // [xBuild] ↻ rebuild 2 files changed
+ * ```
+ *
+ * @see WatchService
+ * @see startInteractive
+ *
+ * @since 3.0.0
+ */
+declare function startWatchMode(buildService: BuildService, config: xBuildConfigInterface, args: ArgumentsInterface, screen: Screen): Promise<void>;
+
+export {
+	applyCommandLineOverrides,
+	configureEntryPoints,
+	startServer,
+	startWatchMode
+};