@lokascript/framework 2.0.0

package/src/aot/aot-orchestrator.ts

@@ -0,0 +1,238 @@
+/**
+ * Generalized AOT Orchestrator
+ *
+ * Coordinates scan → parse → compile → collect for any domain.
+ * Each domain provides a DomainCompilationBackend (DSL + CodeGenerator + scan config),
+ * and the orchestrator handles the rest.
+ *
+ * @example
+ * ```typescript
+ * import { AOTOrchestrator } from '@lokascript/framework';
+ *
+ * const orchestrator = new AOTOrchestrator();
+ *
+ * orchestrator.registerBackend({
+ *   domain: 'sql',
+ *   dsl: createSQLDSL(),
+ *   codeGenerator: sqlCodeGenerator,
+ *   scanConfig: {
+ *     domain: 'sql',
+ *     attributes: ['data-sql'],
+ *     scriptTypes: ['text/sql-dsl'],
+ *   },
+ * });
+ *
+ * const result = await orchestrator.compileFiles(
+ *   ['index.html', 'about.html'],
+ *   (path) => fs.promises.readFile(path, 'utf-8')
+ * );
+ * ```
+ */
+
+import type { MultilingualDSL, CodeGenerator } from '../api/create-dsl';
+import type {
+  DomainScanConfig,
+  ExtractedSnippet,
+  CompiledSnippet,
+  AOTBatchResult,
+  GeneralizedAOTOptions,
+  OutputOptions,
+} from './types';
+import { DomainAwareScanner } from './domain-scanner';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Per-domain compilation backend.
+ * Provides everything needed to scan, parse, and compile a domain's syntax.
+ */
+export interface DomainCompilationBackend {
+  /** Domain name (must match scanConfig.domain) */
+  readonly domain: string;
+  /** The DSL instance for parsing and compilation */
+  readonly dsl: MultilingualDSL;
+  /** Code generator for producing target code from semantic nodes */
+  readonly codeGenerator: CodeGenerator;
+  /** Scan configuration declaring HTML attribute patterns */
+  readonly scanConfig: DomainScanConfig;
+}
+
+// =============================================================================
+// AOTOrchestrator
+// =============================================================================
+
+/**
+ * Generalized AOT orchestrator for any domain.
+ */
+export class AOTOrchestrator {
+  private backends = new Map<string, DomainCompilationBackend>();
+  private options: Required<GeneralizedAOTOptions>;
+
+  constructor(options?: GeneralizedAOTOptions) {
+    this.options = {
+      confidenceThreshold: options?.confidenceThreshold ?? 0.7,
+      continueOnError: options?.continueOnError ?? true,
+      debug: options?.debug ?? false,
+    };
+  }
+
+  /**
+   * Register a domain compilation backend.
+   * @throws if a backend with the same domain name is already registered
+   */
+  registerBackend(backend: DomainCompilationBackend): void {
+    if (this.backends.has(backend.domain)) {
+      throw new Error(`Backend already registered for domain: ${backend.domain}`);
+    }
+    this.backends.set(backend.domain, backend);
+  }
+
+  /**
+   * Scan source files and compile all domain snippets.
+   */
+  async compileFiles(
+    files: string[],
+    readFile: (path: string) => Promise<string>
+  ): Promise<AOTBatchResult> {
+    // Build scanner from all backends' scan configs
+    const configs = Array.from(this.backends.values()).map(b => b.scanConfig);
+    const scanner = new DomainAwareScanner(configs);
+
+    // Extract all snippets
+    const snippets = await scanner.extractFromFiles(files, readFile);
+
+    if (this.options.debug) {
+      console.log(`[aot] Extracted ${snippets.length} snippets from ${files.length} files`);
+    }
+
+    // Compile each snippet
+    const compiled: CompiledSnippet[] = [];
+    const errors: AOTBatchResult['errors'][number][] = [];
+    const domainBreakdown: Record<string, number> = {};
+
+    for (const snippet of snippets) {
+      domainBreakdown[snippet.domain] = (domainBreakdown[snippet.domain] ?? 0) + 1;
+
+      const result = this.compileSnippet(snippet);
+      if ('error' in result) {
+        errors.push({
+          domain: snippet.domain,
+          source: snippet.code,
+          file: snippet.file,
+          line: snippet.line,
+          message: result.error,
+        });
+        if (!this.options.continueOnError) break;
+      } else {
+        compiled.push(result);
+      }
+    }
+
+    return {
+      compiled,
+      errors,
+      stats: {
+        totalSnippets: snippets.length,
+        compiledCount: compiled.length,
+        errorCount: errors.length,
+        domainBreakdown,
+      },
+    };
+  }
+
+  /**
+   * Compile a single extracted snippet.
+   * Returns the compiled result or an error object.
+   */
+  compileSnippet(snippet: ExtractedSnippet): CompiledSnippet | { error: string } {
+    const backend = this.backends.get(snippet.domain);
+    if (!backend) {
+      return { error: `No backend registered for domain: ${snippet.domain}` };
+    }
+
+    try {
+      const result = backend.dsl.compile(snippet.code, snippet.language);
+      if (!result.ok || !result.code) {
+        return { error: result.errors?.join('; ') ?? 'Compilation failed' };
+      }
+
+      return {
+        domain: snippet.domain,
+        source: snippet.code,
+        compiled: result.code,
+        language: snippet.language,
+        file: snippet.file,
+        line: snippet.line,
+      };
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  /**
+   * Generate combined output from compilation results.
+   */
+  generateOutput(result: AOTBatchResult, options?: OutputOptions): string {
+    const format = options?.format ?? 'esm';
+    const includeComments = options?.includeComments ?? true;
+    const groupByDomain = options?.groupByDomain ?? true;
+
+    const sections: string[] = [];
+
+    if (includeComments) {
+      sections.push(`// Generated by @lokascript/framework AOT compiler`);
+      sections.push(
+        `// ${result.stats.compiledCount} snippets compiled, ${result.stats.errorCount} errors`
+      );
+      sections.push('');
+    }
+
+    if (groupByDomain) {
+      // Group by domain
+      const grouped = new Map<string, CompiledSnippet[]>();
+      for (const snippet of result.compiled) {
+        const list = grouped.get(snippet.domain) ?? [];
+        list.push(snippet);
+        grouped.set(snippet.domain, list);
+      }
+
+      for (const [domain, snippets] of grouped) {
+        if (includeComments) {
+          sections.push(`// === Domain: ${domain} ===`);
+          sections.push('');
+        }
+
+        for (const snippet of snippets) {
+          if (includeComments) {
+            sections.push(`// Source: ${snippet.file}:${snippet.line}`);
+            sections.push(`// Language: ${snippet.language}`);
+          }
+          sections.push(snippet.compiled);
+          sections.push('');
+        }
+      }
+    } else {
+      for (const snippet of result.compiled) {
+        if (includeComments) {
+          sections.push(`// [${snippet.domain}] ${snippet.file}:${snippet.line}`);
+        }
+        sections.push(snippet.compiled);
+        sections.push('');
+      }
+    }
+
+    const body = sections.join('\n').trimEnd();
+
+    switch (format) {
+      case 'cjs':
+        return `'use strict';\n\n${body}\n`;
+      case 'iife':
+        return `(function() {\n${body}\n})();\n`;
+      case 'esm':
+      default:
+        return `${body}\n`;
+    }
+  }
+}

package/src/aot/domain-scanner.ts

@@ -0,0 +1,178 @@
+/**
+ * Domain-Aware Scanner
+ *
+ * Extracts DSL snippets from HTML/template files based on domain-declared
+ * attribute patterns and script types. Unlike the hyperscript-specific
+ * HTMLScanner, this scanner is configured dynamically from DomainScanConfig.
+ */
+
+import type { DomainScanConfig, ExtractedSnippet } from './types';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Build regex patterns for extracting attribute values.
+ * Handles double-quoted, single-quoted, and backtick-quoted values.
+ */
+function buildAttributePatterns(attributes: readonly string[]): RegExp[] {
+  const patterns: RegExp[] = [];
+  for (const attr of attributes) {
+    const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Match: attr="value", attr='value', attr=`value`
+    patterns.push(new RegExp(`${escaped}\\s*=\\s*"([^"]+)"`, 'g'));
+    patterns.push(new RegExp(`${escaped}\\s*=\\s*'([^']+)'`, 'g'));
+    patterns.push(new RegExp(`${escaped}\\s*=\\s*\`([^\`]+)\``, 'g'));
+  }
+  return patterns;
+}
+
+/**
+ * Build regex patterns for extracting script tag contents.
+ */
+function buildScriptPatterns(scriptTypes: readonly string[]): RegExp[] {
+  return scriptTypes.map(type => {
+    const escaped = type.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`<script[^>]*type=["']?${escaped}["']?[^>]*>([\\s\\S]*?)<\\/script>`, 'gi');
+  });
+}
+
+/**
+ * Count newlines before a position to determine line number.
+ */
+function getLineNumber(source: string, position: number): number {
+  let line = 1;
+  for (let i = 0; i < position && i < source.length; i++) {
+    if (source[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Try to extract an element ID near the matched attribute.
+ * Looks backward in the source for an id="..." on the same element.
+ */
+function extractElementId(source: string, matchIndex: number): string | undefined {
+  // Find the opening < before this attribute
+  const before = source.lastIndexOf('<', matchIndex);
+  if (before === -1) return undefined;
+
+  const tagChunk = source.slice(before, matchIndex + 200);
+  const idMatch = tagChunk.match(/\bid=["']([^"']+)["']/);
+  return idMatch?.[1];
+}
+
+/**
+ * Try to extract a lang attribute from the element.
+ */
+function extractLangAttribute(source: string, matchIndex: number): string | undefined {
+  const before = source.lastIndexOf('<', matchIndex);
+  if (before === -1) return undefined;
+
+  const tagChunk = source.slice(before, matchIndex + 200);
+  const langMatch = tagChunk.match(/\blang=["']([^"']+)["']/);
+  return langMatch?.[1];
+}
+
+// =============================================================================
+// DomainAwareScanner
+// =============================================================================
+
+/**
+ * Scans HTML/template files for domain-specific snippets.
+ *
+ * Configured by DomainScanConfig objects, each declaring which
+ * HTML attributes and script types a domain uses.
+ */
+export class DomainAwareScanner {
+  private configs: readonly DomainScanConfig[];
+
+  constructor(configs: readonly DomainScanConfig[]) {
+    this.configs = configs;
+  }
+
+  /**
+   * Extract all domain snippets from an HTML source string.
+   */
+  extract(source: string, filename: string): ExtractedSnippet[] {
+    const snippets: ExtractedSnippet[] = [];
+
+    for (const config of this.configs) {
+      const defaultLang = config.defaultLanguage ?? 'en';
+
+      // Extract from attributes
+      const attrPatterns = buildAttributePatterns(config.attributes);
+      for (const pattern of attrPatterns) {
+        pattern.lastIndex = 0;
+        let match: RegExpExecArray | null;
+        while ((match = pattern.exec(source))) {
+          const code = match[1].trim();
+          if (!code) continue;
+
+          const line = getLineNumber(source, match.index);
+          const elementId = extractElementId(source, match.index);
+          const langAttr = extractLangAttribute(source, match.index);
+
+          snippets.push({
+            domain: config.domain,
+            code,
+            language: langAttr ?? defaultLang,
+            file: filename,
+            line,
+            column: 1,
+            ...(elementId != null && { elementId }),
+          });
+        }
+      }
+
+      // Extract from script tags
+      if (config.scriptTypes) {
+        const scriptPatterns = buildScriptPatterns(config.scriptTypes);
+        for (const pattern of scriptPatterns) {
+          pattern.lastIndex = 0;
+          let match: RegExpExecArray | null;
+          while ((match = pattern.exec(source))) {
+            const code = match[1].trim();
+            if (!code) continue;
+
+            const line = getLineNumber(source, match.index);
+
+            snippets.push({
+              domain: config.domain,
+              code,
+              language: defaultLang,
+              file: filename,
+              line,
+              column: 1,
+            });
+          }
+        }
+      }
+    }
+
+    return snippets;
+  }
+
+  /**
+   * Extract snippets from multiple files.
+   */
+  async extractFromFiles(
+    files: string[],
+    readFile: (path: string) => Promise<string>
+  ): Promise<ExtractedSnippet[]> {
+    const allSnippets: ExtractedSnippet[] = [];
+
+    for (const file of files) {
+      try {
+        const source = await readFile(file);
+        const snippets = this.extract(source, file);
+        allSnippets.push(...snippets);
+      } catch {
+        // Skip files that can't be read
+      }
+    }
+
+    return allSnippets;
+  }
+}

package/src/aot/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Generalized AOT compilation for any domain.
+ */
+
+export * from './types';
+export { DomainAwareScanner } from './domain-scanner';
+export { AOTOrchestrator } from './aot-orchestrator';
+export type { DomainCompilationBackend } from './aot-orchestrator';

package/src/aot/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Generalized AOT Type Definitions
+ *
+ * Types for the domain-agnostic Ahead-of-Time compilation system.
+ * Any domain that provides a MultilingualDSL and CodeGenerator can use this.
+ */
+
+// =============================================================================
+// Scan Configuration
+// =============================================================================
+
+/**
+ * How a domain declares its HTML attribute patterns for scanning.
+ */
+export interface DomainScanConfig {
+  /** Domain name (should match DomainDescriptor.name) */
+  readonly domain: string;
+  /** Attribute names to scan for (e.g., ['data-sql', '_sql']) */
+  readonly attributes: readonly string[];
+  /** Script tag types to scan for (e.g., ['text/sql-dsl']) */
+  readonly scriptTypes?: readonly string[];
+  /** Default language when not specified on element (default: 'en') */
+  readonly defaultLanguage?: string;
+}
+
+// =============================================================================
+// Extraction Results
+// =============================================================================
+
+/**
+ * A snippet extracted from a source file, tagged with its domain.
+ */
+export interface ExtractedSnippet {
+  /** Domain this snippet belongs to */
+  readonly domain: string;
+  /** The DSL code */
+  readonly code: string;
+  /** Language code (from element's lang attribute or default) */
+  readonly language: string;
+  /** Source file path */
+  readonly file: string;
+  /** Line number in source file (1-based) */
+  readonly line: number;
+  /** Column number in source file (1-based) */
+  readonly column: number;
+  /** Element ID if available */
+  readonly elementId?: string;
+  /** CSS selector for the element */
+  readonly elementSelector?: string;
+}
+
+// =============================================================================
+// Compilation Results
+// =============================================================================
+
+/**
+ * Result of compiling a single snippet.
+ */
+export interface CompiledSnippet {
+  /** Domain that compiled this snippet */
+  readonly domain: string;
+  /** Original source code */
+  readonly source: string;
+  /** Compiled output */
+  readonly compiled: string;
+  /** Source language */
+  readonly language: string;
+  /** Source file path */
+  readonly file: string;
+  /** Line number in source file */
+  readonly line: number;
+}
+
+/**
+ * Result of batch-compiling all snippets from a project.
+ */
+export interface AOTBatchResult {
+  /** Successfully compiled snippets */
+  readonly compiled: readonly CompiledSnippet[];
+  /** Snippets that failed compilation */
+  readonly errors: ReadonlyArray<{
+    readonly domain: string;
+    readonly source: string;
+    readonly file: string;
+    readonly line: number;
+    readonly message: string;
+  }>;
+  /** Summary statistics */
+  readonly stats: {
+    readonly totalSnippets: number;
+    readonly compiledCount: number;
+    readonly errorCount: number;
+    /** Number of snippets per domain */
+    readonly domainBreakdown: Record<string, number>;
+  };
+}
+
+// =============================================================================
+// Options
+// =============================================================================
+
+/**
+ * Options for the generalized AOT compiler.
+ */
+export interface GeneralizedAOTOptions {
+  /** Minimum confidence for semantic parsing (default: 0.7) */
+  readonly confidenceThreshold?: number;
+  /** Continue compiling other snippets on individual errors (default: true) */
+  readonly continueOnError?: boolean;
+  /** Debug mode — log extraction and compilation details */
+  readonly debug?: boolean;
+}
+
+/**
+ * Options for generating combined output.
+ */
+export interface OutputOptions {
+  /** Module format (default: 'esm') */
+  readonly format?: 'esm' | 'cjs' | 'iife';
+  /** Include source location comments (default: true) */
+  readonly includeComments?: boolean;
+  /** Group output by domain (default: true) */
+  readonly groupByDomain?: boolean;
+}