@kernlang/core 3.1.3 → 3.1.4

package/dist/codegen/emitters.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Safe Emitters — prompt-injection immunity for KERN codegen.
+ *
+ * Every prop value interpolated into generated code MUST go through one of these.
+ * Raw string splicing is the root cause of codegen injection (audit 2026-03-25).
+ *
+ * Extracted from codegen-core.ts for independent reuse by React/Vue/Python codegens.
+ */
+import type { IRNode } from '../types.js';
+/** Validate and emit a safe identifier for generated code. Throws on invalid. */
+export declare function emitIdentifier(value: string | undefined, fallback: string, node?: IRNode): string;
+/** Escape a string for safe interpolation into a single-quoted JS string literal. */
+export declare function emitStringLiteral(value: string): string;
+/** Validate and emit a safe filesystem path for generated code. */
+export declare function emitPath(value: string, node?: IRNode): string;
+/** Escape a value for interpolation into a template literal in generated code. */
+export declare function emitTemplateSafe(value: string): string;
+/**
+ * Validate and emit a safe TypeScript type annotation for generated code.
+ * Handles generics, arrays, unions, intersections, tuples, function types.
+ * Rejects semicolons, backticks, template literals, dynamic imports, comments.
+ */
+export declare function emitTypeAnnotation(value: string | undefined, fallback: string, node?: IRNode): string;
+/** Validate and emit a safe import specifier for generated code. */
+export declare function emitImportSpecifier(value: string, node?: IRNode): string;

package/dist/codegen/emitters.js

@@ -0,0 +1,124 @@
+/**
+ * Safe Emitters — prompt-injection immunity for KERN codegen.
+ *
+ * Every prop value interpolated into generated code MUST go through one of these.
+ * Raw string splicing is the root cause of codegen injection (audit 2026-03-25).
+ *
+ * Extracted from codegen-core.ts for independent reuse by React/Vue/Python codegens.
+ */
+import { KernCodegenError } from '../errors.js';
+// Matches valid JS/TS identifiers — KERN hyphens are converted to camelCase by the parser.
+const SAFE_IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const SAFE_PATH_RE = /^[A-Za-z0-9/_.\-~]+$/;
+const SAFE_IMPORT_RE = /^(@[A-Za-z0-9_-]+\/)?[A-Za-z0-9_./:~-]+$/;
+/** Validate and emit a safe identifier for generated code. Throws on invalid. */
+export function emitIdentifier(value, fallback, node) {
+    const v = value || fallback;
+    if (!SAFE_IDENT_RE.test(v)) {
+        throw new KernCodegenError(`Invalid identifier: '${v.slice(0, 50)}' — must match KERN identifier grammar [A-Za-z_$][A-Za-z0-9_$]*`, node);
+    }
+    return v;
+}
+/** Escape a string for safe interpolation into a single-quoted JS string literal. */
+export function emitStringLiteral(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/`/g, '\\`')
+        .replace(/\$/g, '\\$')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+    return `'${escaped}'`;
+}
+/** Validate and emit a safe filesystem path for generated code. */
+export function emitPath(value, node) {
+    if (!SAFE_PATH_RE.test(value)) {
+        throw new KernCodegenError(`Invalid path: '${value.slice(0, 80)}' — contains unsafe characters`, node);
+    }
+    if (value.includes('..')) {
+        throw new KernCodegenError(`Invalid path: '${value.slice(0, 80)}' — path traversal (..) not allowed`, node);
+    }
+    return emitStringLiteral(value);
+}
+/** Escape a value for interpolation into a template literal in generated code. */
+export function emitTemplateSafe(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/`/g, '\\`')
+        .replace(/\$\{/g, '\\${');
+}
+/**
+ * Validate and emit a safe TypeScript type annotation for generated code.
+ * Handles generics, arrays, unions, intersections, tuples, function types.
+ * Rejects semicolons, backticks, template literals, dynamic imports, comments.
+ */
+export function emitTypeAnnotation(value, fallback, node) {
+    const v = (value || fallback).trim();
+    if (!v)
+        return fallback;
+    if (v.includes('`'))
+        throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — backticks not allowed in types`, node);
+    if (v.includes('${'))
+        throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — template interpolation not allowed`, node);
+    // Semicolons are valid inside object types { x: string; y: number } but not at top level
+    // Top-level semicolons checked during bracket scanning below
+    if (/import\s*\(/.test(v))
+        throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — dynamic imports not allowed in types`, node);
+    if (v.includes('//') || v.includes('/*'))
+        throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — comments not allowed in types`, node);
+    const stack = [];
+    const pairs = { '<': '>', '(': ')', '[': ']', '{': '}' };
+    const closers = { '>': '<', ')': '(', ']': '[', '}': '{' };
+    let inString = null;
+    for (let i = 0; i < v.length; i++) {
+        const ch = v[i];
+        if ((ch === "'" || ch === '"') && (i === 0 || v[i - 1] !== '\\')) {
+            if (inString === ch) {
+                inString = null;
+            }
+            else if (!inString) {
+                inString = ch;
+            }
+            continue;
+        }
+        if (inString)
+            continue;
+        // Reject semicolons at top level (statement injection) but allow inside {} (object types)
+        if (ch === ';' && stack.length === 0) {
+            throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — semicolons not allowed at top level in types`, node);
+        }
+        if (ch === '>' && i > 0 && v[i - 1] === '=')
+            continue;
+        if (ch in pairs) {
+            stack.push(ch);
+        }
+        else if (ch in closers) {
+            const expected = closers[ch];
+            if (stack.length === 0 || stack[stack.length - 1] !== expected) {
+                throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — unbalanced '${ch}'`, node);
+            }
+            stack.pop();
+        }
+    }
+    if (inString)
+        throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — unclosed string literal`, node);
+    if (stack.length > 0)
+        throw new KernCodegenError(`Invalid type annotation: '${v.slice(0, 80)}' — unclosed '${stack[stack.length - 1]}'`, node);
+    return v;
+}
+/** Validate and emit a safe import specifier for generated code. */
+export function emitImportSpecifier(value, node) {
+    if (!value)
+        throw new KernCodegenError('Import specifier cannot be empty', node);
+    if (value.includes("'") || value.includes('"') || value.includes('`') || value.includes('\\')) {
+        throw new KernCodegenError(`Invalid import specifier: '${value.slice(0, 80)}' — contains quote or escape characters`, node);
+    }
+    if (value.includes(';') || value.includes('$') || value.includes('\n')) {
+        throw new KernCodegenError(`Invalid import specifier: '${value.slice(0, 80)}' — contains unsafe characters`, node);
+    }
+    if (!SAFE_IMPORT_RE.test(value)) {
+        throw new KernCodegenError(`Invalid import specifier: '${value.slice(0, 80)}' — must be a valid module path`, node);
+    }
+    return value;
+}
+//# sourceMappingURL=emitters.js.map

package/dist/codegen/emitters.js.map

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

package/dist/codegen/helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared codegen helpers — IR node accessors, string utilities, and annotations.
+ *
+ * Extracted from codegen-core.ts for independent reuse by React/Vue/Python codegens.
+ * These are pure utility functions with no generator dependencies.
+ */
+import type { IRNode } from '../types.js';
+export declare function getProps(node: IRNode): Record<string, unknown>;
+export declare function getChildren(node: IRNode, type?: string): IRNode[];
+export declare function getFirstChild(node: IRNode, type: string): IRNode | undefined;
+export declare function getStyles(node: IRNode): Record<string, string>;
+export declare function getPseudoStyles(node: IRNode): Record<string, Record<string, string>>;
+export declare function getThemeRefs(node: IRNode): string[];
+export declare function dedent(code: string): string;
+export declare function cssPropertyName(camel: string): string;
+export declare function handlerCode(node: IRNode): string;
+export declare function exportPrefix(node: IRNode): string;
+export declare function capitalize(s: string): string;
+/** Parse "name:Type,name2:Type2,spread:number=8" → "name: Type, name2: Type2, spread: number = 8" */
+export declare function parseParamList(params: string): string;
+export declare function emitReasonAnnotations(node: IRNode): string[];
+export declare function emitLowConfidenceTodo(node: IRNode, confidence: string | undefined): string[];

package/dist/codegen/helpers.js

@@ -0,0 +1,159 @@
+/**
+ * Shared codegen helpers — IR node accessors, string utilities, and annotations.
+ *
+ * Extracted from codegen-core.ts for independent reuse by React/Vue/Python codegens.
+ * These are pure utility functions with no generator dependencies.
+ */
+// ── IR Node Accessors ───────────────────────────────────────────────────
+export function getProps(node) {
+    return node.props || {};
+}
+export function getChildren(node, type) {
+    const c = node.children || [];
+    return type ? c.filter(n => n.type === type) : c;
+}
+export function getFirstChild(node, type) {
+    return getChildren(node, type)[0];
+}
+export function getStyles(node) {
+    return getProps(node).styles || {};
+}
+export function getPseudoStyles(node) {
+    return getProps(node).pseudoStyles || {};
+}
+export function getThemeRefs(node) {
+    return getProps(node).themeRefs || [];
+}
+// ── String Utilities ────────────────────────────────────────────────────
+export function dedent(code) {
+    const lines = code.split('\n');
+    const nonEmpty = lines.filter(l => l.trim().length > 0);
+    if (nonEmpty.length === 0)
+        return code;
+    const minIndent = Math.min(...nonEmpty.map(l => l.match(/^(\s*)/)?.[1]?.length ?? 0));
+    return lines.map(l => l.slice(minIndent)).join('\n').trim();
+}
+export function cssPropertyName(camel) {
+    return camel.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+export function handlerCode(node) {
+    const handler = getFirstChild(node, 'handler');
+    if (!handler)
+        return '';
+    const raw = getProps(handler).code || '';
+    return dedent(raw);
+}
+export function exportPrefix(node) {
+    return getProps(node).export === 'false' ? '' : 'export ';
+}
+export function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+// ── Param Parsing ───────────────────────────────────────────────────────
+/** Parse "name:Type,name2:Type2,spread:number=8" → "name: Type, name2: Type2, spread: number = 8" */
+export function parseParamList(params) {
+    if (!params)
+        return '';
+    return splitParamsRespectingDepth(params).map(s => {
+        const trimmed = s.trim();
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1)
+            return trimmed;
+        const pname = trimmed.slice(0, colonIdx).trim();
+        const rest = trimmed.slice(colonIdx + 1).trim();
+        const eqIdx = findDefaultSeparator(rest);
+        if (eqIdx === -1)
+            return `${pname}: ${rest}`;
+        const ptype = rest.slice(0, eqIdx).trim();
+        const pdefault = rest.slice(eqIdx + 1).trim();
+        return `${pname}: ${ptype} = ${pdefault}`;
+    }).join(', ');
+}
+/** Split param string on commas while respecting <>, (), {} depth. */
+function splitParamsRespectingDepth(s) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === '<' || ch === '(' || ch === '{')
+            depth++;
+        else if ((ch === '>' || ch === ')' || ch === '}') && depth > 0)
+            depth--;
+        if (ch === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        parts.push(current);
+    return parts;
+}
+/** Find '=' separating type from default, skipping '=>' arrows. */
+function findDefaultSeparator(rest) {
+    let depth = 0;
+    for (let i = 0; i < rest.length; i++) {
+        const ch = rest[i];
+        if (ch === '<' || ch === '(' || ch === '{')
+            depth++;
+        else if (ch === '>' || ch === ')' || ch === '}')
+            depth--;
+        else if (ch === '=' && depth === 0) {
+            if (rest[i + 1] === '>')
+                continue;
+            return i;
+        }
+    }
+    return -1;
+}
+// ── Reason & Confidence Annotations ─────────────────────────────────────
+export function emitReasonAnnotations(node) {
+    const reasonNode = getFirstChild(node, 'reason');
+    const evidenceNode = getFirstChild(node, 'evidence');
+    const needsNodes = getChildren(node, 'needs');
+    const confidence = getProps(node).confidence;
+    if (!reasonNode && !evidenceNode && !confidence && needsNodes.length === 0)
+        return [];
+    const lines = ['/**'];
+    if (confidence)
+        lines.push(` * @confidence ${confidence}`);
+    if (reasonNode) {
+        const rp = getProps(reasonNode);
+        lines.push(` * @reason ${rp.because || ''}`);
+        if (rp.basis)
+            lines.push(` * @basis ${rp.basis}`);
+        if (rp.survives)
+            lines.push(` * @survives ${rp.survives}`);
+    }
+    if (evidenceNode) {
+        const ep = getProps(evidenceNode);
+        const parts = [`source=${ep.source}`];
+        if (ep.method)
+            parts.push(`method=${ep.method}`);
+        if (ep.authority)
+            parts.push(`authority=${ep.authority}`);
+        lines.push(` * @evidence ${parts.join(', ')}`);
+    }
+    for (const needsNode of needsNodes) {
+        const np = getProps(needsNode);
+        const desc = np.what || np.description || '';
+        const wouldRaise = np['would-raise-to'];
+        const tag = wouldRaise ? `${desc} (would raise to ${wouldRaise})` : desc;
+        lines.push(` * @needs ${tag}`);
+    }
+    lines.push(' */');
+    return lines;
+}
+export function emitLowConfidenceTodo(node, confidence) {
+    if (!confidence)
+        return [];
+    const val = parseFloat(confidence);
+    if (isNaN(val) || val >= 0.5 || confidence.includes(':'))
+        return [];
+    const name = getProps(node).name || node.type;
+    return [`// TODO(low-confidence): ${name} confidence=${confidence}`];
+}
+//# sourceMappingURL=helpers.js.map

package/dist/codegen/helpers.js.map

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

package/dist/codegen-core.d.ts

@@ -7,14 +7,9 @@
  * Machine nodes are KERN's killer feature: 12 lines of KERN → 140+ lines of TS.
  */
 import type { IRNode } from './types.js';
-/** Validate and emit a safe identifier for generated code. Throws on invalid. */
-export declare function emitIdentifier(value: string | undefined, fallback: string, node?: IRNode): string;
-/** Escape a string for safe interpolation into a single-quoted JS string literal. */
-export declare function emitStringLiteral(value: string): string;
-/** Validate and emit a safe filesystem path for generated code. */
-export declare function emitPath(value: string, node?: IRNode): string;
-/** Escape a value for interpolation into a template literal in generated code. */
-export declare function emitTemplateSafe(value: string): string;
+import { type KernRuntime } from './runtime.js';
+export { emitIdentifier, emitStringLiteral, emitPath, emitTemplateSafe, emitTypeAnnotation, emitImportSpecifier } from './codegen/emitters.js';
+export { getProps, getChildren, getFirstChild, getStyles, getPseudoStyles, getThemeRefs, dedent, cssPropertyName, handlerCode, exportPrefix, capitalize, parseParamList, emitReasonAnnotations, emitLowConfidenceTodo } from './codegen/helpers.js';
 /** Register an evolved generator (called at startup). */
 export declare function registerEvolvedGenerator(keyword: string, fn: (node: IRNode) => string[]): void;
 /** Register a target-specific evolved generator (called at startup). */
@@ -25,25 +20,6 @@ export declare function unregisterEvolvedGenerator(keyword: string): void;
 export declare function clearEvolvedGenerators(): void;
 /** Check if an evolved generator exists for a type. */
 export declare function hasEvolvedGenerator(type: string): boolean;
-/** Extract props from an IR node. */
-export declare function getProps(node: IRNode): Record<string, unknown>;
-/** Get children, optionally filtered by type. */
-export declare function getChildren(node: IRNode, type?: string): IRNode[];
-/** Get first child of a given type. */
-export declare function getFirstChild(node: IRNode, type: string): IRNode | undefined;
-/** Extract styles from node props. */
-export declare function getStyles(node: IRNode): Record<string, string>;
-/** Extract pseudo-styles from node props. */
-export declare function getPseudoStyles(node: IRNode): Record<string, Record<string, string>>;
-/** Extract theme refs from node props. */
-export declare function getThemeRefs(node: IRNode): string[];
-/** Strip common leading whitespace from multiline handler code. */
-export declare function dedent(code: string): string;
-/** Convert camelCase to kebab-case for CSS property names. */
-export declare function cssPropertyName(camel: string): string;
-/** Extract handler code from a node (finds handler child, dedents). */
-export declare function handlerCode(node: IRNode): string;
-export declare function exportPrefix(node: IRNode): string;
 export declare function generateType(node: IRNode): string[];
 export declare function generateInterface(node: IRNode): string[];
 export declare function generateUnion(node: IRNode): string[];
@@ -61,13 +37,6 @@ export declare function generateWebSocket(node: IRNode): string[];
 export declare function generateModule(node: IRNode): string[];
 export declare function generateImport(node: IRNode): string[];
 export declare function generateConst(node: IRNode): string[];
-/** Parse "name:Type,name2:Type2,spread:number=8" → "name: Type, name2: Type2, spread: number = 8"
- *  Supports default values via = after the type. */
-export declare function parseParamList(params: string): string;
-export declare function capitalize(s: string): string;
-export declare function emitReasonAnnotations(node: IRNode): string[];
-/** Emit a TODO comment for nodes with low literal confidence (< 0.5). */
-export declare function emitLowConfidenceTodo(node: IRNode, confidence: string | undefined): string[];
 export declare function generateDerive(node: IRNode): string[];
 export declare function generateTransform(node: IRNode): string[];
 export declare function generateAction(node: IRNode): string[];
@@ -92,4 +61,4 @@ export declare const CORE_NODE_TYPES: Set<string>;
 /** Check if a node type is a core language construct. */
 export declare function isCoreNode(type: string): boolean;
 /** Generate TypeScript for any core language node. */
-export declare function generateCoreNode(node: IRNode, target?: string): string[];
+export declare function generateCoreNode(node: IRNode, target?: string, runtime?: KernRuntime): string[];