@lokascript/compilation-service 2.0.0

package/dist/service-891L1MYk.d.ts

@@ -0,0 +1,595 @@
+/**
+ * Abstract Operation Types
+ *
+ * The core abstraction layer between semantic roles and output format.
+ * Each operation describes a single DOM/state change without prescribing
+ * how to emit it — the same operations power test generation (Phase 2)
+ * and cross-framework codegen (Phase 3).
+ */
+/** A reference to the target of an operation */
+type TargetRef = {
+    kind: 'self';
+} | {
+    kind: 'selector';
+    value: string;
+} | {
+    kind: 'variable';
+    value: string;
+};
+interface ToggleClassOp {
+    op: 'toggleClass';
+    className: string;
+    target: TargetRef;
+}
+interface AddClassOp {
+    op: 'addClass';
+    className: string;
+    target: TargetRef;
+}
+interface RemoveClassOp {
+    op: 'removeClass';
+    className: string;
+    target: TargetRef;
+}
+interface SetContentOp {
+    op: 'setContent';
+    content: string;
+    target: TargetRef;
+    position: 'into' | 'before' | 'after' | 'start' | 'end';
+}
+interface AppendContentOp {
+    op: 'appendContent';
+    content: string;
+    target: TargetRef;
+}
+interface ShowOp {
+    op: 'show';
+    target: TargetRef;
+}
+interface HideOp {
+    op: 'hide';
+    target: TargetRef;
+}
+interface SetVariableOp {
+    op: 'setVariable';
+    name: string;
+    value: string;
+    scope: 'local' | 'element' | 'global';
+}
+interface IncrementOp {
+    op: 'increment';
+    target: TargetRef;
+    amount: number;
+}
+interface DecrementOp {
+    op: 'decrement';
+    target: TargetRef;
+    amount: number;
+}
+interface NavigateOp {
+    op: 'navigate';
+    url: string;
+}
+interface HistoryBackOp {
+    op: 'historyBack';
+}
+interface HistoryForwardOp {
+    op: 'historyForward';
+}
+interface FetchOp {
+    op: 'fetch';
+    url: string;
+    format: 'json' | 'text' | 'html';
+    target?: TargetRef;
+}
+interface WaitOp {
+    op: 'wait';
+    durationMs: number;
+}
+interface TriggerEventOp {
+    op: 'triggerEvent';
+    eventName: string;
+    target: TargetRef;
+    detail?: string;
+}
+interface FocusOp {
+    op: 'focus';
+    target: TargetRef;
+}
+interface BlurOp {
+    op: 'blur';
+    target: TargetRef;
+}
+interface LogOp {
+    op: 'log';
+    values: string[];
+}
+/** Union of all abstract operations */
+type AbstractOperation = ToggleClassOp | AddClassOp | RemoveClassOp | SetContentOp | AppendContentOp | ShowOp | HideOp | SetVariableOp | IncrementOp | DecrementOp | NavigateOp | HistoryBackOp | HistoryForwardOp | FetchOp | WaitOp | TriggerEventOp | FocusOp | BlurOp | LogOp;
+/**
+ * A complete behavior specification: what triggers it and what it does.
+ * Extracted from a semantic event handler node.
+ */
+interface BehaviorSpec {
+    /** The triggering event */
+    trigger: {
+        event: string;
+        modifiers?: Record<string, unknown>;
+    };
+    /** The element that listens for the trigger */
+    triggerTarget: TargetRef;
+    /** The operations performed when triggered */
+    operations: AbstractOperation[];
+    /** Whether any operation is async */
+    async: boolean;
+    /** Original hyperscript source (for test naming) */
+    source?: string;
+}
+
+/**
+ * Component Renderer Types
+ *
+ * Interface for pluggable component renderers. Each renderer takes a BehaviorSpec
+ * and produces a complete framework-specific component file.
+ * Parallel to TestRenderer (test generation) — this is for code generation.
+ */
+
+/**
+ * A component renderer converts a BehaviorSpec into framework-specific component code.
+ */
+interface ComponentRenderer {
+    /** The framework this renderer targets */
+    readonly framework: string;
+    /** Render a behavior spec into a complete component */
+    render(spec: BehaviorSpec, options?: ComponentRenderOptions): GeneratedComponent;
+}
+interface ComponentRenderOptions {
+    /** Override auto-generated component name */
+    componentName?: string;
+    /** TypeScript output (default true) */
+    typescript?: boolean;
+}
+/**
+ * A generated component file.
+ */
+interface GeneratedComponent {
+    /** Component name (e.g., "ToggleActiveButton") */
+    name: string;
+    /** Full component file content */
+    code: string;
+    /** Target framework */
+    framework: string;
+    /** Abstract operations for introspection */
+    operations: AbstractOperation[];
+    /** Framework-specific reactive primitives (React hooks, Vue composables, Svelte runes) */
+    hooks: string[];
+}
+
+/**
+ * Test Renderer Types
+ *
+ * Interface for pluggable test renderers. Each renderer takes a BehaviorSpec
+ * and produces a complete test file in a specific framework format.
+ */
+
+/**
+ * A test renderer converts a BehaviorSpec into a framework-specific test file.
+ */
+interface TestRenderer {
+    /** The framework this renderer targets */
+    readonly framework: string;
+    /** Render a behavior spec into a complete test */
+    render(spec: BehaviorSpec, options: TestRenderOptions): GeneratedTest;
+}
+interface TestRenderOptions {
+    /** Override auto-generated test name */
+    testName?: string;
+    /** How to load the hyperscript behavior in the test */
+    executionMode?: 'runtime' | 'compiled';
+    /** Path to LokaScript bundle (runtime mode) */
+    bundlePath?: string;
+    /** Original hyperscript source (for embedding in fixture) */
+    hyperscript?: string;
+    /** Compiled JS code (for compiled mode) */
+    compiledJs?: string;
+}
+/**
+ * A generated test file.
+ */
+interface GeneratedTest {
+    /** Test name (e.g., "on click toggle .active on #btn") */
+    name: string;
+    /** Full test file content */
+    code: string;
+    /** HTML fixture embedded in the test */
+    html: string;
+    /** Target framework */
+    framework: string;
+    /** Abstract operations for introspection */
+    operations: AbstractOperation[];
+}
+
+/**
+ * Semantic Diff Types
+ *
+ * Types for comparing two hyperscript behaviors at the abstract operation level.
+ */
+
+/** One side of a diff comparison — accepts any input format */
+interface DiffInput {
+    /** Natural language hyperscript (requires `language`) */
+    code?: string;
+    /** Explicit syntax: [command role:value ...] */
+    explicit?: string;
+    /** LLM JSON — structured semantic representation */
+    semantic?: SemanticJSON;
+    /** ISO 639-1 language code (required for `code`) */
+    language?: string;
+}
+/** Diff request — compare two hyperscript inputs */
+interface DiffRequest {
+    a: DiffInput;
+    b: DiffInput;
+    /** Minimum confidence for natural language parsing (default 0.7) */
+    confidence?: number;
+}
+/** Diff response — structured comparison result */
+interface DiffResponse {
+    /** Whether both sides parsed successfully */
+    ok: boolean;
+    /** Whether the two behaviors are semantically identical */
+    identical: boolean;
+    /** Trigger comparison (null when triggers match) */
+    trigger: TriggerDiff | null;
+    /** Per-operation comparison */
+    operations: OperationDiff[];
+    /** Human-readable summary */
+    summary: string;
+    /** Diagnostics from parsing both sides */
+    diagnostics: Diagnostic[];
+}
+/** Trigger difference */
+interface TriggerDiff {
+    a: {
+        event: string;
+        modifiers?: Record<string, unknown>;
+    };
+    b: {
+        event: string;
+        modifiers?: Record<string, unknown>;
+    };
+    changes: string[];
+}
+/** Kind of operation change */
+type OperationChangeKind = 'added' | 'removed' | 'changed' | 'reordered' | 'unchanged';
+/** A single operation difference */
+interface OperationDiff {
+    kind: OperationChangeKind;
+    index: {
+        a?: number;
+        b?: number;
+    };
+    a?: AbstractOperation;
+    b?: AbstractOperation;
+    changes?: string[];
+}
+
+/**
+ * Types for the Compilation Service.
+ *
+ * Three input formats converge to a single compilation pipeline:
+ * - Natural language hyperscript (24 languages)
+ * - Explicit syntax: [toggle patient:.active destination:#btn]
+ * - LLM JSON: { action: "toggle", roles: { patient: { type: "selector", value: ".active" } } }
+ */
+/**
+ * Compilation request — provide exactly one of: code, explicit, or semantic.
+ */
+interface CompileRequest {
+    /** Natural language hyperscript (requires `language`) */
+    code?: string;
+    /** Explicit syntax: [command role:value ...] */
+    explicit?: string;
+    /** LLM JSON — structured semantic representation */
+    semantic?: SemanticJSON;
+    /** ISO 639-1 language code (required for `code`, ignored for `explicit`/`semantic`) */
+    language?: string;
+    /** Minimum confidence for natural language parsing (default 0.7) */
+    confidence?: number;
+    /** Optimization level: 0=none, 1=basic, 2=full (default 2) */
+    optimization?: 0 | 1 | 2;
+    /** Output module format (default 'esm') */
+    target?: 'esm' | 'iife';
+    /** Minify output (default false) */
+    minify?: boolean;
+}
+/**
+ * Translation request.
+ */
+interface TranslateRequest {
+    /** Source code or explicit syntax */
+    code: string;
+    /** Source language */
+    from: string;
+    /** Target language */
+    to: string;
+}
+/**
+ * Structured semantic representation for LLM output.
+ * This is the "reliable input format" — no parsing ambiguity.
+ */
+interface SemanticJSON {
+    /** Command name (e.g., "toggle", "add", "set", "put") */
+    action: string;
+    /** Semantic roles mapping */
+    roles: Record<string, SemanticJSONValue>;
+    /** Event trigger (for event handlers) */
+    trigger?: {
+        event: string;
+        modifiers?: Record<string, unknown>;
+    };
+}
+/**
+ * A typed value in a semantic role.
+ */
+interface SemanticJSONValue {
+    /** Value type */
+    type: 'selector' | 'literal' | 'reference' | 'expression' | 'property-path';
+    /** The value */
+    value: string | number | boolean;
+}
+/**
+ * Compilation response.
+ */
+interface CompileResponse {
+    /** Whether compilation succeeded */
+    ok: boolean;
+    /** Compiled JavaScript (on success) */
+    js?: string;
+    /** Runtime helpers needed by the compiled code */
+    helpers?: string[];
+    /** Output size in bytes */
+    size?: number;
+    /** Normalized semantic representation (always present on success) */
+    semantic?: SemanticJSON;
+    /** Parse confidence (natural language input only) */
+    confidence?: number;
+    /** Errors, warnings, and info messages */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Validation-only response (no compilation).
+ */
+interface ValidationResponse {
+    /** Whether validation passed */
+    ok: boolean;
+    /** Normalized semantic representation (if parse succeeded) */
+    semantic?: SemanticJSON;
+    /** Parse confidence */
+    confidence?: number;
+    /** Diagnostics */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Translation response.
+ */
+interface TranslateResponse {
+    /** Whether translation succeeded */
+    ok: boolean;
+    /** Translated code */
+    code?: string;
+    /** Diagnostics */
+    diagnostics: Diagnostic[];
+}
+/**
+ * A diagnostic message (error, warning, or info).
+ */
+interface Diagnostic {
+    /** Severity level */
+    severity: 'error' | 'warning' | 'info';
+    /** Machine-readable code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Suggested fix */
+    suggestion?: string;
+}
+/**
+ * Test generation request.
+ */
+interface TestRequest {
+    /** Natural language hyperscript (requires `language`) */
+    code?: string;
+    /** Explicit syntax: [command role:value ...] */
+    explicit?: string;
+    /** LLM JSON — structured semantic representation */
+    semantic?: SemanticJSON;
+    /** ISO 639-1 language code (required for `code`, ignored for `explicit`/`semantic`) */
+    language?: string;
+    /** Minimum confidence for natural language parsing (default 0.7) */
+    confidence?: number;
+    /** Test framework to target (default 'playwright') */
+    framework?: string;
+    /** How to load hyperscript in the test (default 'runtime') */
+    executionMode?: 'runtime' | 'compiled';
+    /** Override auto-generated test name */
+    testName?: string;
+    /** Path to LokaScript bundle (runtime mode) */
+    bundlePath?: string;
+}
+/**
+ * Test generation response.
+ */
+interface TestResponse {
+    /** Whether test generation succeeded */
+    ok: boolean;
+    /** Generated test files */
+    tests: GeneratedTestOutput[];
+    /** Raw abstract operations (for introspection) */
+    operations: AbstractOperation[];
+    /** Normalized semantic representation */
+    semantic?: SemanticJSON;
+    /** Diagnostics */
+    diagnostics: Diagnostic[];
+}
+/**
+ * A single generated test output.
+ */
+interface GeneratedTestOutput {
+    /** Test name */
+    name: string;
+    /** Full test file content */
+    code: string;
+    /** HTML fixture */
+    html: string;
+    /** Target framework */
+    framework: string;
+}
+/**
+ * Component generation request.
+ */
+interface ComponentRequest {
+    /** Natural language hyperscript (requires `language`) */
+    code?: string;
+    /** Explicit syntax: [command role:value ...] */
+    explicit?: string;
+    /** LLM JSON — structured semantic representation */
+    semantic?: SemanticJSON;
+    /** ISO 639-1 language code (required for `code`) */
+    language?: string;
+    /** Minimum confidence for natural language parsing (default 0.7) */
+    confidence?: number;
+    /** Target framework (default 'react') */
+    framework?: string;
+    /** Override auto-generated component name */
+    componentName?: string;
+    /** TypeScript output (default true) */
+    typescript?: boolean;
+}
+/**
+ * Component generation response.
+ */
+interface ComponentResponse {
+    /** Whether generation succeeded */
+    ok: boolean;
+    /** Generated component */
+    component?: {
+        /** Component name */
+        name: string;
+        /** Full component file content */
+        code: string;
+        /** Framework-specific reactive primitives (React hooks, Vue composables, Svelte runes) */
+        hooks: string[];
+        /** Target framework */
+        framework: string;
+    };
+    /** Raw abstract operations (for introspection) */
+    operations: AbstractOperation[];
+    /** Normalized semantic representation */
+    semantic?: SemanticJSON;
+    /** Diagnostics */
+    diagnostics: Diagnostic[];
+}
+
+/**
+ * Options for creating a CompilationService.
+ */
+interface ServiceOptions {
+    /** Default confidence threshold (default 0.7) */
+    confidenceThreshold?: number;
+    /** Maximum cache entries (default 500, 0 to disable) */
+    cacheSize?: number;
+    /** Custom test renderers keyed by framework name (default: { playwright: PlaywrightRenderer }) */
+    testRenderers?: Record<string, TestRenderer>;
+    /** Custom component renderers keyed by framework name (default: { react: ReactRenderer }) */
+    componentRenderers?: Record<string, ComponentRenderer>;
+}
+/** Detected input format */
+type InputFormat = 'natural' | 'explicit' | 'json';
+
+/**
+ * CompilationService — the main orchestrator.
+ *
+ * Accepts hyperscript in three formats (natural language, explicit syntax, LLM JSON),
+ * validates through semantic schemas, and compiles to optimized JavaScript.
+ */
+
+declare class CompilationService {
+    private cache;
+    private confidenceThreshold;
+    private translateFn;
+    private testRenderers;
+    private componentRenderers;
+    private constructor();
+    /**
+     * Register a test renderer for a given framework.
+     */
+    registerTestRenderer(framework: string, renderer: TestRenderer): void;
+    /**
+     * Register a component renderer for a given framework.
+     */
+    registerComponentRenderer(framework: string, renderer: ComponentRenderer): void;
+    /**
+     * Create a CompilationService by dynamically importing dependencies.
+     *
+     * This async factory resolves @lokascript/semantic and @hyperfixi/aot-compiler
+     * at runtime, following the same pattern as createMultilingualCompiler().
+     */
+    static create(options?: ServiceOptions): Promise<CompilationService>;
+    /**
+     * Compile hyperscript to JavaScript.
+     *
+     * Accepts any of three input formats:
+     * - `code` + `language`: Natural language hyperscript
+     * - `explicit`: Bracket syntax [command role:value ...]
+     * - `semantic`: LLM JSON { action, roles, trigger }
+     *
+     * Returns compiled JS, semantic representation, and diagnostics.
+     */
+    compile(request: CompileRequest): CompileResponse;
+    /**
+     * Validate input without compiling.
+     * Returns semantic representation and diagnostics.
+     */
+    validate(request: CompileRequest): ValidationResponse;
+    /**
+     * Translate hyperscript between languages.
+     */
+    translate(request: TranslateRequest): TranslateResponse;
+    /**
+     * Generate behavior-level tests from hyperscript.
+     *
+     * Parses the input, extracts abstract operations (what the behavior does),
+     * and renders them as test code in the requested framework.
+     */
+    generateTests(request: TestRequest): TestResponse;
+    /**
+     * Generate a framework component from hyperscript.
+     *
+     * Parses the input, extracts abstract operations, and renders
+     * them as a framework-specific component (React, Vue, or Svelte).
+     */
+    generateComponent(request: ComponentRequest): ComponentResponse;
+    /**
+     * Compare two hyperscript inputs at the behavior level.
+     *
+     * Both sides are independently normalized and validated, then compared
+     * as abstract operations. Same behavior in different languages → identical.
+     */
+    diff(request: DiffRequest): DiffResponse;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * Clear the compilation cache.
+     */
+    clearCache(): void;
+}
+
+export { type AbstractOperation as A, type BehaviorSpec as B, CompilationService as C, type Diagnostic as D, type SetVariableOp as E, type IncrementOp as F, type GeneratedTest as G, type HideOp as H, type InputFormat as I, type DecrementOp as J, type FetchOp as K, type TriggerEventOp as L, type FocusOp as M, type NavigateOp as N, type OperationDiff as O, type BlurOp as P, type LogOp as Q, type RemoveClassOp as R, type SemanticJSON as S, type TriggerDiff as T, type ValidationResponse as V, type WaitOp as W, type CompileResponse as a, type TestRenderer as b, type TestRenderOptions as c, type ComponentRenderer as d, type ComponentRenderOptions as e, type GeneratedComponent as f, type CompileRequest as g, type TranslateRequest as h, type TranslateResponse as i, type TestRequest as j, type TestResponse as k, type GeneratedTestOutput as l, type ComponentRequest as m, type ComponentResponse as n, type DiffRequest as o, type DiffResponse as p, type DiffInput as q, type OperationChangeKind as r, type ServiceOptions as s, type SemanticJSONValue as t, type TargetRef as u, type ToggleClassOp as v, type AddClassOp as w, type SetContentOp as x, type AppendContentOp as y, type ShowOp as z };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@lokascript/compilation-service",
+  "version": "2.0.0",
+  "description": "Semantic compilation service for LokaScript - validates and compiles hyperscript from 24 languages, explicit syntax, or LLM JSON",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js",
+      "require": "./dist/http.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "pretest": "../../scripts/ensure-fresh.sh ../semantic ../aot-compiler",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "serve": "tsx src/serve.ts",
+    "test:check": "vitest run --reporter=dot 2>&1 | tail -5",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "hono": "^4.11.7"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@hyperfixi/aot-compiler": "*",
+    "@lokascript/semantic": "*",
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "peerDependencies": {
+    "@lokascript/semantic": "*"
+  },
+  "peerDependenciesMeta": {
+    "@lokascript/semantic": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "hyperscript",
+    "lokascript",
+    "compilation",
+    "semantic",
+    "multilingual",
+    "llm",
+    "http",
+    "edge",
+    "react"
+  ],
+  "author": "LokaScript Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codetalcott/hyperfixi.git",
+    "directory": "packages/compilation-service"
+  }
+}