@remotex-labs/xbuild 2.1.6 → 2.2.0

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * DO NOT EDIT MANUALLY.
  */
 
-import ts, { CompilerOptions, DiagnosticCategory, IScriptSnapshot, LanguageService, ParsedCommandLine, ResolvedModuleWithFailedLookupLocations } from 'typescript';
+import ts, { CompilerOptions, DiagnosticCategory, IScriptSnapshot, LanguageService, ParsedCommandLine, ResolvedModuleWithFailedLookupLocations, SourceFile } from 'typescript';
 import { BuildOptions, BuildResult, Loader, Message, OnEndResult, OnLoadArgs, OnLoadResult, OnResolveArgs, OnResolveResult, OnStartResult, PartialMessage, Platform, PluginBuild } from 'esbuild';
 import { IncomingMessage, ServerResponse } from 'http';
 import { PositionInterface, SourceService } from '@remotex-labs/xmap';
@@ -2197,6 +2197,17 @@ interface LifecycleContextInterface {
      * @since 2.0.0
      */
     variantName: string;
+    /**
+     * esbuild configuration options used for this lifecycle execution.
+     *
+     * @remarks
+     * These options represent the active build configuration for the provider and
+     * are intended to be read by lifecycle handlers when build behavior depends on
+     * entry points, output settings, plugins, or other esbuild flags.
+     *
+     * @since 2.2.0
+     */
+    options: BuildOptions;
 }
 /**
  * Context interface for `onStart` hooks, providing access to the esbuild plugin build object.
@@ -2733,6 +2744,7 @@ type OnLoadType = (context: LoadContextInterface) => MaybeUndefinedPromiseType<O
  *
  * The normalized errors may include:
  * - {@link TypesError} for TypeScript type checking failures
+ * - {@link xBuildError} for text errors during build hooks
  * - {@link esBuildError} for esbuild compilation errors with location information
  * - {@link VMRuntimeError} for runtime errors during build hooks
  * - {@link xBuildBaseError} for custom build system errors
@@ -2745,7 +2757,7 @@ type OnLoadType = (context: LoadContextInterface) => MaybeUndefinedPromiseType<O
  *     new TypesError('Type checking failed', diagnostics)
  *   ],
  *   warnings: [
- *     new VMRuntimeError(new Error('Deprecation warning'))
+ *     new xBuildError('Deprecation warning')
  *   ],
  *   metafile: { ... },
  *   outputFiles: [ ... ],
@@ -4473,10 +4485,14 @@ declare function parseGlobs(globs: Array<string>): ParseGlobInterface;
  *
  * @remarks
  * Uses early exit optimization - stops checking as soon as a match is found.
+ * A pattern is treated as a match when either:
+ * - The pattern string ends with the provided path
+ * - `matchesGlob(p, pattern)` returns true
  *
  * @example
  * ```ts
  * matchesAny('src/app.ts', ['**\/*.ts', '**\/*.js']); // true
+ * matchesAny('src/app.ts', ['prefix/src/app.ts']); // true (suffix check)
  * matchesAny('README.md', ['**\/*.ts', '**\/*.js']); // false
  * ```
  *
@@ -4596,6 +4612,696 @@ interface ParseGlobInterface {
      */
     exclude: Array<string>;
 }
+/**
+ * Type alias for build-time definition values used in conditional compilation.
+ *
+ * @remarks
+ * This type represents the structure of the `define` configuration object that controls
+ * conditional macro behavior. Each key is a definition name referenced by `$$ifdef` or
+ * `$$ifndef` macros, and the value determines whether the macro is included or excluded.
+ *
+ * **Value interpretation**:
+ * - Truthy values (`true`, non-zero numbers, non-empty strings): Definition is considered "defined"
+ * - Falsy values (`false`, `0`, `''`, `null`, `undefined`): Definition is considered "not defined"
+ *
+ * The values can be any type, but are typically booleans for clarity. JavaScript's truthiness
+ * rules are applied when evaluating macro conditions.
+ *
+ * @example Basic boolean definitions
+ * ```ts
+ * const defines: DefinesType = {
+ *   DEBUG: true,
+ *   PRODUCTION: false,
+ *   TEST: false
+ * };
+ * ```
+ *
+ * @example Mixed value types
+ * ```ts
+ * const defines: DefinesType = {
+ *   DEBUG: true,
+ *   LOG_LEVEL: 'info',        // Truthy (non-empty string)
+ *   MAX_RETRIES: 3,            // Truthy (non-zero number)
+ *   EXPERIMENTAL: 0,           // Falsy
+ *   FEATURE_FLAG: undefined    // Falsy
+ * };
+ * ```
+ *
+ * @example Usage in configuration
+ * ```ts
+ * const config = {
+ *   define: {
+ *     DEBUG: process.env.NODE_ENV !== 'production',
+ *     API_URL: process.env.API_URL || 'http://localhost:3000'
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link StateInterface.defines} for usage context
+ * @see {@link isDefinitionMet} for condition evaluation logic
+ *
+ * @since 2.0.0
+ */
+type DefinesType = Record<string, unknown>;
+/**
+ * Build execution context available to macro transformation logic.
+ *
+ * @remarks
+ * Groups runtime build metadata and configuration needed by macros during AST processing:
+ * - `variantName`: active build variant identifier
+ * - `argv`: provider command-line/config arguments
+ * - `options`: effective esbuild `BuildOptions` for the current build
+ *
+ * This object is read by macro handlers to make variant-aware and build-aware decisions.
+ *
+ * @since 2.2.0
+ */
+interface MacroContextInterface {
+    /**
+     * The current build variant name.
+     *
+     * @remarks
+     * Identifies which variant is being transformed (for example, `development`
+     * or `production`). This value is propagated through macro processing so
+     * diagnostics and generated output can be associated with the correct variant.
+     *
+     * @example
+     * ```ts
+     * $$inline(() => {
+     *     console.log(variantName);
+     * });
+     * ```
+     *
+     * @since 2.2.0
+     */
+    variantName: string;
+    /**
+     * Command-line arguments and configuration options passed to the provider.
+     *
+     * @remarks
+     * Contains all CLI options and flags passed when the provider was created.
+     * Available to all handlers for accessing build-specific configuration like
+     * debug flags, output paths, or custom settings.
+     *
+     * @example
+     * ```ts
+     * context.argv; // { debug: true, verbose: false, outdir: 'dist' }
+     * ```
+     *
+     * @since 2.2.0
+     */
+    argv: Record<string, unknown>;
+    /**
+     * esbuild configuration options used for this lifecycle execution.
+     *
+     * @remarks
+     * These options represent the active build configuration for the provider and
+     * are intended to be read by lifecycle handlers when build behavior depends on
+     * entry points, output settings, plugins, or other esbuild flags.
+     *
+     * @since 2.2.0
+     */
+    options: BuildOptions;
+}
+/**
+ * Represents the complete state during macro transformation of a source file.
+ *
+ * @remarks
+ * This interface encapsulates all data needed during AST traversal and macro transformation.
+ * It provides:
+ * - **Metadata access**: Build stage information including disabled macro names
+ * - **Configuration**: Build-time definitions controlling conditional compilation
+ * - **Source information**: TypeScript AST and original file content
+ * - **Diagnostic collection**: Arrays for warnings and errors during transformation
+ *
+ * The state is passed through the entire transformation pipeline, allowing functions
+ * to access configuration, collect diagnostics, and track the transformation process.
+ *
+ * **State lifecycle**:
+ * 1. Created in {@link transformerDirective} with initial configuration
+ * 2. Passed to {@link astProcess} for transformation
+ * 3. Passed to individual node processors ({@link isVariableStatement}, {@link isCallExpression})
+ * 4. Passed to macro transformers ({@link astInlineVariable}, {@link astDefineVariable})
+ * 5. Diagnostics extracted and returned in the final result
+ *
+ * @example State initialization
+ * ```ts
+ * const state: StateInterface = {
+ *   stage: stage as MacrosStaeInterface,
+ *   defines: { DEBUG: true, PRODUCTION: false },
+ *   sourceFile: languageService.getProgram()?.getSourceFile(path)!,
+ *   contents: fileContents,
+ *   errors: [],
+ *   warnings: []
+ * };
+ * ```
+ *
+ * @example Collecting diagnostics during transformation
+ * ```ts
+ * function processNode(node: Node, state: StateInterface): void {
+ *   if (isInvalidMacro(node)) {
+ *     state.warnings.push({
+ *       text: 'Invalid macro usage',
+ *       location: getLocation(node, state.sourceFile)
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Accessing definitions
+ * ```ts
+ * function shouldIncludeMacro(name: string, state: StateInterface): boolean {
+ *   const value = state.defines[name];
+ *   return name in state.defines && !!value;
+ * }
+ * ```
+ *
+ * @see {@link transformerDirective} for state creation
+ * @see {@link astProcess} for state usage during transformation
+ * @see {@link MacrosStateInterface} for stage metadata structure
+ *
+ * @since 2.0.0
+ */
+interface StateInterface {
+    /**
+     * The build stage containing macro analysis metadata.
+     *
+     * @remarks
+     * Provides access to metadata collected during the analysis phase, including:
+     * - Set of files containing macros
+     * - Set of disabled macro names (based on definitions)
+     *
+     * This metadata is used to optimize transformation by skipping files without
+     * macros and replacing disabled macro references with `undefined`.
+     *
+     * @see {@link MacrosStateInterface} for metadata structure
+     * @see {@link analyzeMacroMetadata} for metadata generation
+     *
+     * @since 2.0.0
+     */
+    stage: MacrosStateInterface;
+    /**
+     * Array of error messages collected during transformation.
+     *
+     * @remarks
+     * Contains partial esbuild messages representing errors that occurred during
+     * macro processing. Common error sources include:
+     * - Invalid macro syntax
+     * - Runtime errors during inline code evaluation
+     * - TypeScript compilation errors
+     *
+     * Errors are non-fatal during transformation but are reported in the final result
+     * and may cause the build to fail.
+     *
+     * @example Adding an error
+     * ```ts
+     * state.errors.push({
+     *   text: 'Cannot evaluate inline macro',
+     *   location: { file: filePath, line: 42, column: 10 }
+     * });
+     * ```
+     *
+     * @since 2.0.0
+     */
+    errors: Array<PartialMessage>;
+    /**
+     * Build-time definitions controlling conditional macro inclusion.
+     *
+     * @remarks
+     * A record mapping definition names to their values. Used by `$$ifdef` and `$$ifndef`
+     * macros to determine whether code should be included in the build output.
+     *
+     * Typically sourced from `variant.config.define` in the build configuration.
+     *
+     * @example
+     * ```ts
+     * const state: StateInterface = {
+     *   defines: {
+     *     DEBUG: true,
+     *     PRODUCTION: false,
+     *     API_URL: 'https://api.example.com'
+     *   },
+     *   // ... other properties
+     * };
+     * ```
+     *
+     * @see {@link DefinesType} for type structure
+     * @see {@link isDefinitionMet} for evaluation logic
+     *
+     * @since 2.0.0
+     */
+    defines: DefinesType;
+    /**
+     * Array of warning messages collected during transformation.
+     *
+     * @remarks
+     * Contains partial esbuild messages representing non-fatal issues discovered
+     * during macro processing. Common warning sources include:
+     * - Macro names missing the `$$` prefix convention
+     * - References to undefined functions in inline macros
+     * - Deprecated macro patterns
+     *
+     * Warnings do not prevent successful transformation but indicate potential issues.
+     *
+     * @example Adding a warning
+     * ```ts
+     * state.warnings.push({
+     *   text: `Function ${functionName} not found`,
+     *   location: { file: filePath, line: 10, column: 5 }
+     * });
+     * ```
+     *
+     * @since 2.0.0
+     */
+    warnings: Array<PartialMessage>;
+    /**
+     * The current file content being transformed.
+     *
+     * @remarks
+     * Contains the complete source file text. During transformation, this content
+     * is modified by applying replacement operations. The final transformed content
+     * is returned in the build result.
+     *
+     * Updated during the transformation process as macros are replaced with their
+     * expanded or evaluated forms.
+     *
+     * @since 2.0.0
+     */
+    contents: string;
+    /**
+     * The TypeScript source file AST.
+     *
+     * @remarks
+     * Provides the parsed Abstract Syntax Tree of the source file, used for:
+     * - AST traversal to locate macro calls
+     * - Text extraction from AST nodes
+     * - Position calculation for diagnostics
+     * - Source location mapping
+     *
+     * Obtained from TypeScript's language service and represents the current
+     * state of the file in the compilation.
+     *
+     * @since 2.0.0
+     */
+    sourceFile: SourceFile;
+    /**
+     * Build execution context available to macro transformation logic.
+     *
+     * @remarks
+     * Groups runtime build metadata and configuration needed by macros during AST processing:
+     * - `variantName`: active build variant identifier
+     * - `argv`: provider command-line/config arguments
+     * - `options`: effective esbuild `BuildOptions` for the current build
+     *
+     * This object is read by macro handlers to make variant-aware and build-aware decisions.
+     *
+     * @since 2.2.0
+     */
+    context: MacroContextInterface;
+}
+/**
+ * Represents a text substitution operation for macro replacement.
+ *
+ * @remarks
+ * This interface defines a single replacement operation to be performed on source code
+ * during macro transformation. Each substitution specifies:
+ * - The region of text to replace (via start and end positions)
+ * - The replacement text to insert
+ *
+ * Substitutions are collected during AST traversal and applied in reverse order
+ * (from end to start) to avoid position invalidation as earlier replacements
+ * are applied.
+ *
+ * **Position handling**:
+ * - Positions are character offsets from the start of the file (0-based)
+ * - `start` is inclusive (first character to replace)
+ * - `end` is exclusive (one past the last character to replace)
+ * - Region length: `end - start`
+ *
+ * **Application strategy**:
+ * Replacements are sorted by `start` position in descending order before application,
+ * ensuring that later positions are replaced first, preventing earlier replacements
+ * from shifting positions of subsequent replacements.
+ *
+ * @example Basic substitution
+ * ```ts
+ * const subst: SubstInterface = {
+ *   start: 50,  // Start of the macro call
+ *   end: 85,    // End of macro call
+ *   replacement: 'function $$debug() { return console.log; }'
+ * };
+ * ```
+ *
+ * @example Replacing a macro with undefined
+ * ```ts
+ * // Replace disabled macro reference
+ * const subst: SubstInterface = {
+ *   start: 120,
+ *   end: 127,  // Length of '$$debug'
+ *   replacement: 'undefined'
+ * };
+ * ```
+ *
+ * @example Multiple substitutions
+ * ```ts
+ * const replacements: SubstInterface[] = [
+ *   { start: 100, end: 150, replacement: 'transformed1' },
+ *   { start: 50, end: 80, replacement: 'transformed2' }
+ * ];
+ *
+ * // Sort by start position (descending)
+ * replacements.sort((a, b) => b.start - a.start);
+ *
+ * // Apply in reverse order
+ * for (const subst of replacements) {
+ *   content = content.slice(0, subst.start) +
+ *             subst.replacement +
+ *             content.slice(subst.end);
+ * }
+ * ```
+ *
+ * @see {@link isVariableStatement} for substitution creation
+ * @see {@link astProcess} for substitution collection and application
+ *
+ * @since 2.0.0
+ */
+interface SubstInterface {
+    /**
+     * The exclusive end position of the text region to replace.
+     *
+     * @remarks
+     * Character offset representing one position past the last character to replace.
+     * The character at this position is not included in the replacement.
+     *
+     * Obtained from `node.getEnd()` on the AST node being replaced.
+     *
+     * @since 2.0.0
+     */
+    end: number;
+    /**
+     * The inclusive start position of the text region to replace.
+     *
+     * @remarks
+     * Character offset representing the first character to replace in the source text.
+     * The character at this position is included in the replacement.
+     *
+     * Obtained from `node.getStart(sourceFile)` on the AST node being replaced.
+     *
+     * @since 2.0.0
+     */
+    start: number;
+    /**
+     * The replacement text to insert at the specified position.
+     *
+     * @remarks
+     * The complete text that will replace the region defined by `start` and `end`.
+     * Can be:
+     * - Transformed macro code (function declarations, constants)
+     * - Evaluated inline results
+     * - The string `'undefined'` for disabled macros
+     * - Empty string for removed macros
+     *
+     * @example
+     * ```ts
+     * replacement: 'function $$debug() { return console.log; }'
+     * replacement: 'undefined'
+     * replacement: 'export const API_URL = "https://api.example.com";'
+     * replacement: ''
+     * ```
+     *
+     * @since 2.0.0
+     */
+    replacement: string;
+}
+/**
+ * Metadata collected during macro analysis for a build variant.
+ *
+ * @remarks
+ * This interface stores essential information about macro usage across the project,
+ * used during the transformation phase to:
+ * - Determine which files need macro processing
+ * - Identify which macro functions should be removed
+ * - Optimize build performance by skipping files without macros
+ *
+ * Both sets use absolute file paths for accurate file identification.
+ *
+ * @example Metadata after analyzing a project
+ * ```ts
+ * const metadata: MacrosMetadataInterface = {
+ *   filesWithMacros: new Set([
+ *     '/project/src/index.ts',
+ *     '/project/src/config.ts',
+ *     '/project/src/features/analytics.ts'
+ *   ]),
+ *   disabledMacroNames: new Set([
+ *     '$$noProd',      // from $$ifndef('PRODUCTION') when PRODUCTION=true
+ *     '$$devOnly',     // from $$ifdef('DEVELOPMENT') when DEVELOPMENT=false
+ *     '$$testMode'     // from $$ifdef('TEST') when TEST=false
+ *   ])
+ * };
+ * ```
+ *
+ * @example Using metadata for optimization
+ * ```ts
+ * function shouldProcessFile(filePath: string, metadata: MacrosMetadataInterface): boolean {
+ *   // Skip files that don't contain any macros
+ *   return metadata.filesWithMacros.has(filePath);
+ * }
+ *
+ * function shouldRemoveMacro(macroName: string, metadata: MacrosMetadataInterface): boolean {
+ *   // Check if macro should be stripped from output
+ *   return metadata.disabledMacroNames.has(macroName);
+ * }
+ * ```
+ *
+ * @example Building metadata incrementally
+ * ```ts
+ * const metadata: MacrosMetadataInterface = {
+ *   filesWithMacros: new Set(),
+ *   disabledMacroNames: new Set()
+ * };
+ *
+ * // During analysis
+ * if (fileContainsMacros(file)) {
+ *   metadata.filesWithMacros.add(file);
+ * }
+ *
+ * // When a macro is disabled by definitions
+ * if (shouldDisableMacro(macro, defines)) {
+ *   metadata.disabledMacroNames.add(macro);
+ * }
+ * ```
+ *
+ * @see {@link analyzeMacroMetadata} for the function that generates this metadata
+ * @see {@link MacrosStateInterface} for the stage interface that contains this metadata
+ *
+ * @since 2.0.0
+ */
+interface MacrosMetadataInterface {
+    /**
+     * Set of absolute file paths that contain macro expressions.
+     *
+     * @remarks
+     * Files in this set require macro transformation during the build process.
+     * Files not in this set can skip macro processing entirely, improving build performance.
+     *
+     * Includes files with any of:
+     * - `$$ifdef` expressions
+     * - `$$ifndef` expressions
+     * - Macro variable declarations
+     * - Inline macro calls
+     *
+     * @example
+     * ```ts
+     * filesWithMacros: new Set([
+     *   '/project/src/config.ts', // Has: const $$debug = $$ifdef('DEBUG', ...)
+     *   '/project/src/features.ts', // Has: $$ifdef('ANALYTICS', ...)
+     *   '/project/src/utils/logger.ts' // Has: export const $$log = $$ifndef('PROD', ...)
+     * ])
+     * ```
+     *
+     * @since 2.0.0
+     */
+    filesWithMacros: Set<string>;
+    /**
+     * Set of macro function names that should be removed from the output.
+     *
+     * @remarks
+     * Contains macro names that evaluated to false based on the current build definitions.
+     * These macros and their calls will be replaced with `undefined` during transformation.
+     *
+     * A macro is disabled when:
+     * - `$$ifdef('X', ...)` and X is false or undefined
+     * - `$$ifndef('X', ...)` and X is true
+     *
+     * @example
+     * ```ts
+     * // With definitions: { DEBUG: false, PRODUCTION: true, TEST: false }
+     * disabledMacroNames: new Set([
+     *   '$$hasDebug', // from $$ifdef('DEBUG', ...) - DEBUG is false
+     *   '$$noProd', // from $$ifndef('PRODUCTION', ...) - PRODUCTION is true
+     *   '$$testMode' // from $$ifdef('TEST', ...) - TEST is false
+     * ])
+     * ```
+     *
+     * @since 2.0.0
+     */
+    disabledMacroNames: Set<string>;
+}
+/**
+ * Describes a single text replacement produced by macro analysis/transformation.
+ *
+ * @remarks
+ * This is a small helper contract used to capture:
+ * - the original source fragment ({@link MacroReplacementInterface.source}), and
+ * - the text that should replace it ({@link MacroReplacementInterface.replacement}).
+ *
+ * It is useful for debugging, reporting, and applying deterministic transformations.
+ *
+ * @example Recording a replacement
+ * ```ts
+ * const r: MacroReplacementInterface = {
+ *   source: "$$ifdef('DEBUG', () => log())",
+ *   replacement: "undefined"
+ * };
+ * ```
+ *
+ * @since 2.0.0
+ */
+interface MacroReplacementInterface {
+    /**
+     * Original source text that should be replaced.
+     *
+     * @remarks
+     * Typically, this is an exact substring extracted from a file (e.g., a macro call,
+     * a macro variable initializer, or any other segment discovered during analysis).
+     *
+     * Consumers can use this to:
+     * - build diagnostics ("what was replaced?")
+     * - provide debug output / reports
+     * - verify transformations are deterministic
+     *
+     * @since 2.0.0
+     */
+    source: string;
+    /**
+     * Replacement text that should be substituted in place of {@link source}.
+     *
+     * @remarks
+     * This is the final text representation that should appear in the transformed output.
+     * For disabled macros this is often `'undefined'`, but it may also be an inlined constant,
+     * rewritten function body, or other generated code.
+     *
+     * @since 2.0.0
+     */
+    replacement: string;
+}
+/**
+ * Extended lifecycle stage interface with macro-specific metadata.
+ *
+ * @remarks
+ * This interface extends the base {@link LifecycleStageInterface} to include
+ * macro analysis metadata, making it available throughout the build lifecycle.
+ *
+ * The metadata is:
+ * - Populated during the analysis phase by {@link analyzeMacroMetadata}
+ * - Consumed during the transformation phase by {@link transformerDirective}
+ * - Accessible to all lifecycle hooks that need macro information
+ *
+ * @example Using in build lifecycle
+ * ```ts
+ * async function onBuild(context: { stage: MacrosStateInterface }) {
+ *   const { defineMetadata } = context.stage;
+ *
+ *   console.log(`Files with macros: ${defineMetadata.filesWithMacros.size}`);
+ *   console.log(`Disabled macros: ${defineMetadata.disabledMacroNames.size}`);
+ * }
+ * ```
+ *
+ * @example Checking macro status in plugin
+ * ```ts
+ * function myPlugin(stage: MacrosStateInterface) {
+ *   return {
+ *     name: 'my-plugin',
+ *     setup(build) {
+ *       build.onLoad({ filter: /\.ts$/ }, (args) => {
+ *         if (!stage.defineMetadata.filesWithMacros.has(args.path)) {
+ *           // Skip macro processing for this file
+ *           return null;
+ *         }
+ *
+ *         // Process macros...
+ *       });
+ *     }
+ *   };
+ * }
+ * ```
+ *
+ * @example Accessing in transformer
+ * ```ts
+ * function transform(code: string, stage: MacrosStateInterface): string {
+ *   const { disabledMacroNames } = stage.defineMetadata;
+ *
+ *   // Remove disabled macros
+ *   for (const macroName of disabledMacroNames) {
+ *     code = code.replace(new RegExp(macroName, 'g'), 'undefined');
+ *   }
+ *
+ *   return code;
+ * }
+ * ```
+ *
+ * @see {@link analyzeMacroMetadata} for metadata generation
+ * @see {@link MacrosMetadataInterface} for metadata structure
+ * @see {@link LifecycleStageInterface} for base stage properties
+ *
+ * @since 2.0.0
+ */
+interface MacrosStateInterface extends LifecycleStageInterface {
+    /**
+     * Macro analysis metadata for the current build.
+     *
+     * @remarks
+     * Contains information about:
+     * - Which files contain macros and need processing
+     * - Which macro names should be removed based on definitions
+     *
+     * This metadata is shared across all build plugins and transformers
+     * to ensure consistent macro handling throughout the build process.
+     *
+     * @since 2.0.0
+     */
+    defineMetadata: MacrosMetadataInterface;
+    /**
+     * Optional map of macro-driven source replacements recorded during transformation.
+     *
+     * @remarks
+     * When present, this can be used for:
+     * - debugging ("what exactly changed?"),
+     * - producing transformation reports, or
+     * - testing/verifying deterministic output.
+     *
+     * The keys are the name of the variant, and each value is an array of replacements made.
+     * Each entry describes the original fragment and its replacement via
+     * {@link MacroReplacementInterface}.
+     *
+     * @example
+     * ```ts
+     * stage.replacementInfo = {
+     *   'index': [
+     *     { source: "$$inline(() => 1 + 1)", replacement: "2" },
+     *     { source: "$$debug()", replacement: "undefined" }
+     *   ],
+     *   'config': [
+     *     { source: "$$ifdef('PROD', ...)", replacement: "undefined" }
+     *   ]
+     * };
+     * ```
+     *
+     * @since 2.0.0
+     */
+    replacementInfo?: Record<string, Array<MacroReplacementInterface>>;
+}
 /**
  * User-defined command-line options that extend the base xBuild CLI.
  *
@@ -5959,6 +6665,7 @@ export {
 	LifecycleContextInterface,
 	LifecycleStageInterface,
 	LoadContextInterface,
+	MacroContextInterface,
 	MaybeUndefinedPromiseType,
 	MaybeVoidPromiseType,
 	OnEndType,