/* 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

/**
 * 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
}

/**
 * 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
}

/**
 * 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
