powerlines 0.19.4 → 0.20.0

package/dist/lib/{config-B8PZKdIr.d.cts → config-DN8Ad0lv.d.cts}

@@ -21,7 +21,7 @@ import { Jiti } from 'jiti';
 import MagicString, { SourceMap } from 'magic-string';
 import { ParserOptions, ParseResult } from 'oxc-parser';
 import { Range } from 'semver';
-import { TransformResult as TransformResult$1, ExternalIdResult, HookFilter, UnpluginOptions, UnpluginContext, UnpluginBuildContext, UnpluginMessage } from 'unplugin';
+import { TransformResult as TransformResult$1, ExternalIdResult, HookFilter, UnpluginOptions, UnpluginContext, UnpluginMessage, UnpluginBuildContext } from 'unplugin';
 import { ArrayValues } from '@stryke/types/array';
 import { P as ParsedTypeScriptConfig, T as TSConfig } from './tsconfig-Bz-CiFqD.cjs';
 import { PrimitiveJsonValue } from '@stryke/json/types';
@@ -39,6 +39,73 @@ interface BuildConfig {
      * @defaultValue "neutral"
      */
     platform?: "node" | "browser" | "neutral";
+    /**
+     * Array of strings indicating the order in which fields in a package.json file should be resolved to determine the entry point for a module.
+     *
+     * @defaultValue `['browser', 'module', 'jsnext:main', 'jsnext']`
+     */
+    mainFields?: string[];
+    /**
+     * Array of strings indicating what conditions should be used for module resolution.
+     */
+    conditions?: string[];
+    /**
+     * Array of strings indicating what file extensions should be used for module resolution.
+     *
+     * @defaultValue `['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']`
+     */
+    extensions?: string[];
+    /**
+     * Array of strings indicating what modules should be deduplicated to a single version in the build.
+     *
+     * @remarks
+     * This option is useful for ensuring that only one version of a module is included in the bundle, which can help reduce bundle size and avoid conflicts.
+     */
+    dedupe?: string[];
+    /**
+     * Array of strings or regular expressions that indicate what modules are builtin for the environment.
+     */
+    builtins?: (string | RegExp)[];
+    /**
+     * Define global variable replacements.
+     *
+     * @remarks
+     * This option allows you to specify global constants that will be replaced in the code during the build process. It is similar to the `define` option in esbuild and Vite, enabling you to replace specific identifiers with constant expressions at build time.
+     *
+     * @example
+     * ```ts
+     * {
+     *   define: {
+     *     __VERSION__: '"1.0.0"',
+     *     __DEV__: 'process.env.NODE_ENV !== "production"'
+     *   }
+     * }
+     * ```
+     *
+     * @see https://esbuild.github.io/api/#define
+     * @see https://vitejs.dev/config/build-options.html#define
+     * @see https://github.com/rollup/plugins/tree/master/packages/replace
+     */
+    define?: Record<string, any>;
+    /**
+     * Global variables that will have import statements injected where necessary
+     *
+     * @remarks
+     * This option allows you to specify global variables that should be automatically imported from specified modules whenever they are used in the code. This is particularly useful for polyfilling Node.js globals in a browser environment.
+     *
+     * @example
+     * ```ts
+     * {
+     *   inject: {
+     *     process: 'process/browser',
+     *     Buffer: ['buffer', 'Buffer'],
+     *   }
+     * }
+     * ```
+     *
+     * @see https://github.com/rollup/plugins/tree/master/packages/inject
+     */
+    inject?: Record<string, string | string[]>;
     /**
      * The alias mappings to use for module resolution during the build process.
      *
@@ -54,6 +121,8 @@ interface BuildConfig {
      *   }
      * }
      * ```
+     *
+     * @see https://github.com/rollup/plugins/tree/master/packages/alias
      */
     alias?: Record<string, string>;
     /**
@@ -72,15 +141,16 @@ interface BuildConfig {
      */
     skipNodeModulesBundle?: boolean;
     /**
-     * Should the Powerlines processes skip the `"prepare"` task prior to building?
+     * An optional set of override options to apply to the selected build variant.
      *
-     * @defaultValue false
+     * @remarks
+     * This option allows you to provide configuration options with the guarantee that they will **not** be overridden and will take precedence over other build configurations.
      */
-    skipPrepare?: boolean;
+    override?: Record<string, any>;
 }
-type BuildResolvedConfig = BuildConfig;
-type ESBuildBuildConfig = Omit<BuildOptions, "entryPoints" | "sourceRoot" | "platform" | "outdir" | "env" | "assets" | "external" | "tsconfig" | "tsconfigRaw" | "logLevel"> & BuildConfig;
-type ESBuildResolvedBuildConfig = BuildOptions & BuildResolvedConfig;
+type BuildResolvedConfig = Omit<BuildConfig, "override">;
+type ESBuildBuildConfig = Omit<BuildOptions, "entryPoints" | "sourceRoot" | "platform" | "outdir" | "env" | "assets" | "external" | "inject" | "tsconfig" | "tsconfigRaw" | "logLevel"> & BuildConfig;
+type ESBuildResolvedBuildConfig = Omit<BuildOptions, "inject"> & BuildResolvedConfig;
 type ViteBuildConfig = Omit<UserConfig$1, "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw" | "environments" | "output"> & BuildConfig;
 type ViteResolvedBuildConfig = UserConfig$1 & BuildResolvedConfig;
 type WebpackBuildConfig = Omit<Configuration, "name" | "entry" | "entryPoints" | "tsconfig" | "tsconfigRaw"> & BuildConfig;
@@ -117,7 +187,7 @@ interface ResolvedEntryTypeDefinition extends TypeDefinition {
      */
     output?: string;
 }
-type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview" | "mainFields" | "extensions"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr" | "mainFields" | "extensions">> & {
+type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr">> & {
     /**
      * The name of the environment
      */
@@ -134,7 +204,7 @@ type OutputResolvedConfig = Required<Omit<OutputConfig, "assets"> & {
 /**
  * The resolved options for the Powerlines project configuration.
  */
-type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "platform" | "tsconfig" | "lint" | "test" | "build" | "transform" | "override" | "root" | "variant" | "type" | "output" | "logLevel" | "framework"> & Required<Pick<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "tsconfig" | "lint" | "test" | "build" | "transform" | "override" | "framework">> & {
+type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "platform" | "tsconfig" | "lint" | "test" | "build" | "transform" | "variant" | "type" | "output" | "logLevel" | "framework"> & Required<Pick<TUserConfig, "name" | "title" | "plugins" | "mode" | "environments" | "tsconfig" | "lint" | "test" | "build" | "transform" | "framework">> & {
     /**
      * The configuration options that were provided inline to the Powerlines CLI.
      */
@@ -165,6 +235,13 @@ type ResolvedConfig<TUserConfig extends UserConfig = UserConfig> = Omit<TUserCon
      * The output configuration options to use for the build process
      */
     output: OutputResolvedConfig;
+    /**
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
+     */
+    build: Omit<TUserConfig["build"], "override"> & Required<Pick<Required<TUserConfig["build"]>, "override">>;
     /**
      * The log level to use for the Powerlines processes.
      *
@@ -205,6 +282,10 @@ interface GenerateTypesResult {
     directives?: string[];
     code: string;
 }
+type DeepPartial<T> = {
+    [K in keyof T]?: DeepPartial<T[K]>;
+};
+type ConfigResult<TContext extends PluginContext = PluginContext> = DeepPartial<TContext["config"]> & Record<string, any>;
 interface BasePluginHookFunctions<TContext extends PluginContext = PluginContext> extends Record<CommandType, (this: TContext) => MaybePromise<void>> {
     /**
      * A function that returns configuration options to be merged with the build context's options.
@@ -220,7 +301,7 @@ interface BasePluginHookFunctions<TContext extends PluginContext = PluginContext
      * @param config - The partial configuration object to be modified.
      * @returns A promise that resolves to a partial configuration object.
      */
-    config: (this: Context<TContext["config"]>) => MaybePromise<Partial<TContext["config"]["userConfig"]>>;
+    config: (this: UnresolvedContext<TContext["config"]>) => MaybePromise<ConfigResult<TContext>>;
     /**
      * Modify environment configs before it's resolved. The hook can either mutate the passed-in environment config directly, or return a partial config object that will be deeply merged into existing config.
      *
@@ -328,7 +409,7 @@ type PluginHooks<TContext extends PluginContext = PluginContext> = {
      * @param config - The partial configuration object to be modified.
      * @returns A promise that resolves to a partial configuration object.
      */
-    config: PluginHook<(this: Context<TContext["config"]>) => MaybePromise<Partial<TContext["config"]["userConfig"]>>> | Partial<TContext["config"]["userConfig"]>;
+    config: PluginHook<(this: UnresolvedContext<TContext["config"]>) => MaybePromise<ConfigResult<TContext>>> | ConfigResult<TContext>;
     /**
      * A hook that is called to transform the source code.
      *
@@ -902,7 +983,13 @@ interface InitContextOptions {
      */
     isHighPriority: boolean;
 }
-interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+/**
+ * The unresolved Powerlines context.
+ *
+ * @remarks
+ * This context is used before the user configuration has been fully resolved after the `config`.
+ */
+interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
     /**
      * The Storm workspace configuration
      */
@@ -910,7 +997,10 @@ interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
     /**
      * An object containing the options provided to Powerlines
      */
-    config: TResolvedConfig;
+    config: Omit<TResolvedConfig["userConfig"], "build" | "output"> & Required<Pick<TResolvedConfig["userConfig"], "build" | "output">> & {
+        projectRoot: NonUndefined<TResolvedConfig["userConfig"]["root"]>;
+        output: TResolvedConfig["output"];
+    };
     /**
      * A logging function for the Powerlines engine
      */
@@ -1067,6 +1157,12 @@ interface Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
      */
     extendLog: (name: string) => LogFn;
 }
+type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<UnresolvedContext<TResolvedConfig>, "config"> & {
+    /**
+     * The fully resolved Powerlines configuration
+     */
+    config: TResolvedConfig;
+};
 interface APIContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
     /**
      * The expected plugins options for the Powerlines project.
@@ -1301,24 +1397,33 @@ interface BaseConfig {
      * The entry point(s) for the application
      */
     entry?: TypeDefinitionParameter | TypeDefinitionParameter[];
+    /**
+     * Configuration for the output of the build process
+     */
+    output?: OutputConfig;
     /**
      * Configuration for linting the source code
+     *
+     * @remarks
+     * If set to `false`, linting will be disabled.
      */
     lint?: Record<string, any> | false;
     /**
      * Configuration for testing the source code
+     *
+     * @remarks
+     * If set to `false`, testing will be disabled.
      */
     test?: Record<string, any> | false;
-    /**
-     * Configuration for the output of the build process
-     */
-    output?: OutputConfig;
     /**
      * Configuration for the transformation of the source code
      */
     transform?: Record<string, any>;
     /**
-     * Options to to provide to the build process
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
      */
     build?: BuildConfig;
     /**
@@ -1348,37 +1453,6 @@ interface BaseConfig {
     tsconfigRaw?: TSConfig;
 }
 interface EnvironmentConfig extends BaseConfig {
-    /**
-     * Array of strings indicating the order in which fields in a package.json file should be resolved to determine the entry point for a module.
-     *
-     * @defaultValue `['browser', 'module', 'jsnext:main', 'jsnext']`
-     */
-    mainFields?: string[];
-    /**
-     * Array of strings indicating what conditions should be used for module resolution.
-     */
-    conditions?: string[];
-    /**
-     * Array of strings indicating what conditions should be used for external modules.
-     */
-    externalConditions?: string[];
-    /**
-     * Array of strings indicating what file extensions should be used for module resolution.
-     *
-     * @defaultValue `['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']`
-     */
-    extensions?: string[];
-    /**
-     * Array of strings indicating what modules should be deduplicated to a single version in the build.
-     *
-     * @remarks
-     * This option is useful for ensuring that only one version of a module is included in the bundle, which can help reduce bundle size and avoid conflicts.
-     */
-    dedupe?: string[];
-    /**
-     * Array of strings or regular expressions that indicate what modules are builtin for the environment.
-     */
-    builtins?: (string | RegExp)[];
     /**
      * Configuration options for the preview server
      */
@@ -1451,14 +1525,26 @@ interface CommonUserConfig extends BaseConfig {
      */
     framework?: string;
 }
-type UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> = CommonUserConfig & {
-    build?: TBuildConfig & {
+type UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> = Omit<CommonUserConfig, "build"> & {
+    /**
+     * Configuration provided to build processes
+     *
+     * @remarks
+     * This configuration can be used by plugins during the `build` command. It will generally contain options specific to the selected {@link BuildVariant | build variant}.
+     */
+    build: Omit<TBuildConfig, "override"> & {
         /**
          * The build variant being used by the Powerlines engine.
          */
         variant?: TBuildVariant;
+        /**
+         * An optional set of override options to apply to the selected build variant.
+         *
+         * @remarks
+         * This option allows you to provide configuration options with the guarantee that they will **not** be overridden and will take precedence over other build configurations.
+         */
+        override?: Partial<TBuildResolvedConfig>;
     };
-    override?: Partial<TBuildResolvedConfig>;
 };
 type WebpackUserConfig = UserConfig<WebpackBuildConfig, WebpackResolvedBuildConfig, "webpack">;
 type RspackUserConfig = UserConfig<RspackBuildConfig, RspackResolvedBuildConfig, "rspack">;
@@ -1539,4 +1625,4 @@ type ReleaseInlineConfig<TUserConfig extends UserConfig = UserConfig> = InlineCo
     command: "release";
 };
 
-export type { APIContext as A, BuildVariant as B, Context as C, DocsInlineConfig as D, ESBuildResolvedBuildConfig as E, HookKeys as H, InferHookParameters as I, LogFn as L, MetaInfo as M, NewInlineConfig as N, PowerlinesCommand as P, ResolvedEntryTypeDefinition as R, SourceFile as S, TransformResult as T, UnbuildBuildConfig as U, ViteResolvedBuildConfig as V, WorkspaceConfig as W, ParsedUserConfig as a, WorkerProcess as b, RolldownResolvedBuildConfig as c, RollupResolvedBuildConfig as d, TsupBuildConfig as e, TsupResolvedBuildConfig as f, PluginContext as g, SelectHooksOptions as h, ResolvedConfig as i, EnvironmentContext as j, InferHookReturnType as k, UnbuildResolvedBuildConfig as l, InferUnpluginVariant as m, BuildPlugin as n, InferResolvedConfig as o, UnpluginBuildVariant as p, InferUserConfig as q, InitialUserConfig as r, PrepareInlineConfig as s, CleanInlineConfig as t, BuildInlineConfig as u, LintInlineConfig as v, ReleaseInlineConfig as w };
+export type { APIContext as A, BuildVariant as B, Context as C, DocsInlineConfig as D, ESBuildResolvedBuildConfig as E, HookKeys as H, InferHookParameters as I, LogFn as L, MetaInfo as M, NewInlineConfig as N, PowerlinesCommand as P, ResolvedEntryTypeDefinition as R, SelectHooksOptions as S, TsupBuildConfig as T, UnbuildBuildConfig as U, ViteResolvedBuildConfig as V, WorkspaceConfig as W, ParsedUserConfig as a, RolldownResolvedBuildConfig as b, RollupResolvedBuildConfig as c, TsupResolvedBuildConfig as d, PluginContext as e, SourceFile as f, TransformResult as g, WorkerProcess as h, ResolvedConfig as i, EnvironmentContext as j, InferHookReturnType as k, UnbuildResolvedBuildConfig as l, InferUnpluginVariant as m, BuildPlugin as n, InferResolvedConfig as o, UnpluginBuildVariant as p, InferUserConfig as q, InitialUserConfig as r, PrepareInlineConfig as s, CleanInlineConfig as t, BuildInlineConfig as u, LintInlineConfig as v, ReleaseInlineConfig as w };

package/dist/lib/config-file.d.cts

@@ -1,5 +1,5 @@
 import { Jiti } from 'jiti';
-import { C as Context, W as WorkspaceConfig, P as PowerlinesCommand, a as ParsedUserConfig } from './config-B8PZKdIr.cjs';
+import { C as Context, W as WorkspaceConfig, P as PowerlinesCommand, a as ParsedUserConfig } from './config-DN8Ad0lv.cjs';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';

package/dist/lib/config-file.d.ts

@@ -1,5 +1,5 @@
 import { Jiti } from 'jiti';
-import { C as Context, W as WorkspaceConfig, P as PowerlinesCommand, a as ParsedUserConfig } from './config-gWvjY0K0.js';
+import { C as Context, W as WorkspaceConfig, P as PowerlinesCommand, a as ParsedUserConfig } from './config-Bag1Ft7u.js';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';

package/dist/lib/create-program.d.cts

@@ -1,5 +1,5 @@
 import { Project } from 'ts-morph';
-import { C as Context } from './config-B8PZKdIr.cjs';
+import { C as Context } from './config-DN8Ad0lv.cjs';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';

package/dist/lib/create-program.d.ts

@@ -1,5 +1,5 @@
 import { Project } from 'ts-morph';
-import { C as Context } from './config-gWvjY0K0.js';
+import { C as Context } from './config-Bag1Ft7u.js';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';

package/dist/lib/entry.d.cts

@@ -1,5 +1,5 @@
 import { TypeDefinition, TypeDefinitionParameter } from '@stryke/types/configuration';
-import { C as Context, R as ResolvedEntryTypeDefinition } from './config-B8PZKdIr.cjs';
+import { C as Context, R as ResolvedEntryTypeDefinition } from './config-DN8Ad0lv.cjs';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';

package/dist/lib/entry.d.ts

@@ -1,5 +1,5 @@
 import { TypeDefinition, TypeDefinitionParameter } from '@stryke/types/configuration';
-import { C as Context, R as ResolvedEntryTypeDefinition } from './config-gWvjY0K0.js';
+import { C as Context, R as ResolvedEntryTypeDefinition } from './config-Bag1Ft7u.js';
 import '@storm-software/build-tools/types';
 import '@storm-software/config-tools/types';
 import '@storm-software/config/types';

package/dist/lib/{hooks-BL4stJLn.d.ts → hooks-BVnPAWgt.d.ts}

@@ -1,4 +1,4 @@
-import { h as SelectHooksOptions } from './config-gWvjY0K0.js';
+import { S as SelectHooksOptions } from './config-Bag1Ft7u.js';
 
 type CallHookOptions = SelectHooksOptions & ({
     /**

package/dist/lib/{hooks-DnWcaiLo.d.cts → hooks-H2P-7xA4.d.cts}

@@ -1,4 +1,4 @@
-import { h as SelectHooksOptions } from './config-B8PZKdIr.cjs';
+import { S as SelectHooksOptions } from './config-DN8Ad0lv.cjs';
 
 type CallHookOptions = SelectHooksOptions & ({
     /**