// src/runtime/IHandlerCompiler.ts
//
// Vision 45 §10.2: Handler Compiler Interface
//
// Guy Steele (Scheme Design, "Growing a Language"):
//   "A language grows by giving new meaning to existing forms.
//    IHandlerCompiler lets you define what 'code' means - JavaScript or LISP."
//
// This interface abstracts the compilation of handler code strings into
// executable functions. Implementations exist for JavaScript (development)
// and LISP (production-safe sandboxed execution).

import type { IMatrixContext } from '../engine/core/IMatrixContext';
import type { IHandlerSchema } from '../serialization/IComponentSchema';

/**
 * Compiled handler ready for execution.
 *
 * The result of IHandlerCompiler.compile() is a callable function
 * that receives payload and meta, with `this` bound to the component.
 */
export interface ICompiledHandler {
  /**
   * Execute the handler.
   *
   * @param payload - The command payload
   * @param meta - Command metadata (source, timestamp, etc.)
   * @returns Handler result (if any)
   */
  (payload: unknown, meta: unknown): unknown;
}

/**
 * Compilation result with optional error info.
 */
export interface ICompilationResult {
  /** Whether compilation succeeded */
  success: boolean;

  /** Compiled handler (if success) */
  handler?: ICompiledHandler;

  /** Error message (if failed) */
  error?: string;

  /** Source location for debugging */
  sourceMap?: ISourceLocation;
}

/**
 * Source location for error reporting.
 */
export interface ISourceLocation {
  /** Line number (1-based) */
  line: number;

  /** Column number (1-based) */
  column: number;

  /** Source file/schema name */
  source?: string;
}

/**
 * Compilation options.
 */
export interface ICompilationOptions {
  /** Context for resolving dependencies */
  context?: IMatrixContext;

  /** Whether to enable source maps */
  sourceMap?: boolean;

  /** Whether to enable strict mode */
  strict?: boolean;

  /** Security context */
  securityContext?: 'trusted' | 'sandboxed';
}

/**
 * Handler compiler interface.
 *
 * Vision 45 §10.2: Abstracts JavaScript vs LISP compilation.
 *
 * Each compiler implementation handles a specific language:
 * - JavaScriptHandlerCompiler: Uses `new Function()` for JS code
 * - LispHandlerCompiler: Uses LispDispatchStrategy for sandboxed LISP
 *
 * @example
 * ```typescript
 * const compiler = new JavaScriptHandlerCompiler();
 * const result = compiler.compile('this.count++', 'increment');
 *
 * if (result.success && result.handler) {
 *   result.handler.call(component, payload, meta);
 * }
 * ```
 */
export interface IHandlerCompiler {
  /** Supported language */
  readonly language: 'javascript' | 'lisp';

  /**
   * Compile handler code into executable.
   *
   * @param code - Handler code string
   * @param commandName - Command this handler responds to (for error reporting)
   * @param options - Optional compilation settings
   * @returns Compilation result with handler or error
   */
  compile(
    code: string,
    commandName: string,
    options?: ICompilationOptions
  ): ICompilationResult;

  /**
   * Compile handler from schema definition.
   *
   * Convenience method that extracts code from IHandlerSchema.
   *
   * @param schema - Handler schema (code + language + security)
   * @param commandName - Command name for error reporting
   * @param options - Optional compilation settings
   * @returns Compilation result
   */
  compileFromSchema(
    schema: IHandlerSchema,
    commandName: string,
    options?: ICompilationOptions
  ): ICompilationResult;

  /**
   * Check if this compiler supports the given language.
   */
  supports(language: string): boolean;

  /**
   * Validate code without compiling.
   *
   * Useful for editor/IDE integration.
   *
   * @param code - Code to validate
   * @returns Validation errors (empty if valid)
   */
  validate(code: string): IValidationError[];
}

/**
 * Validation error from code checking.
 */
export interface IValidationError {
  /** Error message */
  message: string;

  /** Error location */
  location?: ISourceLocation;

  /** Error severity */
  severity: 'error' | 'warning' | 'info';
}
