@powerlines/plugin-oxc-transform 0.5.66 → 0.5.68

package/dist/powerlines/src/types/config.d.mts

@@ -0,0 +1,345 @@
+import { BuildConfig, BuildResolvedConfig } from "./build.mjs";
+import { StoragePort, StoragePreset } from "./fs.mjs";
+import { TSConfig } from "./tsconfig.mjs";
+import { PluginContext } from "./context.mjs";
+import { Plugin } from "./plugin.mjs";
+import { MaybePromise } from "@stryke/types/base";
+import { PreviewOptions } from "vite";
+import { Format } from "@storm-software/build-tools/types";
+import { LogLevelLabel } from "@storm-software/config-tools/types";
+import { StormWorkspaceConfig } from "@storm-software/config/types";
+import { TypeDefinitionParameter } from "@stryke/types/configuration";
+import { AssetGlob } from "@stryke/types/file";
+
+//#region ../powerlines/src/types/config.d.ts
+
+type LogFn = (type: LogLevelLabel, ...args: string[]) => void;
+/**
+ * The {@link StormWorkspaceConfig | configuration} object for an entire Powerlines workspace
+ */
+type WorkspaceConfig = Partial<StormWorkspaceConfig> & Required<Pick<StormWorkspaceConfig, "workspaceRoot">>;
+type PluginFactory<in out TContext extends PluginContext = PluginContext, TOptions = any> = (options: TOptions) => MaybePromise<Plugin<TContext>>;
+/**
+ * A configuration tuple for a Powerlines plugin.
+ */
+type PluginConfigTuple<TContext extends PluginContext = PluginContext, TOptions = any> = [string | PluginFactory<TContext, TOptions>, TOptions] | [Plugin<TContext>];
+/**
+ * A configuration object for a Powerlines plugin.
+ */
+type PluginConfigObject<TContext extends PluginContext = PluginContext, TOptions = any> = {
+  plugin: string | PluginFactory<TContext, TOptions>;
+  options: TOptions;
+} | {
+  plugin: Plugin<TContext>;
+  options?: never;
+};
+/**
+ * A configuration tuple for a Powerlines plugin.
+ */
+type PluginConfig<TContext extends PluginContext = PluginContext> = string | PluginFactory<TContext, void> | Plugin<TContext> | Promise<Plugin<TContext>> | PluginConfigTuple<TContext> | PluginConfigObject<TContext>;
+type ProjectType = "application" | "library";
+interface DeployConfig {
+  /**
+   * The deployment variant being used by the Powerlines engine.
+   *
+   * @example
+   * ```ts
+   * export default defineConfig({
+   *  deploy: {
+   *    variant: "cloudflare"
+   *  }
+   * });
+   *
+   * ```
+   */
+  variant?: string;
+}
+interface OutputConfig {
+  /**
+   * The path to output the final compiled files to
+   *
+   * @remarks
+   * If a value is not provided, Powerlines will attempt to:
+   * 1. Use the `outDir` value in the `tsconfig.json` file.
+   * 2. Use the `dist` directory in the project root directory.
+   *
+   * @defaultValue "dist/\{projectRoot\}"
+   */
+  outputPath?: string;
+  /**
+   * The output directory path for the project build.
+   *
+   * @remarks
+   * This path is used to determine where the built files will be placed after the build process completes. This will be used in scenarios where the monorepo uses TSConfig paths to link packages together.
+   *
+   * @defaultValue "\{projectRoot\}/dist"
+   */
+  buildPath?: string;
+  /**
+   * The folder where the generated runtime artifacts will be located
+   *
+   * @remarks
+   * This folder will contain all runtime artifacts and builtins generated during the "prepare" phase.
+   *
+   * @defaultValue "\{projectRoot\}/.powerlines"
+   */
+  artifactsPath?: string;
+  /**
+   * The path of the generated runtime declaration file relative to the workspace root.
+   *
+   * @defaultValue "\{projectRoot\}/powerlines.d.ts"
+   */
+  dts?: string | false;
+  /**
+   * A prefix to use for identifying builtin modules
+   *
+   * @remarks
+   * This prefix will be used to identify all builtin modules generated during the "prepare" phase. An example builtin ID for a module called `"utils"` would be `"{builtinPrefix}:utils"`.
+   *
+   * @defaultValue "powerlines"
+   */
+  builtinPrefix?: string;
+  /**
+   * The module format of the output files
+   *
+   * @remarks
+   * This option can be a single format or an array of formats. If an array is provided, multiple builds will be generated for each format.
+   *
+   * @defaultValue "esm"
+   */
+  format?: Format | Format[];
+  /**
+   * A list of assets to copy to the output directory
+   *
+   * @remarks
+   * The assets can be specified as a string (path to the asset) or as an object with a `glob` property (to match multiple files). The paths are relative to the project root directory.
+   */
+  assets?: Array<string | AssetGlob>;
+  /**
+   * A string preset or a custom {@link StoragePort} to provide fine-grained control over generated/output file storage.
+   *
+   * @remarks
+   * If a string preset is provided, it must be one of the following values:
+   * - `"virtual"`: Uses the local file system for storage.
+   * - `"fs"`: Uses an in-memory virtual file system for storage.
+   *
+   * If a custom {@link StoragePort} is provided, it will be used for all file storage operations during the build process.
+   *
+   * @defaultValue "virtual"
+   */
+  storage?: StoragePort | StoragePreset;
+}
+interface BaseConfig {
+  /**
+   * The entry point(s) for the application
+   */
+  entry?: TypeDefinitionParameter | TypeDefinitionParameter[];
+  /**
+   * Configuration for the output of the build process
+   */
+  output?: OutputConfig;
+  /**
+   * Configuration for cleaning the build artifacts
+   *
+   * @remarks
+   * If set to `false`, the cleaning process will be disabled.
+   */
+  clean?: Record<string, any> | false;
+  /**
+   * 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 transformation of the source code
+   */
+  transform?: Record<string, any>;
+  /**
+   * 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;
+  /**
+   * Configuration for documentation generation
+   *
+   * @remarks
+   * This configuration will be used by the documentation generation plugins during the `docs` command.
+   */
+  docs?: Record<string, any>;
+  /**
+   * Configuration for deploying the source code
+   *
+   * @remarks
+   * If set to `false`, the deployment will be disabled.
+   */
+  deploy?: DeployConfig | false;
+  /**
+   * The path to the tsconfig file to be used by the compiler
+   *
+   * @remarks
+   * If a value is not provided, the plugin will attempt to find the `tsconfig.json` file in the project root directory. The parsed tsconfig compiler options will be merged with the {@link Options.tsconfigRaw} value (if provided).
+   *
+   * @defaultValue "\{projectRoot\}/tsconfig.json"
+   */
+  tsconfig?: string;
+  /**
+   * The raw {@link TSConfig} object to be used by the compiler. This object will be merged with the `tsconfig.json` file.
+   *
+   * @see https://www.typescriptlang.org/tsconfig
+   *
+   * @remarks
+   * If populated, this option takes higher priority than `tsconfig`
+   */
+  tsconfigRaw?: TSConfig;
+}
+interface EnvironmentConfig extends BaseConfig {
+  /**
+   * Configuration options for the preview server
+   */
+  preview?: PreviewOptions;
+  /**
+   * A flag indicating whether the build is for a Server-Side Rendering environment.
+   */
+  ssr?: boolean;
+  /**
+   * Define if this environment is used for Server-Side Rendering
+   *
+   * @defaultValue "server" (if it isn't the client environment)
+   */
+  consumer?: "client" | "server";
+}
+interface CommonUserConfig extends BaseConfig {
+  /**
+   * The name of the project
+   */
+  name?: string;
+  /**
+   * The project display title
+   *
+   * @remarks
+   * This option is used in documentation generation and other places where a human-readable title is needed.
+   */
+  title?: string;
+  /**
+   * A description of the project
+   *
+   * @remarks
+   * If this option is not provided, the build process will try to use the \`description\` value from the `\package.json\` file.
+   */
+  description?: string;
+  /**
+   * The log level to use for the Powerlines processes.
+   *
+   * @defaultValue "info"
+   */
+  logLevel?: LogLevelLabel | null;
+  /**
+   * A custom logger function to use for logging messages
+   */
+  customLogger?: LogFn;
+  /**
+   * Explicitly set a mode to run in. This mode will be used at various points throughout the Powerlines processes, such as when compiling the source code.
+   *
+   * @defaultValue "production"
+   */
+  mode?: "development" | "test" | "production";
+  /**
+   * The type of project being built
+   *
+   * @defaultValue "application"
+   */
+  type?: ProjectType;
+  /**
+   * The root directory of the project
+   */
+  root: string;
+  /**
+   * The root directory of the project's source code
+   *
+   * @defaultValue "\{root\}/src"
+   */
+  sourceRoot?: string;
+  /**
+   * A path to a custom configuration file to be used instead of the default `storm.json`, `powerlines.config.js`, or `powerlines.config.ts` files.
+   *
+   * @remarks
+   * This option is useful for running Powerlines commands with different configuration files, such as in CI/CD environments or when testing different configurations.
+   */
+  configFile?: string;
+  /**
+   * Should the Powerlines CLI processes skip installing missing packages?
+   *
+   * @remarks
+   * This option is useful for CI/CD environments where the installation of packages is handled by a different process.
+   *
+   * @defaultValue false
+   */
+  skipInstalls?: boolean;
+  /**
+   * Should the compiler processes skip any improvements that make use of cache?
+   *
+   * @defaultValue false
+   */
+  skipCache?: boolean;
+  /**
+   * A list of resolvable paths to plugins used during the build process
+   */
+  plugins?: PluginConfig<PluginContext<any>>[];
+  /**
+   * Environment-specific configurations
+   */
+  environments?: Record<string, EnvironmentConfig>;
+  /**
+   * A string identifier that allows a child framework or tool to identify itself when using Powerlines.
+   *
+   * @remarks
+   * If no values are provided for {@link OutputConfig.dts | output.dts}, {@link OutputConfig.builtinPrefix | output.builtinPrefix}, or {@link OutputConfig.artifactsPath | output.artifactsFolder}, this value will be used as the default.
+   *
+   * @defaultValue "powerlines"
+   */
+  framework?: string;
+}
+interface UserConfig<TBuildConfig extends BuildConfig = BuildConfig, TBuildResolvedConfig extends BuildResolvedConfig = BuildResolvedConfig, TBuildVariant extends string = any> extends 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>;
+  };
+}
+type PowerlinesCommand = "new" | "prepare" | "build" | "lint" | "test" | "docs" | "deploy" | "clean";
+/**
+ * The configuration provided while executing Powerlines commands.
+ */
+type InlineConfig<TUserConfig extends UserConfig = UserConfig> = Partial<TUserConfig> & {
+  /**
+   * A string identifier for the Powerlines command being executed
+   */
+  command: PowerlinesCommand;
+};
+//#endregion
+export { EnvironmentConfig, InlineConfig, LogFn, OutputConfig, PluginConfig, UserConfig, WorkspaceConfig };

package/dist/powerlines/src/types/context.d.cts

@@ -0,0 +1,347 @@
+import { ResolveOptions, VirtualFile, VirtualFileSystemInterface } from "./fs.cjs";
+import { ParsedTypeScriptConfig } from "./tsconfig.cjs";
+import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.cjs";
+import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.cjs";
+import { NonUndefined } from "@stryke/types/base";
+import { ExternalIdResult, UnpluginBuildContext, UnpluginContext, UnpluginMessage } from "unplugin";
+import { EnvPaths } from "@stryke/env/get-env-paths";
+import { FetchRequestOptions } from "@stryke/http/fetch";
+import { PackageJson } from "@stryke/types/package-json";
+import { Jiti } from "jiti";
+import { SourceMap } from "magic-string";
+import { ParseResult, ParserOptions } from "oxc-parser";
+import { Range } from "semver";
+import { Project } from "ts-morph";
+import { RequestInfo, Response } from "undici";
+
+//#region ../powerlines/src/types/context.d.ts
+
+interface MetaInfo {
+  /**
+   * The checksum generated from the resolved options
+   */
+  checksum: string;
+  /**
+   * The build id
+   */
+  buildId: string;
+  /**
+   * The release id
+   */
+  releaseId: string;
+  /**
+   * The build timestamp
+   */
+  timestamp: number;
+  /**
+   * A hash that represents the path to the project root directory
+   */
+  projectRootHash: string;
+  /**
+   * A hash that represents the path to the project root directory
+   */
+  configHash: string;
+}
+interface Resolver extends Jiti {
+  plugin: Jiti;
+}
+interface TransformResult$1 {
+  code: string;
+  map: SourceMap | null;
+}
+interface InitContextOptions {
+  /**
+   * If false, the plugin will be loaded after all other plugins.
+   *
+   * @defaultValue true
+   */
+  isHighPriority: boolean;
+}
+interface FetchOptions extends FetchRequestOptions {
+  /**
+   * An indicator specifying that the request should bypass any caching
+   */
+  skipCache?: boolean;
+}
+interface ParseOptions extends ParserOptions {
+  /**
+   * When true this allows return statements to be outside functions to e.g. support parsing CommonJS code.
+   */
+  allowReturnOutsideFunction?: boolean;
+}
+/**
+ * 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
+   */
+  workspaceConfig: WorkspaceConfig;
+  /**
+   * An object containing the options provided to Powerlines
+   */
+  config: Omit<TResolvedConfig["userConfig"], "build" | "output"> & Required<Pick<TResolvedConfig["userConfig"], "build" | "output">> & {
+    projectRoot: NonUndefined<TResolvedConfig["userConfig"]["root"]>;
+    sourceRoot: NonUndefined<TResolvedConfig["userConfig"]["sourceRoot"]>;
+    output: TResolvedConfig["output"];
+  };
+  /**
+   * A logging function for the Powerlines engine
+   */
+  log: LogFn;
+  /**
+   * A logging function for fatal messages
+   */
+  fatal: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for error messages
+   */
+  error: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for warning messages
+   */
+  warn: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for informational messages
+   */
+  info: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for debug messages
+   */
+  debug: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for trace messages
+   */
+  trace: (message: string | UnpluginMessage) => void;
+  /**
+   * The metadata information
+   */
+  meta: MetaInfo;
+  /**
+   * The metadata information currently written to disk
+   */
+  persistedMeta?: MetaInfo;
+  /**
+   * The Powerlines artifacts directory
+   */
+  artifactsPath: string;
+  /**
+   * The path to the Powerlines builtin runtime modules directory
+   */
+  builtinsPath: string;
+  /**
+   * The path to the Powerlines entry modules directory
+   */
+  entryPath: string;
+  /**
+   * The path to the Powerlines TypeScript declaration files directory
+   */
+  dtsPath: string;
+  /**
+   * The path to a directory where the reflection data buffers (used by the build processes) are stored
+   */
+  dataPath: string;
+  /**
+   * The path to a directory where the project cache (used by the build processes) is stored
+   */
+  cachePath: string;
+  /**
+   * The Powerlines environment paths
+   */
+  envPaths: EnvPaths;
+  /**
+   * The file system path to the Powerlines package installation
+   */
+  powerlinesPath: string;
+  /**
+   * The relative path to the Powerlines workspace root directory
+   */
+  relativeToWorkspaceRoot: string;
+  /**
+   * The project's `package.json` file content
+   */
+  packageJson: PackageJson & Record<string, any>;
+  /**
+   * The project's `project.json` file content
+   */
+  projectJson?: Record<string, any>;
+  /**
+   * The dependency installations required by the project
+   */
+  dependencies: Record<string, string | Range>;
+  /**
+   * The development dependency installations required by the project
+   */
+  devDependencies: Record<string, string | Range>;
+  /**
+   * The parsed TypeScript configuration from the `tsconfig.json` file
+   */
+  tsconfig: ParsedTypeScriptConfig;
+  /**
+   * The entry points of the source code
+   */
+  entry: ResolvedEntryTypeDefinition[];
+  /**
+   * The virtual file system manager used during the build process to reference generated runtime files
+   */
+  fs: VirtualFileSystemInterface;
+  /**
+   * The Jiti module resolver
+   */
+  resolver: Resolver;
+  /**
+   * The builtin module id that exist in the Powerlines virtual file system
+   */
+  builtins: string[];
+  /**
+   * The {@link Project} instance used for type reflection and module manipulation
+   *
+   * @see https://ts-morph.com/
+   *
+   * @remarks
+   * This instance is created lazily on first access.
+   */
+  program: Project;
+  /**
+   * A function to perform HTTP fetch requests
+   *
+   * @remarks
+   * This function uses a caching layer to avoid duplicate requests during the Powerlines process.
+   *
+   * @example
+   * ```ts
+   * const response = await context.fetch("https://api.example.com/data");
+   * const data = await response.json();
+   * ```
+   *
+   * @see https://github.com/nodejs/undici
+   *
+   * @param input - The URL to fetch.
+   * @param options - The fetch request options.
+   * @returns A promise that resolves to a response returned by the fetch.
+   */
+  fetch: (input: RequestInfo, options?: FetchOptions) => Promise<Response>;
+  /**
+   * Parse code using [Oxc-Parser](https://github.com/oxc/oxc) into an (ESTree-compatible)[https://github.com/estree/estree] AST object.
+   *
+   * @remarks
+   * This function can be used to parse TypeScript code into an AST for further analysis or transformation.
+   *
+   * @example
+   * ```ts
+   * const ast = context.parse("const x: number = 42;");
+   * ```
+   *
+   * @see https://rollupjs.org/plugin-development/#this-parse
+   * @see https://github.com/oxc/oxc
+   *
+   * @param code - The source code to parse.
+   * @param options - The options to pass to the parser.
+   * @returns An (ESTree-compatible)[https://github.com/estree/estree] AST object.
+   */
+  parse: (code: string, options?: ParseOptions) => Promise<ParseResult>;
+  /**
+   * A helper function to resolve modules using the Jiti resolver
+   *
+   * @remarks
+   * This function can be used to resolve modules relative to the project root directory.
+   *
+   * @example
+   * ```ts
+   * const resolvedPath = await context.resolve("some-module", "/path/to/importer");
+   * ```
+   *
+   * @param id - The module to resolve.
+   * @param importer - An optional path to the importer module.
+   * @param options - Additional resolution options.
+   * @returns A promise that resolves to the resolved module path.
+   */
+  resolve: (id: string, importer?: string, options?: ResolveOptions) => Promise<ExternalIdResult | undefined>;
+  /**
+   * A helper function to load modules using the Jiti resolver
+   *
+   * @remarks
+   * This function can be used to load modules relative to the project root directory.
+   *
+   * @example
+   * ```ts
+   * const module = await context.load("some-module", "/path/to/importer");
+   * ```
+   *
+   * @param id - The module to load.
+   * @returns A promise that resolves to the loaded module.
+   */
+  load: (id: string) => Promise<TransformResult$1 | undefined>;
+  /**
+   * The Powerlines builtin virtual files
+   */
+  getBuiltins: () => Promise<VirtualFile[]>;
+  /**
+   * Resolves a builtin virtual file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the builtin file
+   * @param id - The unique identifier of the builtin file
+   * @param path - An optional path to write the builtin file to
+   */
+  emitBuiltin: (code: string, id: string, path?: string) => Promise<void>;
+  /**
+   * Resolves a entry virtual file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the entry file
+   * @param path - An optional path to write the entry file to
+   */
+  emitEntry: (code: string, path: string) => Promise<void>;
+  /**
+   * A function to update the context fields using a new user configuration options
+   */
+  withUserConfig: (userConfig: UserConfig, options?: InitContextOptions) => Promise<void>;
+  /**
+   * A function to update the context fields using inline configuration options
+   */
+  withInlineConfig: (inlineConfig: InlineConfig, options?: InitContextOptions) => Promise<void>;
+  /**
+   * Create a new logger instance
+   *
+   * @param name - The name to use for the logger instance
+   * @returns A logger function
+   */
+  createLog: (name: string | null) => LogFn;
+  /**
+   * Extend the current logger instance with a new name
+   *
+   * @param name - The name to use for the extended logger instance
+   * @returns A logger function
+   */
+  extendLog: (name: string) => LogFn;
+  /**
+   * Generates a checksum representing the current context state
+   *
+   * @returns A promise that resolves to a string representing the checksum
+   */
+  generateChecksum: () => Promise<string>;
+}
+type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<UnresolvedContext<TResolvedConfig>, "config"> & {
+  /**
+   * The fully resolved Powerlines configuration
+   */
+  config: TResolvedConfig;
+};
+interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
+  /**
+   * The environment specific resolved configuration
+   */
+  environment: EnvironmentResolvedConfig;
+  /**
+   * An alternative property name for the {@link log} property
+   *
+   * @remarks
+   * This is provided for compatibility with other logging libraries that expect a `logger` property.
+   */
+  logger: LogFn;
+}
+type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
+//#endregion
+export { BuildPluginContext, PluginContext, UnresolvedContext };