@kernlang/core 3.1.2 → 3.1.4

package/dist/runtime.d.ts

@@ -0,0 +1,57 @@
+/**
+ * KernRuntime — instance-based state for KERN's parser, codegen, and template engine.
+ *
+ * Centralizes 6 module-level global registries into a single owning instance.
+ * All public APIs (parse, parseDocument, generateCoreNode, isTemplateNode,
+ * expandTemplateNode, isKnownNodeType) accept an optional `runtime` parameter
+ * for true instance isolation (LSP, serverless, worker threads, parallel tests).
+ *
+ * Usage:
+ *   const runtime = new KernRuntime();
+ *   runtime.registerEvolvedType('custom');
+ *   runtime.registerParserHints('custom', { positionalArgs: ['name'] });
+ *   runtime.registerEvolvedGenerator('custom', node => [...]);
+ *
+ * A `defaultRuntime` singleton is provided for backward compatibility.
+ * All existing module-level functions (registerEvolvedType, clearParserHints, etc.)
+ * delegate to `defaultRuntime` so existing code continues to work unchanged.
+ */
+import type { IRNode, ParseDiagnostic, TemplateDefinition } from './types.js';
+export interface ParserHintsConfig {
+    positionalArgs?: string[];
+    bareWord?: string;
+    multilineBlock?: string;
+}
+export declare class KernRuntime {
+    readonly parserHints: Map<string, ParserHintsConfig>;
+    readonly multilineBlockTypes: Set<string>;
+    lastParseDiagnostics: ParseDiagnostic[];
+    readonly dynamicNodeTypes: Set<string>;
+    readonly evolvedGenerators: Map<string, (node: IRNode) => string[]>;
+    readonly evolvedTargetGenerators: Map<string, Map<string, (node: IRNode) => string[]>>;
+    readonly templateRegistry: Map<string, TemplateDefinition>;
+    registerParserHints(keyword: string, hints: ParserHintsConfig): void;
+    unregisterParserHints(keyword: string): void;
+    clearParserHints(): void;
+    registerEvolvedType(keyword: string): void;
+    unregisterEvolvedType(keyword: string): void;
+    getEvolvedTypes(): ReadonlySet<string>;
+    clearEvolvedTypes(): void;
+    registerEvolvedGenerator(keyword: string, fn: (node: IRNode) => string[]): void;
+    registerEvolvedTargetGenerator(keyword: string, target: string, fn: (node: IRNode) => string[]): void;
+    unregisterEvolvedGenerator(keyword: string): void;
+    hasEvolvedGenerator(keyword: string): boolean;
+    clearEvolvedGenerators(): void;
+    registerTemplate(name: string, def: TemplateDefinition): void;
+    isTemplateNode(type: string): boolean;
+    getTemplate(name: string): TemplateDefinition | undefined;
+    templateCount(): number;
+    clearTemplates(): void;
+    /** Reset all runtime state. Useful for test isolation. */
+    reset(): void;
+}
+/**
+ * Default runtime singleton. All existing module-level registration functions
+ * delegate to this instance for backward compatibility.
+ */
+export declare const defaultRuntime: KernRuntime;

package/dist/runtime.js

@@ -0,0 +1,121 @@
+/**
+ * KernRuntime — instance-based state for KERN's parser, codegen, and template engine.
+ *
+ * Centralizes 6 module-level global registries into a single owning instance.
+ * All public APIs (parse, parseDocument, generateCoreNode, isTemplateNode,
+ * expandTemplateNode, isKnownNodeType) accept an optional `runtime` parameter
+ * for true instance isolation (LSP, serverless, worker threads, parallel tests).
+ *
+ * Usage:
+ *   const runtime = new KernRuntime();
+ *   runtime.registerEvolvedType('custom');
+ *   runtime.registerParserHints('custom', { positionalArgs: ['name'] });
+ *   runtime.registerEvolvedGenerator('custom', node => [...]);
+ *
+ * A `defaultRuntime` singleton is provided for backward compatibility.
+ * All existing module-level functions (registerEvolvedType, clearParserHints, etc.)
+ * delegate to `defaultRuntime` so existing code continues to work unchanged.
+ */
+// ── KernRuntime ──────────────────────────────────────────────────────────
+export class KernRuntime {
+    // Parser state
+    parserHints = new Map();
+    multilineBlockTypes = new Set(['logic', 'handler', 'cleanup', 'body']);
+    lastParseDiagnostics = [];
+    // Spec state
+    dynamicNodeTypes = new Set();
+    // Codegen state
+    evolvedGenerators = new Map();
+    evolvedTargetGenerators = new Map();
+    // Template state
+    templateRegistry = new Map();
+    // ── Parser Hints ─────────────────────────────────────────────────────
+    registerParserHints(keyword, hints) {
+        this.parserHints.set(keyword, hints);
+        if (hints.multilineBlock) {
+            this.multilineBlockTypes.add(keyword);
+        }
+    }
+    unregisterParserHints(keyword) {
+        const hints = this.parserHints.get(keyword);
+        if (hints?.multilineBlock) {
+            this.multilineBlockTypes.delete(keyword);
+        }
+        this.parserHints.delete(keyword);
+    }
+    clearParserHints() {
+        for (const [keyword, hints] of this.parserHints) {
+            if (hints.multilineBlock)
+                this.multilineBlockTypes.delete(keyword);
+        }
+        this.parserHints.clear();
+    }
+    // ── Evolved Types (spec) ─────────────────────────────────────────────
+    registerEvolvedType(keyword) {
+        this.dynamicNodeTypes.add(keyword);
+    }
+    unregisterEvolvedType(keyword) {
+        this.dynamicNodeTypes.delete(keyword);
+    }
+    getEvolvedTypes() {
+        return new Set(this.dynamicNodeTypes);
+    }
+    clearEvolvedTypes() {
+        this.dynamicNodeTypes.clear();
+    }
+    // ── Evolved Generators (codegen) ─────────────────────────────────────
+    registerEvolvedGenerator(keyword, fn) {
+        this.evolvedGenerators.set(keyword, fn);
+    }
+    registerEvolvedTargetGenerator(keyword, target, fn) {
+        let targetMap = this.evolvedTargetGenerators.get(keyword);
+        if (!targetMap) {
+            targetMap = new Map();
+            this.evolvedTargetGenerators.set(keyword, targetMap);
+        }
+        targetMap.set(target, fn);
+    }
+    unregisterEvolvedGenerator(keyword) {
+        this.evolvedGenerators.delete(keyword);
+        this.evolvedTargetGenerators.delete(keyword);
+    }
+    hasEvolvedGenerator(keyword) {
+        return this.evolvedGenerators.has(keyword);
+    }
+    clearEvolvedGenerators() {
+        this.evolvedGenerators.clear();
+        this.evolvedTargetGenerators.clear();
+    }
+    // ── Templates ────────────────────────────────────────────────────────
+    registerTemplate(name, def) {
+        this.templateRegistry.set(name, def);
+    }
+    isTemplateNode(type) {
+        return this.templateRegistry.has(type);
+    }
+    getTemplate(name) {
+        return this.templateRegistry.get(name);
+    }
+    templateCount() {
+        return this.templateRegistry.size;
+    }
+    clearTemplates() {
+        this.templateRegistry.clear();
+    }
+    // ── Full Reset ───────────────────────────────────────────────────────
+    /** Reset all runtime state. Useful for test isolation. */
+    reset() {
+        this.clearParserHints();
+        this.clearEvolvedTypes();
+        this.clearEvolvedGenerators();
+        this.clearTemplates();
+        this.lastParseDiagnostics = [];
+    }
+}
+// ── Default Runtime ──────────────────────────────────────────────────────
+/**
+ * Default runtime singleton. All existing module-level registration functions
+ * delegate to this instance for backward compatibility.
+ */
+export const defaultRuntime = new KernRuntime();
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,39 @@
+/**
+ * AST Schema Validation — validates IRNode shape after parsing, before codegen.
+ *
+ * Defines required/optional props and allowed child types per node type.
+ * Catches malformed ASTs (missing required props, wrong children) at the
+ * parse boundary instead of scattering validation across 76 codegen functions.
+ *
+ * Props are classified by kind:
+ *   - 'identifier'     → validated by emitIdentifier
+ *   - 'typeAnnotation' → validated by emitTypeAnnotation
+ *   - 'importPath'     → validated by emitImportSpecifier
+ *   - 'rawExpr'        → intentional escape hatch (handler code, expressions)
+ *   - 'rawBlock'       → intentional escape hatch (<<<...>>> blocks)
+ *   - 'string'         → free-form string value
+ *   - 'boolean'        → 'true'/'false'
+ *   - 'number'         → numeric value
+ */
+import type { IRNode } from './types.js';
+export type PropKind = 'identifier' | 'typeAnnotation' | 'importPath' | 'rawExpr' | 'rawBlock' | 'string' | 'boolean' | 'number';
+export interface PropSchema {
+    required?: boolean;
+    kind: PropKind;
+}
+export interface NodeSchema {
+    props: Record<string, PropSchema>;
+    allowedChildren?: string[];
+}
+export declare const NODE_SCHEMAS: Record<string, NodeSchema>;
+export interface SchemaViolation {
+    nodeType: string;
+    message: string;
+    line?: number;
+    col?: number;
+}
+/**
+ * Validate an IRNode tree against the schema definitions.
+ * Returns violations found. Empty array = valid.
+ */
+export declare function validateSchema(root: IRNode): SchemaViolation[];