@powerlines/plugin-openapi 0.2.235 → 0.2.237

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

@@ -0,0 +1,514 @@
+import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.mjs";
+import { ParsedTypeScriptConfig } from "./tsconfig.mjs";
+import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.mjs";
+import { HooksList, InferHooksListItem } from "./hooks.mjs";
+import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.mjs";
+import { Plugin } from "./plugin.mjs";
+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 { 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 SelectHooksOptions {
+  order?: "pre" | "post" | "normal";
+}
+/**
+ * Options for initializing or updating the context with new configuration values
+ */
+interface InitContextOptions {
+  /**
+   * If false, the plugin will be loaded after all other plugins.
+   *
+   * @defaultValue true
+   */
+  isHighPriority: boolean;
+}
+/**
+ * Options for fetch requests made via the context's {@link Context.fetch} method
+ */
+interface FetchOptions extends FetchRequestOptions {
+  /**
+   * An indicator specifying that the request should bypass any caching
+   */
+  skipCache?: boolean;
+}
+/**
+ * Options for parsing code using [Oxc-Parser](https://github.com/oxc/oxc)
+ */
+interface ParseOptions extends ParserOptions {
+  /**
+   * When true this allows return statements to be outside functions to e.g. support parsing CommonJS code.
+   */
+  allowReturnOutsideFunction?: boolean;
+}
+interface EmitOptions extends WriteOptions {
+  /**
+   * The file extension to use when emitting the file
+   */
+  extension?: string;
+  /**
+   * If true, will emit the file using {@link UnpluginBuildContext.emitFile | the bundler's emit function}.
+   */
+  emitWithBundler?: boolean;
+  needsCodeReference?: Parameters<UnpluginBuildContext["emitFile"]>[0]["needsCodeReference"];
+  originalFileName?: Parameters<UnpluginBuildContext["emitFile"]>[0]["originalFileName"];
+}
+/**
+ * Options for emitting entry virtual files
+ */
+type EmitEntryOptions = EmitOptions & Omit<ResolvedEntryTypeDefinition, "file">;
+/**
+ * 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 alias mappings for the project used during module resolution
+   *
+   * @remarks
+   * This includes both the built-in module aliases as well as any custom aliases defined in the build configuration.
+   */
+  alias: Record<string, string>;
+  /**
+   * 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 file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the file
+   * @param path - The path to write the file to
+   * @param options - Additional options for writing the file
+   */
+  emit: (code: string, path: string, options?: EmitOptions) => Promise<void>;
+  /**
+   * Synchronously resolves a file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the file
+   * @param path - The path to write the file to
+   * @param options - Additional options for writing the file
+   */
+  emitSync: (code: string, path: string, options?: EmitOptions) => void;
+  /**
+   * 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 options - Additional options for writing the builtin file
+   */
+  emitBuiltin: (code: string, id: string, options?: EmitOptions) => Promise<void>;
+  /**
+   * Synchronously 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 options - Additional options for writing the builtin file
+   */
+  emitBuiltinSync: (code: string, id: string, options?: EmitOptions) => 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
+   * @param options - Additional options for writing the entry file
+   */
+  emitEntry: (code: string, path: string, options?: EmitEntryOptions) => Promise<void>;
+  /**
+   * Synchronously 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
+   * @param options - Additional options for writing the entry file
+   */
+  emitEntrySync: (code: string, path: string, options?: EmitEntryOptions) => 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 APIContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+  /**
+   * The expected plugins options for the Powerlines project.
+   *
+   * @remarks
+   * This is a record of plugin identifiers to their respective options. This field is populated by the Powerlines engine during both plugin initialization and the `init` command.
+   */
+  plugins: Plugin<PluginContext<TResolvedConfig>>[];
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
+  /**
+   * A table for storing the current context for each configured environment
+   */
+  environments: Record<string, EnvironmentContext<TResolvedConfig>>;
+  /**
+   * Retrieves the context for a specific environment by name
+   *
+   * @throws Will throw an error if the environment does not exist
+   *
+   * @param name - The name of the environment to retrieve. If not provided, the default environment is returned.
+   * @returns A promise that resolves to the environment context.
+   *
+   * @example
+   * ```ts
+   * const devEnv = await apiContext.getEnvironment("development");
+   * const defaultEnv = await apiContext.getEnvironment();
+   * ```
+   */
+  getEnvironment: (name?: string) => Promise<EnvironmentContext<TResolvedConfig>>;
+  /**
+   * Safely retrieves the context for a specific environment by name
+   *
+   * @param name - The name of the environment to retrieve. If not provided, the default environment is returned.
+   * @returns A promise that resolves to the environment context, or undefined if the environment does not exist.
+   *
+   * @example
+   * ```ts
+   * const devEnv = await apiContext.getEnvironmentSafe("development");
+   * const defaultEnv = await apiContext.getEnvironmentSafe();
+   * ```
+   *
+   * @remarks
+   * This method is similar to `getEnvironment`, but it returns `undefined` instead of throwing an error if the specified environment does not exist.
+   * This can be useful in scenarios where the existence of an environment is optional or uncertain.
+   *
+   * ```ts
+   * const testEnv = await apiContext.getEnvironmentSafe("test");
+   * if (testEnv) {
+   *   // Environment exists, safe to use it
+   * } else {
+   *   // Environment does not exist, handle accordingly
+   * }
+   * ```
+   *
+   * Using this method helps avoid unhandled exceptions in cases where an environment might not be defined.
+   */
+  getEnvironmentSafe: (name?: string) => Promise<EnvironmentContext<TResolvedConfig> | undefined>;
+  /**
+   * A function to copy the context and update the fields for a specific environment
+   *
+   * @param environment - The environment configuration to use.
+   * @returns A new context instance with the updated environment.
+   */
+  in: (environment: EnvironmentResolvedConfig) => Promise<EnvironmentContext<TResolvedConfig>>;
+  /**
+   * A function to merge all configured environments into a single context
+   *
+   * @returns A promise that resolves to the merged environment context.
+   */
+  toEnvironment: () => Promise<EnvironmentContext<TResolvedConfig>>;
+}
+interface EnvironmentContextPlugin<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+  plugin: Plugin<PluginContext<TResolvedConfig>>;
+  context: PluginContext<TResolvedConfig>;
+}
+type SelectHookResultItem<TContext extends PluginContext, TKey extends string> = InferHooksListItem<TContext, TKey> & {
+  context: TContext;
+};
+type SelectHookResult<TContext extends PluginContext, TKey extends string> = SelectHookResultItem<TContext, TKey>[];
+interface EnvironmentContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig> {
+  /**
+   * The expected plugins options for the Powerlines project.
+   *
+   * @remarks
+   * This is a record of plugin identifiers to their respective options. This field is populated by the Powerlines engine during both plugin initialization and the `init` command.
+   */
+  plugins: EnvironmentContextPlugin<TResolvedConfig>[];
+  /**
+   * A function to add a plugin to the context and update the configuration options
+   */
+  addPlugin: (plugin: Plugin<PluginContext<TResolvedConfig>>) => Promise<void>;
+  /**
+   * The environment specific resolved configuration
+   */
+  environment: EnvironmentResolvedConfig;
+  /**
+   * A table holding references to hook functions registered by plugins
+   */
+  hooks: HooksList<PluginContext<TResolvedConfig>>;
+  /**
+   * Retrieves the hook handlers for a specific hook name
+   */
+  selectHooks: <TKey extends string>(key: TKey, options?: SelectHooksOptions) => SelectHookResult<PluginContext<TResolvedConfig>, TKey>;
+}
+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>;
+type WithUnpluginBuildContext<TContext extends PluginContext> = UnpluginBuildContext & TContext;
+//#endregion
+export { APIContext, BuildPluginContext, Context, EnvironmentContext, PluginContext, SelectHooksOptions, UnresolvedContext, WithUnpluginBuildContext };