@remotex-labs/xbuild 2.1.0 → 2.1.2

package/dist/bash.d.ts

@@ -26,14 +26,13 @@ import type { SourceService } from '@remotex-labs/xmap';
 import type { ParsedStackTraceInterface, StackFrameInterface } from '@remotex-labs/xmap/parser.component';
 import { type PositionWithCodeInterface } from '@remotex-labs/xmap';
 import { type SourceOptionsInterface } from '@remotex-labs/xmap/formatter.component';
-import type { Message } from 'esbuild';
 import type { Plugin } from 'esbuild';
 import type { BuildOptions, BuildResult, Metafile } from 'esbuild';
 import type { OnLoadResult } from 'esbuild';
 import type { VariableStatement, ExpressionStatement } from 'typescript';
 import type { SourceFile } from 'typescript';
 import type { VariableDeclaration, CallExpression } from 'typescript';
-import type { SourceFile, Node, NodeArray, Expression } from 'typescript';
+import type { SourceFile, Node } from 'typescript';
 import type { CallExpression, VariableDeclaration, Node } from 'typescript';
 import type { NodeArray, Expression, VariableStatement } from 'typescript';
 import type { Node, FunctionDeclaration, ArrowFunction, FunctionExpression } from 'typescript';
@@ -294,7 +293,7 @@ declare global {
      * @see {@link DefineType} for valid definition names
      * @since 2.0.0
      */
-    function $$ifdef<T>(define: DefineType, callback: T): T;
+    function $$ifdef<T>(define: DefineType, callback: T): T extends (...args: infer A) => infer R ? (...args: A) => R | undefined : T | undefined;
     /**
      * Conditional inclusion macro that includes code when a definition is falsy or undefined.
      *
@@ -355,7 +354,7 @@ declare global {
      * @see {@link DefineType} for valid definition names
      * @since 2.0.0
      */
-    function $$ifndef<T>(define: DefineType, callback: T): T;
+    function $$ifndef<T>(define: DefineType, callback: T): T extends (...args: infer A) => infer R ? (...args: A) => R | undefined : T | undefined;
     /**
      * Inline evaluation macro that executes code at build time and replaces it with the result.
      *
@@ -427,7 +426,7 @@ declare global {
      *
      * @since 2.0.0
      */
-    function $$inline(callback: unknown): string;
+    function $$inline<T>(callback: () => T): string | undefined;
     /**
      * Pre-configuration CLI arguments snapshot (bootstrap argv).
      *
@@ -9571,7 +9570,7 @@ declare class esBuildError extends xBuildBaseError {
      *
      * @since 2.0.0
      */
-    constructor(message: Message);
+    constructor(message: PartialMessage);
 }
 
 /**
@@ -12325,6 +12324,24 @@ declare function extractEntryPoints(baseDir: string, entryPoints: BuildOptions['
 /**
  * Import will remove at compile time
  */
+/**
+ * Imports
+ */
+/**
+ * Checks whether a given AST node’s source text contains any supported macro function name.
+ *
+ * @param node - AST node to inspect
+ * @param sourceFile - Optional source file used by TypeScript to compute node text
+ *
+ * @returns `true` if the node text contains at least one macro identifier; otherwise `false`.
+ *
+ * @remarks
+ * This is a fast, text-based pre-check used to avoid deeper macro parsing work when a node
+ * clearly cannot contain macro calls.
+ *
+ * @since 2.0.0
+ */
+declare function nodeContainsMacro(node: ts.Node, sourceFile?: ts.SourceFile): boolean;
 /**
  * Processes variable statements containing macro calls and adds replacements to the replacement set.
  *
@@ -12394,7 +12411,7 @@ declare function extractEntryPoints(baseDir: string, entryPoints: BuildOptions['
  *
  * @since 2.0.0
  */
-declare function isVariableStatement(node: VariableStatement, replacements: Set<SubstInterface>, state: StateInterface): Promise<void>;
+declare function isVariableStatement(node: VariableStatement, replacements: Set<SubstInterface>, state: StateInterface): Promise<boolean>;
 /**
  * Processes standalone macro call expressions and adds replacements to the replacement set.
  *
@@ -12449,7 +12466,7 @@ declare function isVariableStatement(node: VariableStatement, replacements: Set<
  *
  * @since 2.0.0
  */
-declare function isCallExpression(node: ExpressionStatement, replacements: Set<SubstInterface>, state: StateInterface): Promise<void>;
+declare function isCallExpression(node: ExpressionStatement, replacements: Set<SubstInterface>, state: StateInterface): Promise<boolean>;
 /**
  * Recursively traverses the AST to find and transform all macro occurrences in the source file.
  *
@@ -12660,7 +12677,7 @@ declare function transformerDirective(variant: VariantService, context: LoadCont
  * ```
  *
  * @see {@link analyzeMacroMetadata} for the function that generates this metadata
- * @see {@link MacrosStaeInterface} for the stage interface that contains this metadata
+ * @see {@link MacrosStateInterface} for the stage interface that contains this metadata
  *
  * @since 2.0.0
  */
@@ -12715,6 +12732,54 @@ interface MacrosMetadataInterface {
      */
     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.
  *
@@ -12776,7 +12841,7 @@ interface MacrosMetadataInterface {
  *
  * @since 2.0.0
  */
-interface MacrosStaeInterface extends LifecycleStageInterface {
+interface MacrosStateInterface extends LifecycleStageInterface {
     /**
      * Macro analysis metadata for the current build.
      *
@@ -12791,6 +12856,29 @@ interface MacrosStaeInterface extends LifecycleStageInterface {
      * @since 2.0.0
      */
     defineMetadata: MacrosMetadataInterface;
+    /**
+     * Optional list 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.
+     *
+     * Each entry describes the original fragment and its replacement via
+     * {@link MacroReplacementInterface}.
+     *
+     * @example
+     * ```ts
+     * stage.replacementInfo = [
+     *   { source: "$$inline(() => 1 + 1)", replacement: "2" },
+     *   { source: "$$debug()", replacement: "undefined" }
+     * ];
+     * ```
+     *
+     * @since 2.0.0
+     */
+    replacementInfo?: Array<MacroReplacementInterface>;
 }
 
 /**
@@ -12902,7 +12990,7 @@ type DefinesType = Record<string, unknown>;
  *
  * @see {@link transformerDirective} for state creation
  * @see {@link astProcess} for state usage during transformation
- * @see {@link MacrosStaeInterface} for stage metadata structure
+ * @see {@link MacrosStateInterface} for stage metadata structure
  *
  * @since 2.0.0
  */
@@ -12918,12 +13006,12 @@ interface StateInterface {
      * This metadata is used to optimize transformation by skipping files without
      * macros and replacing disabled macro references with `undefined`.
      *
-     * @see {@link MacrosStaeInterface} for metadata structure
+     * @see {@link MacrosStateInterface} for metadata structure
      * @see {@link analyzeMacroMetadata} for metadata generation
      *
      * @since 2.0.0
      */
-    stage: MacrosStaeInterface;
+    stage: MacrosStateInterface;
     /**
      * Array of error messages collected during transformation.
      *
@@ -13208,6 +13296,8 @@ declare function transformToFunction(fnName: string, node: Node, sourceFile: Sou
  *
  * @param node - The AST node to transform
  * @param sourceFile - The source file containing the node
+ * @param prefix - The prefix to prepend before the IIFE; defaults to `''`
+ * @param suffix - The suffix to append after the IIFE; defaults to `'();'`
  *
  * @returns A string containing the IIFE expression
  *
@@ -13218,10 +13308,15 @@ declare function transformToFunction(fnName: string, node: Node, sourceFile: Sou
  * **For function-like nodes** (arrow functions and function expressions):
  * - Wraps directly: `(function)()` or `(() => value)()`
  * - Preserves the function as-is
+ * - Note: `prefix` and `suffix` are not applied to function-like nodes
  *
  * **For other node types** (expressions, statements):
  * - Wraps in an arrow function IIFE with explicit return
  * - Ensures the value is returned for use in expressions
+ * - Applies `prefix` before and `suffix` after the IIFE
+ *
+ * The `prefix` and `suffix` parameters allow customization of the IIFE syntax, useful when
+ * the IIFE needs additional context, chaining, or specific wrapping.
  *
  * Used when conditional macros appear in expression contexts where a function
  * declaration is not valid syntax.
@@ -13247,11 +13342,18 @@ declare function transformToFunction(fnName: string, node: Node, sourceFile: Sou
  * // '(() => { return 1 + 1; })()'
  * ```
  *
+ * @example Custom prefix and suffix
+ * ```ts
+ * const node = parseExpression('getValue()');
+ * const result = transformToIIFE(node, sourceFile, 'await ', '.catch(handleError)');
+ * // 'await (() => { return getValue(); })().catch(handleError)'
+ * ```
+ *
  * @see {@link astDefineCallExpression} for the calling context
  *
  * @since 2.0.0
  */
-declare function transformToIIFE(node: Node, sourceFile: SourceFile): string;
+declare function transformToIIFE(node: Node, sourceFile: SourceFile, prefix?: string, suffix?: string): string;
 /**
  * Transforms a conditional macro variable declaration into a function or returns an empty string if excluded.
  *
@@ -13316,64 +13418,76 @@ declare function transformToIIFE(node: Node, sourceFile: SourceFile): string;
  */
 declare function astDefineVariable(decl: VariableDeclaration, init: CallExpression, hasExport: boolean, state: StateInterface): string | false;
 /**
- * Transforms a conditional macro call expression into an IIFE or returns empty string if excluded.
+ * Transforms a conditional macro call expression into a constant assignment with an IIFE or returns empty string if excluded.
  *
- * @param args - The arguments passed to the macro call
- * @param fnName - The macro function name (`'$$ifdef'` or `'$$ifndef'`)
+ * @param decl - The variable declaration node containing the macro
+ * @param init - The call expression node representing the macro call
+ * @param hasExport - Whether the variable declaration has an `export` modifier
  * @param state - The macro transformation state containing definitions and source file
+ * @param outerSuffix - Optional suffix to append after the IIFE invocation
  *
- * @returns The transformed IIFE string, empty string if excluded, or `false` if invalid
+ * @returns The transformed constant assignment string, empty string if excluded, or `false` if invalid
  *
  * @remarks
- * This function processes standalone conditional macro calls that appear in expression contexts:
+ * This function processes conditional macro call expressions that are assigned to constants:
  * ```ts
- * console.log($$ifdef('DEBUG', () => "debug mode"));
- * const value = $$ifndef('PRODUCTION', () => devValue);
+ * const $$value = $$ifdef('DEBUG', () => "debug mode");
+ * export const $$config = $$ifndef('PRODUCTION', () => devConfig);
  * ```
  *
- * Unlike {@link astDefineVariable}, this handles macros that are not part of variable
- * declarations but are used directly as expressions.
+ * Unlike {@link astDefineVariable}, which transforms macros into function declarations,
+ * this handles macros that should remain as constant assignments with IIFE values.
  *
  * The transformation process:
  * 1. Validates that the first argument is a string literal (the definition name)
- * 2. Checks if the definition condition is met using {@link isDefinitionMet}
- * 3. If included: transforms the callback into an IIFE using {@link transformToIIFE}
- * 4. If excluded: returns an empty string (macro evaluates to undefined)
- * 5. If invalid: returns `false` (non-string definition argument)
+ * 2. Extracts the macro function name (`$$ifdef` or `$$ifndef`)
+ * 3. Checks if the definition condition is met using {@link isDefinitionMet}
+ * 4. If included: transforms the callback into a constant assignment with IIFE using {@link transformToIIFE}
+ * 5. If excluded: returns an empty string (macro is stripped from output)
+ * 6. If invalid: returns `false` (non-string definition argument)
+ *
+ * The variable name from the declaration becomes the constant name in the output,
+ * and the `hasExport` parameter controls whether the constant is exported.
  *
  * @example Included expression (DEBUG=true)
  * ```ts
- * // Source: console.log($$ifdef('DEBUG', () => "debugging"));
+ * // Source: const $$debugMsg = $$ifdef('DEBUG', () => "debugging");
  * // With: { DEBUG: true }
- * const result = astDefineCallExpression(args, '$$ifdef', state);
- * // '(() => "debugging")()'
- * // Result: console.log((() => "debugging")());
+ * const result = astDefineCallExpression(decl, init, false, state);
+ * // 'const $$debugMsg = (() => { return "debugging"; })();'
  * ```
  *
  * @example Excluded expression (DEBUG=false)
  * ```ts
- * // Source: console.log($$ifdef('DEBUG', () => "debugging"));
+ * // Source: const $$debugMsg = $$ifdef('DEBUG', () => "debugging");
  * // With: { DEBUG: false }
- * const result = astDefineCallExpression(args, '$$ifdef', state);
+ * const result = astDefineCallExpression(decl, init, false, state);
  * // ''
- * // Result: console.log();
  * ```
  *
- * @example Using `$$ifndef`
+ * @example Exported constant
  * ```ts
- * // Source: const url = $$ifndef('PRODUCTION', () => 'http://localhost');
+ * // Source: export const $$apiUrl = $$ifndef('PRODUCTION', () => 'http://localhost');
  * // With: { PRODUCTION: false }
- * const result = astDefineCallExpression(args, '$$ifndef', state);
- * // '(() => "http://localhost")()'
+ * const result = astDefineCallExpression(decl, init, true, state);
+ * // 'export const $$apiUrl = (() => { return "http://localhost"; })();'
+ * ```
+ *
+ * @example With custom suffix
+ * ```ts
+ * // Source: const $$data = $$ifdef('FEATURE', () => fetchData());
+ * // With: { FEATURE: true }
+ * const result = astDefineCallExpression(decl, init, false, state, '.then(process)');
+ * // 'const $$data = (() => { return fetchData(); })().then(process)'
  * ```
  *
  * @see {@link isDefinitionMet} for condition evaluation
  * @see {@link transformToIIFE} for transformation logic
- * @see {@link astDefineVariable} for variable declaration handling
+ * @see {@link astDefineVariable} for function declaration handling
  *
  * @since 2.0.0
  */
-declare function astDefineCallExpression(args: NodeArray<Expression>, fnName: string, state: StateInterface): string | false;
+declare function astDefineCallExpression(init: CallExpression, state: StateInterface, decl?: VariableDeclaration, hasExport?: boolean, outerSuffix?: string): string | false;
 
 /**
  * Import will remove at compile time
@@ -14101,38 +14215,6 @@ declare function sandboxExecute(code: string, sandbox?: Context, options?: Scrip
  * @param index - The starting index in the text where the match was found
  * @returns A partial {@link Location} object containing file, line, and column information
  *
- * @remarks
- * Line numbers are 1-based. The column is calculated relative to the match index.
- * This function is primarily used for generating accurate diagnostic messages.
- *
- * @example
- * ```ts
- * const sourceCode = 'import x from "y";\nconst $$myMacro = $$ifdef("DEBUG");';
- * const macroIndex = sourceCode.indexOf('$$myMacro');
- *
- * const location = getLineAndColumn(sourceCode, '$$myMacro', 'src/app.ts', macroIndex);
- * console.log(location);
- * // Output: {
- * //   file: 'src/app.ts',
- * //   line: 2,
- * //   column: 6
- * // }
- * ```
- *
- * @example Multi-line file positioning
- * ```ts
- * const code = [
- *   'const x = 1;',
- *   'const y = 2;',
- *   'const $$feature = $$ifdef("FEATURE_X");'
- * ].join('\n');
- *
- * const index = code.indexOf('$$feature');
- * const loc = getLineAndColumn(code, '$$feature', 'config.ts', index);
- * // loc.line === 3
- * ```
- *
- * @see {@link Location}
  * @since 2.0.0
  */
 declare function getLineAndColumn(text: string, name: string, file: string, index: number): Partial<Location>;
@@ -15679,7 +15761,7 @@ declare function logBuildStart({ variantName }: BuildContextInterface): void;
  *
  * @since 2.0.0
  */
-declare function logBuildEnd({ variantName, duration, buildResult }: ResultContextInterface): void;
+declare function logBuildEnd({ variantName, duration, buildResult, stage }: ResultContextInterface): void;
 
 /**
  * Import will remove at compile time