macroforge 0.1.75 → 0.1.77

package/index.d.ts

@@ -7,46 +7,46 @@
  * 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;
+  /**
+   * 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
 }
 
 /**
@@ -78,124 +78,120 @@ export declare class NativeMapper {
  * ```
  */
 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>;
+  /**
+   * 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>
 }
 
 /**
@@ -228,124 +224,124 @@ export declare class NativePlugin {
  * ```
  */
 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;
+  /**
+   * 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;
+export type NativePositionMapper = PositionMapper
 
 /**
  * Returns debug information about all registered macro descriptors (debug API).
@@ -357,7 +353,7 @@ export type NativePositionMapper = PositionMapper;
  *
  * A vector of strings describing each registered macro descriptor.
  */
-export declare function __macroforgeDebugDescriptors(): Array<string>;
+export declare function __macroforgeDebugDescriptors(): Array<string>
 
 /**
  * Returns all registered macro module names (debug API).
@@ -368,7 +364,7 @@ export declare function __macroforgeDebugDescriptors(): Array<string>;
  *
  * A vector of module names.
  */
-export declare function __macroforgeDebugGetModules(): Array<string>;
+export declare function __macroforgeDebugGetModules(): Array<string>
 
 /**
  * Looks up a macro by module and name (debug API).
@@ -384,7 +380,7 @@ export declare function __macroforgeDebugGetModules(): Array<string>;
  *
  * A string describing whether the macro was found or not.
  */
-export declare function __macroforgeDebugLookup(module: string, name: string): string;
+export declare function __macroforgeDebugLookup(module: string, name: string): string
 
 /**
  * Returns the names of all registered macros.
@@ -393,7 +389,7 @@ export declare function __macroforgeDebugLookup(module: string, name: string): s
  *
  * A vector of macro names (e.g., `["Debug", "Clone", "Serialize"]`).
  */
-export declare function __macroforgeGetMacroNames(): Array<string>;
+export declare function __macroforgeGetMacroNames(): Array<string>
 
 /**
  * Returns the complete manifest of all registered macros and decorators.
@@ -413,7 +409,7 @@ export declare function __macroforgeGetMacroNames(): Array<string>;
  * // ["Debug", "Clone", "PartialEq", "Hash", "Serialize", "Deserialize", ...]
  * ```
  */
-export declare function __macroforgeGetManifest(): MacroManifest;
+export declare function __macroforgeGetManifest(): MacroManifest
 
 /**
  * Checks if any macros are registered in this package.
@@ -424,7 +420,7 @@ export declare function __macroforgeGetManifest(): MacroManifest;
  *
  * `true` if at least one macro is registered, `false` otherwise.
  */
-export declare function __macroforgeIsMacroPackage(): boolean;
+export declare function __macroforgeIsMacroPackage(): boolean
 
 /**
  * r" Run this macro with the given context.
@@ -452,7 +448,7 @@ export declare function __macroforgeIsMacroPackage(): boolean;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunClone(contextJson: string): string;
+export declare function __macroforgeRunClone(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -480,7 +476,7 @@ export declare function __macroforgeRunClone(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunDebug(contextJson: string): string;
+export declare function __macroforgeRunDebug(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -508,7 +504,7 @@ export declare function __macroforgeRunDebug(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunDefault(contextJson: string): string;
+export declare function __macroforgeRunDefault(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -536,7 +532,7 @@ export declare function __macroforgeRunDefault(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunDeserialize(contextJson: string): string;
+export declare function __macroforgeRunDeserialize(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -564,7 +560,7 @@ export declare function __macroforgeRunDeserialize(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunHash(contextJson: string): string;
+export declare function __macroforgeRunHash(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -592,7 +588,7 @@ export declare function __macroforgeRunHash(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunOrd(contextJson: string): string;
+export declare function __macroforgeRunOrd(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -620,7 +616,7 @@ export declare function __macroforgeRunOrd(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunPartialEq(contextJson: string): string;
+export declare function __macroforgeRunPartialEq(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -648,7 +644,7 @@ export declare function __macroforgeRunPartialEq(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunPartialOrd(contextJson: string): string;
+export declare function __macroforgeRunPartialOrd(contextJson: string): string
 
 /**
  * r" Run this macro with the given context.
@@ -676,7 +672,7 @@ export declare function __macroforgeRunPartialOrd(contextJson: string): string;
  * r" - The `TsStream` cannot be created from the context
  * r" - The result cannot be serialized to JSON
  */
-export declare function __macroforgeRunSerialize(contextJson: string): string;
+export declare function __macroforgeRunSerialize(contextJson: string): string
 
 /**
  * Checks if the given TypeScript code has valid syntax.
@@ -702,7 +698,7 @@ export declare function __macroforgeRunSerialize(contextJson: string): string;
  * }
  * ```
  */
-export declare function checkSyntax(code: string, filepath: string): SyntaxCheckResult;
+export declare function checkSyntax(code: string, filepath: string): SyntaxCheckResult
 
 /**
  * Clears the configuration cache.
@@ -722,7 +718,7 @@ export declare function checkSyntax(code: string, filepath: string): SyntaxCheck
  * const result = loadConfig(configContent, configPath);
  * ```
  */
-export declare function clearConfigCache(): void;
+export declare function clearConfigCache(): void
 
 /**
  * Entry for a registered decorator in the manifest.
@@ -731,14 +727,14 @@ export declare function clearConfigCache(): void;
  * 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 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
 }
 
 /**
@@ -760,7 +756,7 @@ export interface DecoratorManifestEntry {
  * }
  * ```
  */
-export declare function Derive(...features: any[]): ClassDecorator;
+export declare function Derive(...features: any[]): ClassDecorator
 
 /**
  * Options for macro expansion.
@@ -768,49 +764,63 @@ export declare function Derive(...features: any[]): ClassDecorator;
  * 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;
+  /**
+   * 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
 }
 
 /**
@@ -840,16 +850,16 @@ export interface ExpandOptions {
  * ```
  */
 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;
+  /** 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
 }
 
 /**
@@ -889,11 +899,7 @@ export interface ExpandResult {
  * console.log(result.diagnostics); // Any warnings or errors
  * ```
  */
-export declare function expandSync(
-    code: string,
-    filepath: string,
-    options?: ExpandOptions | undefined | null
-): ExpandResult;
+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.
@@ -908,12 +914,12 @@ export declare function expandSync(
  * 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;
+  /** 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
 }
 
 /**
@@ -922,10 +928,10 @@ export interface GeneratedRegionResult {
  * 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;
+  /** 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
 }
 
 /**
@@ -935,16 +941,16 @@ export interface ImportSourceResult {
  * 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;
+  /** 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
 }
 
 /**
@@ -980,7 +986,7 @@ export interface JsDiagnostic {
  * const expanded = expandSync(code, filepath, { configPath });
  * ```
  */
-export declare function loadConfig(content: string, filepath: string): LoadConfigResult;
+export declare function loadConfig(content: string, filepath: string): LoadConfigResult
 
 /**
  * Result of loading a macroforge configuration file.
@@ -988,14 +994,14 @@ export declare function loadConfig(content: string, filepath: string): LoadConfi
  * 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;
+  /** 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
 }
 
 /**
@@ -1025,23 +1031,23 @@ export interface LoadConfigResult {
  * ```
  */
 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;
+  /**
+   * 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
 }
 
 /**
@@ -1053,12 +1059,12 @@ export interface MacroDiagnostic {
  * - 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>;
+  /** ABI version for compatibility checking. */
+  version: number
+  /** All registered macros (derive, attribute, function). */
+  macros: Array<MacroManifestEntry>
+  /** All registered field/class decorators. */
+  decorators: Array<DecoratorManifestEntry>
 }
 
 /**
@@ -1068,14 +1074,14 @@ export interface MacroManifest {
  * 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;
+  /** 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
 }
 
 /**
@@ -1092,14 +1098,14 @@ export interface MacroManifestEntry {
  * - 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;
+  /** 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
 }
 
 /**
@@ -1133,10 +1139,7 @@ export interface MappingSegmentResult {
  * // ]
  * ```
  */
-export declare function parseImportSources(
-    code: string,
-    filepath: string
-): Array<ImportSourceResult>;
+export declare function parseImportSources(code: string, filepath: string): Array<ImportSourceResult>
 
 /**
  * Options for processing a file through the macro system.
@@ -1145,26 +1148,84 @@ export declare function parseImportSources(
  * 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;
+  /**
+   * 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>
 }
 
 /**
@@ -1181,16 +1242,16 @@ export interface ProcessFileOptions {
  * - 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>;
+  /**
+   * 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>
 }
 
 /**
@@ -1199,10 +1260,10 @@ export interface SourceMappingResult {
  * 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;
+  /** Byte offset where the span starts. */
+  start: number
+  /** Length of the span in bytes. */
+  length: number
 }
 
 /**
@@ -1211,10 +1272,10 @@ export interface SpanResult {
  * 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;
+  /** `true` if the code parsed without errors, `false` otherwise. */
+  ok: boolean
+  /** Error message if parsing failed, `None` if successful. */
+  error?: string
 }
 
 /**
@@ -1231,23 +1292,23 @@ export interface SyntaxCheckResult {
  * * `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;
+  /** 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
 }
 
 /**
@@ -1277,4 +1338,4 @@ export interface TransformResult {
  *
  * Uses a 32MB thread stack to prevent stack overflow during deep AST recursion.
  */
-export declare function transformSync(code: string, filepath: string): TransformResult;
+export declare function transformSync(code: string, filepath: string): TransformResult