macroforge 0.1.78 → 0.1.79

package/index.d.ts

@@ -1,1341 +0,0 @@
-/* auto-generated by NAPI-RS */
-/* eslint-disable */
-/**
- * Wrapper around `NativePositionMapper` for NAPI compatibility.
- *
- * This provides the same functionality as `NativePositionMapper` but with a
- * different JavaScript class name. Used internally by [`NativePlugin::get_mapper`].
- */
-export declare class NativeMapper {
-  /**
-   * Creates a new mapper wrapping the given source mapping.
-   *
-   * # Arguments
-   *
-   * * `mapping` - The source mapping result from macro expansion
-   */
-  constructor(mapping: SourceMappingResult)
-  /** Checks if this mapper has no mapping data. */
-  isEmpty(): boolean
-  /**
-   * Converts a position in the original source to expanded source.
-   * See [`NativePositionMapper::original_to_expanded`] for details.
-   */
-  originalToExpanded(pos: number): number
-  /**
-   * Converts a position in the expanded source back to original.
-   * See [`NativePositionMapper::expanded_to_original`] for details.
-   */
-  expandedToOriginal(pos: number): number | null
-  /**
-   * Returns the name of the macro that generated code at the given position.
-   * See [`NativePositionMapper::generated_by`] for details.
-   */
-  generatedBy(pos: number): string | null
-  /**
-   * Maps a span from expanded source to original source.
-   * See [`NativePositionMapper::map_span_to_original`] for details.
-   */
-  mapSpanToOriginal(start: number, length: number): SpanResult | null
-  /**
-   * Maps a span from original source to expanded source.
-   * See [`NativePositionMapper::map_span_to_expanded`] for details.
-   */
-  mapSpanToExpanded(start: number, length: number): SpanResult
-  /**
-   * Checks if a position is inside macro-generated code.
-   * See [`NativePositionMapper::is_in_generated`] for details.
-   */
-  isInGenerated(pos: number): boolean
-}
-
-/**
- * The main plugin class for macro expansion with caching support.
- *
- * `NativePlugin` is designed to be instantiated once and reused across multiple
- * file processing operations. It maintains a cache of expansion results keyed
- * by filepath and version, enabling efficient incremental processing.
- *
- * # Thread Safety
- *
- * The plugin is thread-safe through the use of `Mutex` for internal state.
- * However, macro expansion itself runs in a separate thread with a 32MB stack
- * to prevent stack overflow during deep AST recursion.
- *
- * # Example
- *
- * ```javascript
- * // Create a single plugin instance (typically at startup)
- * const plugin = new NativePlugin();
- *
- * // Process files with caching
- * const result1 = plugin.process_file("src/foo.ts", code1, { version: "1" });
- * const result2 = plugin.process_file("src/foo.ts", code2, { version: "1" }); // Cache hit!
- * const result3 = plugin.process_file("src/foo.ts", code3, { version: "2" }); // Cache miss
- *
- * // Get a mapper for position translation
- * const mapper = plugin.get_mapper("src/foo.ts");
- * ```
- */
-export declare class NativePlugin {
-  /**
-   * Creates a new `NativePlugin` instance.
-   *
-   * Initializes the plugin with an empty cache and sets up a default log file
-   * at `/tmp/macroforge-plugin.log` for debugging purposes.
-   *
-   * # Returns
-   *
-   * A new `NativePlugin` ready for processing files.
-   *
-   * # Side Effects
-   *
-   * Creates or clears the log file at `/tmp/macroforge-plugin.log`.
-   */
-  constructor()
-  /**
-   * Writes a message to the plugin's log file.
-   *
-   * Useful for debugging macro expansion issues in production environments.
-   *
-   * # Arguments
-   *
-   * * `message` - The message to log
-   *
-   * # Note
-   *
-   * Messages are appended to the log file. If the log file hasn't been
-   * configured or cannot be written to, the message is silently dropped.
-   */
-  log(message: string): void
-  /**
-   * Sets the path for the plugin's log file.
-   *
-   * # Arguments
-   *
-   * * `path` - The file path to use for logging
-   *
-   * # Note
-   *
-   * This does not create the file; it will be created when the first
-   * message is logged.
-   */
-  setLogFile(path: string): void
-  /**
-   * Processes a TypeScript file through the macro expansion system.
-   *
-   * This is the main entry point for file processing. It handles caching,
-   * thread isolation (to prevent stack overflow), and error recovery.
-   *
-   * # Arguments
-   *
-   * * `_env` - NAPI environment (unused but required by NAPI)
-   * * `filepath` - Path to the file (used for TSX detection and caching)
-   * * `code` - The TypeScript source code to process
-   * * `options` - Optional configuration for expansion and caching
-   *
-   * # Returns
-   *
-   * An [`ExpandResult`] containing the expanded code, diagnostics, and source mapping.
-   *
-   * # Errors
-   *
-   * Returns an error if:
-   * - Thread spawning fails
-   * - The worker thread panics (often due to stack overflow)
-   * - Macro expansion fails internally
-   *
-   * # Performance
-   *
-   * - Uses a 32MB thread stack to prevent stack overflow during deep AST recursion
-   * - Caches results by filepath and version for efficient incremental processing
-   * - Early bailout for files without `@derive` decorators
-   *
-   * # Thread Safety
-   *
-   * Macro expansion runs in a separate thread because:
-   * 1. SWC AST operations can be deeply recursive, exceeding default stack limits
-   * 2. Node.js thread stack is typically only 2MB
-   * 3. Panics in the worker thread are caught and reported gracefully
-   */
-  processFile(filepath: string, code: string, options?: ProcessFileOptions | undefined | null): ExpandResult
-  /**
-   * Retrieves a position mapper for a previously processed file.
-   *
-   * The mapper enables translation between original and expanded source positions,
-   * which is essential for IDE features like error reporting and navigation.
-   *
-   * # Arguments
-   *
-   * * `filepath` - Path to the file (must have been previously processed)
-   *
-   * # Returns
-   *
-   * `Some(NativeMapper)` if the file has been processed and has source mapping data,
-   * `None` if the file hasn't been processed or has no mapping (no macros expanded).
-   */
-  getMapper(filepath: string): NativeMapper | null
-  /**
-   * Maps diagnostics from expanded source positions back to original source positions.
-   *
-   * This is used by IDE integrations to show errors at the correct locations
-   * in the user's original code, rather than in the macro-expanded output.
-   *
-   * # Arguments
-   *
-   * * `filepath` - Path to the file the diagnostics are for
-   * * `diags` - Diagnostics with positions in the expanded source
-   *
-   * # Returns
-   *
-   * Diagnostics with positions mapped back to the original source.
-   * If no mapper is available for the file, returns diagnostics unchanged.
-   */
-  mapDiagnostics(filepath: string, diags: Array<JsDiagnostic>): Array<JsDiagnostic>
-}
-
-/**
- * Bidirectional position mapper for translating between original and expanded source positions.
- *
- * This mapper enables IDE features like error reporting, go-to-definition, and hover
- * to work correctly with macro-expanded code by translating positions between the
- * original source (what the user wrote) and the expanded source (what the compiler sees).
- *
- * # Performance
- *
- * Position lookups use binary search for O(log n) complexity, where n is the number
- * of mapping segments. This is critical for responsive IDE interactions.
- *
- * # Example
- *
- * ```javascript
- * const mapper = new PositionMapper(sourceMapping);
- *
- * // Convert original position to expanded
- * const expandedPos = mapper.original_to_expanded(42);
- *
- * // Convert expanded position back to original (if not in generated code)
- * const originalPos = mapper.expanded_to_original(100);
- *
- * // Check if a position is in macro-generated code
- * if (mapper.is_in_generated(pos)) {
- *     const macro = mapper.generated_by(pos); // e.g., "Debug"
- * }
- * ```
- */
-export declare class PositionMapper {
-  /**
-   * Creates a new position mapper from source mapping data.
-   *
-   * # Arguments
-   *
-   * * `mapping` - The source mapping result from macro expansion
-   *
-   * # Returns
-   *
-   * A new `NativePositionMapper` ready for position translation.
-   */
-  constructor(mapping: SourceMappingResult)
-  /**
-   * Checks if this mapper has no mapping data.
-   *
-   * An empty mapper indicates no transformations occurred, so position
-   * translation is an identity operation.
-   *
-   * # Returns
-   *
-   * `true` if there are no segments and no generated regions.
-   */
-  isEmpty(): boolean
-  /**
-   * Converts a position in the original source to the corresponding position in expanded source.
-   *
-   * Uses binary search for O(log n) lookup performance.
-   *
-   * # Arguments
-   *
-   * * `pos` - Byte offset in the original source
-   *
-   * # Returns
-   *
-   * The corresponding byte offset in the expanded source. If the position falls
-   * in a gap between segments, returns the position unchanged. If after the last
-   * segment, extrapolates based on the delta.
-   *
-   * # Algorithm
-   *
-   * 1. Binary search to find the segment containing or after `pos`
-   * 2. If inside a segment, compute offset within segment and translate
-   * 3. If after all segments, extrapolate from the last segment
-   * 4. Otherwise, return position unchanged (gap or before first segment)
-   */
-  originalToExpanded(pos: number): number
-  /**
-   * Converts a position in the expanded source back to the original source position.
-   *
-   * Returns `None` if the position is inside macro-generated code that has no
-   * corresponding location in the original source.
-   *
-   * # Arguments
-   *
-   * * `pos` - Byte offset in the expanded source
-   *
-   * # Returns
-   *
-   * `Some(original_pos)` if the position maps to original code,
-   * `None` if the position is in macro-generated code.
-   */
-  expandedToOriginal(pos: number): number | null
-  /**
-   * Returns the name of the macro that generated code at the given position.
-   *
-   * # Arguments
-   *
-   * * `pos` - Byte offset in the expanded source
-   *
-   * # Returns
-   *
-   * `Some(macro_name)` if the position is inside generated code (e.g., "Debug"),
-   * `None` if the position is in original (non-generated) code.
-   */
-  generatedBy(pos: number): string | null
-  /**
-   * Maps a span (start + length) from expanded source to original source.
-   *
-   * # Arguments
-   *
-   * * `start` - Start byte offset in expanded source
-   * * `length` - Length of the span in bytes
-   *
-   * # Returns
-   *
-   * `Some(SpanResult)` with the mapped span in original source,
-   * `None` if either endpoint is in generated code.
-   */
-  mapSpanToOriginal(start: number, length: number): SpanResult | null
-  /**
-   * Maps a span (start + length) from original source to expanded source.
-   *
-   * This always succeeds since every original position has an expanded equivalent.
-   *
-   * # Arguments
-   *
-   * * `start` - Start byte offset in original source
-   * * `length` - Length of the span in bytes
-   *
-   * # Returns
-   *
-   * A `SpanResult` with the mapped span in expanded source.
-   */
-  mapSpanToExpanded(start: number, length: number): SpanResult
-  /**
-   * Checks if a position is inside macro-generated code.
-   *
-   * # Arguments
-   *
-   * * `pos` - Byte offset in the expanded source
-   *
-   * # Returns
-   *
-   * `true` if the position is inside a generated region, `false` otherwise.
-   */
-  isInGenerated(pos: number): boolean
-}
-export type NativePositionMapper = PositionMapper
-
-/**
- * Returns debug information about all registered macro descriptors (debug API).
- *
- * This provides low-level access to the inventory-based macro registration
- * system for debugging purposes.
- *
- * # Returns
- *
- * A vector of strings describing each registered macro descriptor.
- */
-export declare function __macroforgeDebugDescriptors(): Array<string>
-
-/**
- * Returns all registered macro module names (debug API).
- *
- * Modules group related macros together (e.g., "builtin", "serde").
- *
- * # Returns
- *
- * A vector of module names.
- */
-export declare function __macroforgeDebugGetModules(): Array<string>
-
-/**
- * Looks up a macro by module and name (debug API).
- *
- * Useful for testing macro registration and debugging lookup issues.
- *
- * # Arguments
- *
- * * `module` - The module name (e.g., "builtin")
- * * `name` - The macro name (e.g., "Debug")
- *
- * # Returns
- *
- * A string describing whether the macro was found or not.
- */
-export declare function __macroforgeDebugLookup(module: string, name: string): string
-
-/**
- * Returns the names of all registered macros.
- *
- * # Returns
- *
- * A vector of macro names (e.g., `["Debug", "Clone", "Serialize"]`).
- */
-export declare function __macroforgeGetMacroNames(): Array<string>
-
-/**
- * Returns the complete manifest of all registered macros and decorators.
- *
- * This is a debug/introspection API that allows tooling to discover
- * what macros are available at runtime.
- *
- * # Returns
- *
- * A [`MacroManifest`] containing all registered macros and decorators.
- *
- * # Example (JavaScript)
- *
- * ```javascript
- * const manifest = __macroforgeGetManifest();
- * console.log("Available macros:", manifest.macros.map(m => m.name));
- * // ["Debug", "Clone", "PartialEq", "Hash", "Serialize", "Deserialize", ...]
- * ```
- */
-export declare function __macroforgeGetManifest(): MacroManifest
-
-/**
- * Checks if any macros are registered in this package.
- *
- * Useful for build tools to determine if macro expansion is needed.
- *
- * # Returns
- *
- * `true` if at least one macro is registered, `false` otherwise.
- */
-export declare function __macroforgeIsMacroPackage(): boolean
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunClone(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunDebug(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunDefault(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunDeserialize(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunHash(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunOrd(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunPartialEq(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunPartialOrd(contextJson: string): string
-
-/**
- * r" Run this macro with the given context.
- * r"
- * r" This function is automatically generated and exposed to JavaScript via NAPI.
- * r" It deserializes the macro context from JSON, executes the macro transformation,
- * r" and serializes the result back to JSON for the TypeScript plugin.
- * r"
- * r" # Arguments
- * r"
- * r" * `context_json` - A JSON string containing the [`MacroContextIR`] with:
- * r"   - `target_source`: The TypeScript source code to transform
- * r"   - `file_name`: The source file path for error reporting
- * r"   - Additional context metadata
- * r"
- * r" # Returns
- * r"
- * r" A JSON string containing the [`MacroResult`] with the transformed code
- * r" or any diagnostic errors.
- * r"
- * r" # Errors
- * r"
- * r" Returns a NAPI error if:
- * r" - The input JSON cannot be parsed
- * r" - The `TsStream` cannot be created from the context
- * r" - The result cannot be serialized to JSON
- */
-export declare function __macroforgeRunSerialize(contextJson: string): string
-
-/**
- * Checks if the given TypeScript code has valid syntax.
- *
- * This function attempts to parse the code using SWC's TypeScript parser
- * without performing any macro expansion.
- *
- * # Arguments
- *
- * * `code` - The TypeScript source code to check
- * * `filepath` - The file path (used to determine if it's TSX based on extension)
- *
- * # Returns
- *
- * A [`SyntaxCheckResult`] indicating success or containing the parse error.
- *
- * # Example
- *
- * ```javascript
- * const result = check_syntax("const x: number = 42;", "test.ts");
- * if (!result.ok) {
- *     console.error("Syntax error:", result.error);
- * }
- * ```
- */
-export declare function checkSyntax(code: string, filepath: string): SyntaxCheckResult
-
-/**
- * Clears the configuration cache.
- *
- * This is useful for testing to ensure each test starts with a clean state.
- * In production, clearing the cache will force configs to be re-parsed on next access.
- *
- * # Example
- *
- * ```javascript
- * const { clearConfigCache, loadConfig } = require('macroforge-ts');
- *
- * // Clear cache before each test
- * clearConfigCache();
- *
- * // Now load a fresh config
- * const result = loadConfig(configContent, configPath);
- * ```
- */
-export declare function clearConfigCache(): void
-
-/**
- * Entry for a registered decorator in the manifest.
- *
- * Used by [`MacroManifest`] to describe field-level decorators
- * that can be used with macros.
- */
-export interface DecoratorManifestEntry {
-  /** The module this decorator belongs to (e.g., "serde"). */
-  module: string
-  /** The exported name of the decorator (e.g., "skip", "rename"). */
-  export: string
-  /** The decorator kind: "class", "property", "method", "accessor", "parameter". */
-  kind: string
-  /** Documentation string for the decorator. */
-  docs: string
-}
-
-/**
- * The `@Derive` decorator function exported to JavaScript/TypeScript.
- *
- * This is a no-op function that exists purely for TypeScript type checking.
- * The actual decorator processing happens during macro expansion, where
- * `@derive(...)` decorators are recognized and transformed.
- *
- * # TypeScript Usage
- *
- * ```typescript
- * import { Derive } from "macroforge-ts";
- *
- * @Derive(Debug, Clone, Serialize)
- * class User {
- *     name: string;
- *     email: string;
- * }
- * ```
- */
-export declare function Derive(...features: any[]): ClassDecorator
-
-/**
- * Options for macro expansion.
- *
- * Used by [`expand_sync`] to configure expansion behavior.
- */
-export interface ExpandOptions {
-  /**
-   * If `true`, preserves `@derive` decorators in the output.
-   * If `false` (default), decorators are stripped after expansion.
-   */
-  keepDecorators?: boolean
-  /**
-   * Additional decorator module names from external macros.
-   *
-   * These are used during decorator stripping to identify Macroforge-specific
-   * decorators that should be removed from the output. Built-in decorator modules
-   * (like "serde", "debug") are automatically included.
-   *
-   * External macro packages should export their decorator module names, which
-   * plugins can collect and pass here.
-   *
-   * # Example
-   *
-   * ```javascript
-   * expandSync(code, filepath, {
-   *   keepDecorators: false,
-   *   externalDecoratorModules: ["myMacro", "customValidator"]
-   * });
-   * ```
-   */
-  externalDecoratorModules?: Array<string>
-  /**
-   * Path to a previously loaded config file.
-   *
-   * When provided, the expansion will use the cached configuration
-   * (including foreign types) from this path. The config must have been
-   * previously loaded via [`load_config`].
-   *
-   * # Example
-   *
-   * ```javascript
-   * // First, load the config
-   * const configResult = loadConfig(configContent, configPath);
-   *
-   * // Then use it during expansion
-   * expandSync(code, filepath, { configPath });
-   * ```
-   */
-  configPath?: string
-  /**
-   * Pre-built type registry JSON from [`scan_project_sync`].
-   *
-   * When provided, macros receive project-wide type awareness through
-   * the `type_registry` and `resolved_fields` fields on `MacroContextIR`.
-   *
-   * # Example
-   *
-   * ```javascript
-   * const scan = scanProjectSync(projectRoot);
-   * expandSync(code, filepath, { typeRegistryJson: scan.registryJson });
-   * ```
-   */
-  typeRegistryJson?: string
-}
-
-/**
- * Result of expanding macros in TypeScript source code.
- *
- * This is the primary return type for macro expansion operations,
- * containing the expanded code, diagnostics, and source mapping.
- *
- * # Example
- *
- * ```rust
- * use macroforge_ts::{ExpandResult, MacroDiagnostic};
- *
- * // Create an ExpandResult programmatically
- * let result = ExpandResult {
- *     code: "class User {}".to_string(),
- *     types: None,
- *     metadata: None,
- *     diagnostics: vec![],
- *     source_mapping: None,
- * };
- *
- * // Check for errors
- * if result.diagnostics.iter().any(|d| d.level == "error") {
- *     // Handle errors
- * }
- * ```
- */
-export interface ExpandResult {
-  /** The expanded TypeScript code with all macros processed. */
-  code: string
-  /** Optional TypeScript type declarations for generated methods. */
-  types?: string
-  /** Optional JSON metadata about processed classes. */
-  metadata?: string
-  /** Diagnostics (errors, warnings, info) from the expansion process. */
-  diagnostics: Array<MacroDiagnostic>
-  /** Source mapping for position translation between original and expanded code. */
-  sourceMapping?: SourceMappingResult
-}
-
-/**
- * Synchronously expands macros in TypeScript code.
- *
- * This is the standalone macro expansion function that doesn't use caching.
- * For cached expansion, use [`NativePlugin::process_file`] instead.
- *
- * # Arguments
- *
- * * `_env` - NAPI environment (unused but required by NAPI)
- * * `code` - The TypeScript source code to expand
- * * `filepath` - The file path (used for TSX detection)
- * * `options` - Optional configuration (e.g., `keep_decorators`)
- *
- * # Returns
- *
- * An [`ExpandResult`] containing the expanded code, diagnostics, and source mapping.
- *
- * # Errors
- *
- * Returns an error if:
- * - Thread spawning fails
- * - The worker thread panics
- * - Macro host initialization fails
- *
- * # Performance
- *
- * - Uses a 32MB thread stack to prevent stack overflow
- * - Performs early bailout for files without `@derive` decorators
- *
- * # Example
- *
- * ```javascript
- * const result = expand_sync(env, code, "user.ts", { keep_decorators: false });
- * console.log(result.code); // Expanded TypeScript code
- * console.log(result.diagnostics); // Any warnings or errors
- * ```
- */
-export declare function expandSync(code: string, filepath: string, options?: ExpandOptions | undefined | null): ExpandResult
-
-/**
- * A region in the expanded source that was generated by a macro.
- *
- * These regions identify code that has no corresponding location in the
- * original source because it was synthesized by a macro.
- *
- * # Example
- *
- * For a `@derive(Debug)` macro that generates a `toString()` method,
- * a `GeneratedRegionResult` would mark the entire method body as generated
- * with `source_macro = "Debug"`.
- */
-export interface GeneratedRegionResult {
-  /** Byte offset where the generated region starts in the expanded source. */
-  start: number
-  /** Byte offset where the generated region ends in the expanded source. */
-  end: number
-  /** Name of the macro that generated this region (e.g., "Debug", "Clone"). */
-  sourceMacro: string
-}
-
-/**
- * Information about an imported identifier from a TypeScript module.
- *
- * Used to track where decorators and macro-related imports come from.
- */
-export interface ImportSourceResult {
-  /** Local identifier name in the import statement (e.g., `Derive` in `import { Derive }`). */
-  local: string
-  /** Module specifier this identifier was imported from (e.g., `"macroforge-ts"`). */
-  module: string
-}
-
-/**
- * A diagnostic from the TypeScript/JavaScript compiler or IDE.
- *
- * This structure mirrors TypeScript's diagnostic format for interoperability
- * with language servers and IDEs.
- */
-export interface JsDiagnostic {
-  /** Byte offset where the diagnostic starts. `None` for global diagnostics. */
-  start?: number
-  /** Length of the diagnostic span in bytes. */
-  length?: number
-  /** Human-readable diagnostic message. */
-  message?: string
-  /** TypeScript diagnostic code (e.g., 2304 for "Cannot find name"). */
-  code?: number
-  /** Diagnostic category: "error", "warning", "suggestion", "message". */
-  category?: string
-}
-
-/**
- * Load and parse a macroforge configuration file.
- *
- * Parses a `macroforge.config.js/ts` file and caches the result for use
- * during macro expansion. The configuration includes both simple settings
- * (like `keepDecorators`) and foreign type handlers.
- *
- * # Arguments
- *
- * * `content` - The raw content of the configuration file
- * * `filepath` - Path to the configuration file (used to determine syntax and as cache key)
- *
- * # Returns
- *
- * A [`LoadConfigResult`] containing the parsed configuration summary.
- *
- * # Example
- *
- * ```javascript
- * import { loadConfig, expandSync } from 'macroforge';
- * import fs from 'fs';
- *
- * const configPath = 'macroforge.config.js';
- * const configContent = fs.readFileSync(configPath, 'utf-8');
- *
- * // Load and cache the configuration
- * const result = loadConfig(configContent, configPath);
- * console.log(`Loaded config with ${result.foreignTypeCount} foreign types`);
- *
- * // The config is now cached and will be used by expandSync
- * const expanded = expandSync(code, filepath, { configPath });
- * ```
- */
-export declare function loadConfig(content: string, filepath: string): LoadConfigResult
-
-/**
- * Result of loading a macroforge configuration file.
- *
- * Returned by [`load_config`] after parsing a `macroforge.config.js/ts` file.
- */
-export interface LoadConfigResult {
-  /** Whether to preserve `@derive` decorators in the output code. */
-  keepDecorators: boolean
-  /** Whether to generate a convenience const for non-class types. */
-  generateConvenienceConst: boolean
-  /** Whether the config has any foreign type handlers defined. */
-  hasForeignTypes: boolean
-  /** Number of foreign types configured. */
-  foreignTypeCount: number
-}
-
-/**
- * A diagnostic message produced during macro expansion.
- *
- * Diagnostics can represent errors, warnings, or informational messages
- * that occurred during the macro expansion process.
- *
- * # Fields
- *
- * * `level` - Severity level: "error", "warning", or "info"
- * * `message` - Human-readable description of the issue
- * * `start` - Optional byte offset where the issue starts in the source
- * * `end` - Optional byte offset where the issue ends in the source
- *
- * # Example
- *
- * ```rust
- * use macroforge_ts::MacroDiagnostic;
- *
- * let _diag = MacroDiagnostic {
- *     level: "error".to_string(),
- *     message: "Unknown macro 'Foo'".to_string(),
- *     start: Some(42),
- *     end: Some(45),
- * };
- * ```
- */
-export interface MacroDiagnostic {
-  /**
-   * Severity level of the diagnostic.
-   * One of: "error", "warning", "info".
-   */
-  level: string
-  /** Human-readable message describing the diagnostic. */
-  message: string
-  /**
-   * Byte offset in the original source where the issue starts.
-   * `None` if the diagnostic is not associated with a specific location.
-   */
-  start?: number
-  /**
-   * Byte offset in the original source where the issue ends.
-   * `None` if the diagnostic is not associated with a specific location.
-   */
-  end?: number
-}
-
-/**
- * Complete manifest of all available macros and decorators.
- *
- * This is returned by [`get_macro_manifest`] and is useful for:
- * - IDE autocompletion
- * - Documentation generation
- * - Tooling integration
- */
-export interface MacroManifest {
-  /** ABI version for compatibility checking. */
-  version: number
-  /** All registered macros (derive, attribute, function). */
-  macros: Array<MacroManifestEntry>
-  /** All registered field/class decorators. */
-  decorators: Array<DecoratorManifestEntry>
-}
-
-/**
- * Entry for a registered macro in the manifest.
- *
- * Used by [`MacroManifest`] to describe available macros to tooling
- * such as IDE extensions and documentation generators.
- */
-export interface MacroManifestEntry {
-  /** The macro name (e.g., "Debug", "Clone", "Serialize"). */
-  name: string
-  /** The macro kind: "derive", "attribute", or "function". */
-  kind: string
-  /** Human-readable description of what the macro does. */
-  description: string
-  /** The package that provides this macro (e.g., "macroforge-ts"). */
-  package: string
-}
-
-/**
- * A segment mapping a range in the original source to a range in the expanded source.
- *
- * These segments form the core of the bidirectional source mapping system,
- * enabling IDE features like "go to definition" and error reporting to work
- * correctly with macro-expanded code.
- *
- * # Invariants
- *
- * - `original_start < original_end`
- * - `expanded_start < expanded_end`
- * - Segments are non-overlapping and sorted by position
- */
-export interface MappingSegmentResult {
-  /** Byte offset where this segment starts in the original source. */
-  originalStart: number
-  /** Byte offset where this segment ends in the original source. */
-  originalEnd: number
-  /** Byte offset where this segment starts in the expanded source. */
-  expandedStart: number
-  /** Byte offset where this segment ends in the expanded source. */
-  expandedEnd: number
-}
-
-/**
- * Parses import statements from TypeScript code and returns their sources.
- *
- * This function extracts information about all import statements in the code,
- * mapping each imported identifier to its source module. Useful for analyzing
- * dependencies and understanding where decorators come from.
- *
- * # Arguments
- *
- * * `code` - The TypeScript source code to parse
- * * `filepath` - The file path (used for TSX detection)
- *
- * # Returns
- *
- * A vector of [`ImportSourceResult`] entries, one for each imported identifier.
- *
- * # Errors
- *
- * Returns an error if the code cannot be parsed.
- *
- * # Example
- *
- * ```javascript
- * // For code: import { Derive, Clone } from "macroforge-ts";
- * const imports = parse_import_sources(code, "test.ts");
- * // Returns: [
- * //   { local: "Derive", module: "macroforge-ts" },
- * //   { local: "Clone", module: "macroforge-ts" }
- * // ]
- * ```
- */
-export declare function parseImportSources(code: string, filepath: string): Array<ImportSourceResult>
-
-/**
- * Options for processing a file through the macro system.
- *
- * Used by [`NativePlugin::process_file`] to configure expansion behavior
- * and caching.
- */
-export interface ProcessFileOptions {
-  /**
-   * If `true`, preserves `@derive` decorators in the output.
-   * If `false` (default), decorators are stripped after expansion.
-   */
-  keepDecorators?: boolean
-  /**
-   * Version string for cache invalidation.
-   * When provided, cached results are only reused if versions match.
-   */
-  version?: string
-  /**
-   * Additional decorator module names from external macros.
-   * See [`ExpandOptions::external_decorator_modules`] for details.
-   */
-  externalDecoratorModules?: Array<string>
-  /**
-   * Path to a previously loaded config file (for foreign types lookup).
-   * See [`ExpandOptions::config_path`] for details.
-   */
-  configPath?: string
-  /**
-   * Pre-built type registry JSON from [`scan_project_sync`].
-   * See [`ExpandOptions::type_registry_json`] for details.
-   */
-  typeRegistryJson?: string
-}
-
-/** Options for scanning a TypeScript project for type information. */
-export interface ScanOptions {
-  /** File extensions to scan (default: `[".ts", ".tsx"]`). */
-  extensions?: Array<string>
-  /** Whether to only collect exported types (default: `false`). */
-  exportedOnly?: boolean
-}
-
-/**
- * Scan a TypeScript project and build a type registry.
- *
- * This should be called once at build start (e.g., in Vite's `buildStart` hook)
- * and the resulting `registry_json` should be passed to [`expand_sync`] via
- * `ExpandOptions.type_registry_json`.
- *
- * # Arguments
- *
- * * `root_dir` - The project root directory to scan
- * * `options` - Optional scan configuration
- *
- * # Returns
- *
- * A [`ScanResult`] with the serialized registry and scan statistics.
- *
- * # Example
- *
- * ```javascript
- * const scan = scanProjectSync(projectRoot);
- * console.log(`Found ${scan.typesFound} types in ${scan.filesScanned} files`);
- *
- * // Pass to expand_sync for each file
- * const result = expandSync(code, filepath, {
- *   typeRegistryJson: scan.registryJson,
- * });
- * ```
- */
-export declare function scanProjectSync(rootDir: string, options?: ScanOptions | undefined | null): ScanResult
-
-/** Result of scanning a project for type information. */
-export interface ScanResult {
-  /**
-   * JSON-serialized [`TypeRegistry`].
-   * Pass this to `expand_sync` via `ExpandOptions.type_registry_json`.
-   */
-  registryJson: string
-  /** Number of files scanned. */
-  filesScanned: number
-  /** Number of types found. */
-  typesFound: number
-  /** Diagnostics from scanning (e.g., files that failed to parse). */
-  diagnostics: Array<MacroDiagnostic>
-}
-
-/**
- * Complete source mapping information for a macro expansion.
- *
- * Contains both preserved segments (original code that wasn't modified)
- * and generated regions (new code synthesized by macros).
- *
- * # Usage
- *
- * This mapping enables:
- * - Converting positions from original source to expanded source and vice versa
- * - Identifying which macro generated a given piece of code
- * - Mapping IDE diagnostics from expanded code back to original source
- */
-export interface SourceMappingResult {
-  /**
-   * Segments mapping preserved regions between original and expanded source.
-   * Sorted by position for efficient binary search lookups.
-   */
-  segments: Array<MappingSegmentResult>
-  /**
-   * Regions in the expanded source that were generated by macros.
-   * Used to identify synthetic code with no original source location.
-   */
-  generatedRegions: Array<GeneratedRegionResult>
-}
-
-/**
- * A span (range) in source code, represented as start position and length.
- *
- * Used for mapping diagnostics and other positional information.
- */
-export interface SpanResult {
-  /** Byte offset where the span starts. */
-  start: number
-  /** Length of the span in bytes. */
-  length: number
-}
-
-/**
- * Result of checking TypeScript syntax validity.
- *
- * Returned by [`check_syntax`] to indicate whether code parses successfully.
- */
-export interface SyntaxCheckResult {
-  /** `true` if the code parsed without errors, `false` otherwise. */
-  ok: boolean
-  /** Error message if parsing failed, `None` if successful. */
-  error?: string
-}
-
-/**
- * Result of transforming TypeScript code through the macro system.
- *
- * This struct is returned by [`transform_sync`] and contains the transformed code
- * along with optional source maps, type declarations, and metadata about processed classes.
- *
- * # Fields
- *
- * * `code` - The transformed TypeScript/JavaScript code with macros expanded
- * * `map` - Optional source map for debugging (currently not implemented)
- * * `types` - Optional TypeScript type declarations for generated methods
- * * `metadata` - Optional JSON metadata about processed classes
- */
-export interface TransformResult {
-  /** The transformed TypeScript/JavaScript code with all macros expanded. */
-  code: string
-  /**
-   * Source map for mapping transformed positions back to original.
-   * Currently always `None` - source mapping is handled separately via `SourceMappingResult`.
-   */
-  map?: string
-  /**
-   * TypeScript type declarations (`.d.ts` content) for generated methods.
-   * Used by IDEs to provide type information for macro-generated code.
-   */
-  types?: string
-  /**
-   * JSON-serialized metadata about processed classes.
-   * Contains information about which classes were processed and what was generated.
-   */
-  metadata?: string
-}
-
-/**
- * Synchronously transforms TypeScript code through the macro expansion system.
- *
- * This is similar to [`expand_sync`] but returns a [`TransformResult`] which
- * includes source map information (when available).
- *
- * # Arguments
- *
- * * `_env` - NAPI environment (unused but required by NAPI)
- * * `code` - The TypeScript source code to transform
- * * `filepath` - The file path (used for TSX detection)
- *
- * # Returns
- *
- * A [`TransformResult`] containing the transformed code and metadata.
- *
- * # Errors
- *
- * Returns an error if:
- * - Thread spawning fails
- * - The worker thread panics
- * - Macro expansion fails
- *
- * # Thread Safety
- *
- * Uses a 32MB thread stack to prevent stack overflow during deep AST recursion.
- */
-export declare function transformSync(code: string, filepath: string): TransformResult