macroforge 0.1.33 → 0.1.34

package/index.d.ts

@@ -1,204 +1,1138 @@
 /* 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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" Called by the TS plugin to execute macro expansion
+ * 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
 
+/**
+ * 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
 }
 
+/**
+ * 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
+ *
+ * ```ignore
+ * let result = expand_sync(env, code, filepath, None)?;
+ * if result.diagnostics.iter().any(|d| d.level == "error") {
+ *     // Handle errors
+ * }
+ * // Use result.code for the expanded source
+ * ```
+ */
 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
 }
 
-/** Expand macros in TypeScript code and return the transformed TS (types) and diagnostics */
+/**
+ * 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 */
+  /** Local identifier name in the import statement (e.g., `Derive` in `import { Derive }`). */
   local: string
-  /** Module specifier this identifier was imported from */
+  /** 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
 }
 
+/**
+ * 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
+ *
+ * ```ignore
+ * 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
 }
 
+/**
+ * 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