@zenithbuild/compiler 1.3.2 → 1.3.9

package/dist/discovery/componentDiscovery.js

@@ -0,0 +1,66 @@
+/**
+ * Component Discovery
+ *
+ * Discovers and catalogs components in a Zenith project using standard
+ * file system walking and the unified native "syscall" for metadata.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseZenFile } from '../parseZenFile';
+/**
+ * Discover all components in a directory recursively
+ */
+export function discoverComponents(baseDir) {
+    const components = new Map();
+    if (!fs.existsSync(baseDir))
+        return components;
+    const walk = (dir) => {
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const fullPath = path.join(dir, file);
+            if (fs.statSync(fullPath).isDirectory()) {
+                walk(fullPath);
+            }
+            else if (file.endsWith('.zen')) {
+                const name = path.basename(file, '.zen');
+                try {
+                    // Call the "One True Bridge" in metadata mode
+                    const ir = parseZenFile(fullPath, undefined, { mode: 'metadata' });
+                    // Map IR to ComponentMetadata format
+                    components.set(name, {
+                        name,
+                        path: fullPath,
+                        template: ir.template.raw,
+                        nodes: ir.template.nodes,
+                        expressions: ir.template.expressions,
+                        slots: [], // Native bridge needs to return slot info in IR if used
+                        props: ir.props || [],
+                        states: ir.script?.states || {},
+                        styles: ir.styles?.map((s) => s.raw) || [],
+                        script: ir.script?.raw || null,
+                        scriptAttributes: ir.script?.attributes || null,
+                        hasScript: !!ir.script,
+                        hasStyles: ir.styles?.length > 0
+                    });
+                }
+                catch (e) {
+                    console.error(`[Zenith Discovery] Failed to parse component ${file}:`, e);
+                }
+            }
+        }
+    };
+    walk(baseDir);
+    return components;
+}
+/**
+ * Universal Zenith Component Tag Rule: PascalCase
+ */
+export function isComponentTag(tagName) {
+    return tagName.length > 0 && tagName[0] === tagName[0]?.toUpperCase();
+}
+/**
+ * Get component metadata by name
+ */
+export function getComponent(components, name) {
+    return components.get(name);
+}

package/dist/discovery/layouts.d.ts

@@ -0,0 +1,14 @@
+export interface LayoutMetadata {
+    name: string;
+    filePath: string;
+    props: string[];
+    states: Map<string, any>;
+    html: string;
+    scripts: string[];
+    styles: string[];
+}
+/**
+ * Discover layouts in a directory using standard file system walking
+ * and the unified native bridge for metadata.
+ */
+export declare function discoverLayouts(layoutsDir: string): Map<string, LayoutMetadata>;

package/dist/discovery/layouts.js

@@ -0,0 +1,36 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseZenFile } from '../parseZenFile';
+/**
+ * Discover layouts in a directory using standard file system walking
+ * and the unified native bridge for metadata.
+ */
+export function discoverLayouts(layoutsDir) {
+    const layouts = new Map();
+    if (!fs.existsSync(layoutsDir))
+        return layouts;
+    const files = fs.readdirSync(layoutsDir);
+    for (const file of files) {
+        if (file.endsWith('.zen')) {
+            const fullPath = path.join(layoutsDir, file);
+            const name = path.basename(file, '.zen');
+            try {
+                // Call the "One True Bridge" in metadata mode
+                const ir = parseZenFile(fullPath, undefined, { mode: 'metadata' });
+                layouts.set(name, {
+                    name,
+                    filePath: fullPath,
+                    props: ir.props || [],
+                    states: new Map(),
+                    html: ir.template.raw,
+                    scripts: ir.script ? [ir.script.content] : [],
+                    styles: ir.styles?.map((s) => s.raw) || []
+                });
+            }
+            catch (e) {
+                console.error(`[Zenith Layout Discovery] Failed to parse layout ${file}:`, e);
+            }
+        }
+    }
+    return layouts;
+}

package/dist/errors/compilerError.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Compiler Error Handling
+ *
+ * Compiler errors with source location information
+ */
+export declare class CompilerError extends Error {
+    file: string;
+    line: number;
+    column: number;
+    errorType: string;
+    context?: string;
+    hints: string[];
+    code?: string;
+    constructor(message: string, file: string, line: number, column: number, errorType?: string, context?: string, hints?: string[], code?: string);
+    toString(): string;
+}
+/**
+ * Invariant Error
+ *
+ * Thrown when a Zenith compiler invariant is violated.
+ * Invariants are non-negotiable rules that guarantee correct behavior.
+ *
+ * If an invariant fails, the compiler is at fault — not the user.
+ * The user receives a clear explanation of what is forbidden and why.
+ */
+export declare class InvariantError extends CompilerError {
+    invariantId: string;
+    guarantee: string;
+    constructor(invariantId: string, message: string, guarantee: string, file: string, line: number, column: number, context?: string, hints?: string[]);
+    toString(): string;
+}

package/dist/errors/compilerError.js

@@ -0,0 +1,51 @@
+/**
+ * Compiler Error Handling
+ *
+ * Compiler errors with source location information
+ */
+export class CompilerError extends Error {
+    file;
+    line;
+    column;
+    errorType;
+    context;
+    hints;
+    code;
+    constructor(message, file, line, column, errorType = 'COMPILER_ERROR', context, hints = [], code) {
+        super(`${file}:${line}:${column} ${message}`);
+        this.name = 'CompilerError';
+        this.file = file;
+        this.line = line;
+        this.column = column;
+        this.errorType = errorType;
+        this.context = context;
+        this.hints = hints;
+        this.code = code;
+    }
+    toString() {
+        return `${this.file}:${this.line}:${this.column} [${this.errorType}] ${this.message}`;
+    }
+}
+/**
+ * Invariant Error
+ *
+ * Thrown when a Zenith compiler invariant is violated.
+ * Invariants are non-negotiable rules that guarantee correct behavior.
+ *
+ * If an invariant fails, the compiler is at fault — not the user.
+ * The user receives a clear explanation of what is forbidden and why.
+ */
+export class InvariantError extends CompilerError {
+    invariantId;
+    guarantee;
+    constructor(invariantId, message, guarantee, file, line, column, context, hints = []) {
+        super(`[${invariantId}] ${message}\n\n  Zenith Guarantee: ${guarantee}`, file, line, column, 'COMPILER_INVARIANT_VIOLATION', context, hints, invariantId);
+        this.name = 'InvariantError';
+        this.invariantId = invariantId;
+        this.guarantee = guarantee;
+        this.code = invariantId;
+    }
+    toString() {
+        return `${this.file}:${this.line}:${this.column} [${this.invariantId}] ${this.message}`;
+    }
+}

package/dist/finalize/generateFinalBundle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Generate Final Bundle
+ *
+ * Phase 8/9/10: Generate final browser-ready bundle
+ *
+ * Combines:
+ * - Compiled HTML
+ * - Runtime JS
+ * - Expression functions
+ * - Event bindings
+ * - Style injection
+ */
+import type { FinalizedOutput } from '../output/types';
+/**
+ * Generate final bundle code
+ *
+ * This is the complete JavaScript bundle that will execute in the browser.
+ * All expressions are pre-compiled - no template parsing at runtime.
+ */
+export declare function generateFinalBundle(finalized: FinalizedOutput): string;
+/**
+ * Generate HTML with inline script
+ */
+export declare function generateHTMLWithScript(html: string, jsBundle: string, styles: string[]): string;

package/dist/finalize/generateFinalBundle.js

@@ -0,0 +1,68 @@
+/**
+ * Generate Final Bundle
+ *
+ * Phase 8/9/10: Generate final browser-ready bundle
+ *
+ * Combines:
+ * - Compiled HTML
+ * - Runtime JS
+ * - Expression functions
+ * - Event bindings
+ * - Style injection
+ */
+/**
+ * Generate final bundle code
+ *
+ * This is the complete JavaScript bundle that will execute in the browser.
+ * All expressions are pre-compiled - no template parsing at runtime.
+ */
+export function generateFinalBundle(finalized) {
+    return `// Zenith Compiled Bundle (Phase 8/9/10)
+// Generated at compile time - no .zen parsing in browser
+// All expressions are pre-compiled - deterministic output
+
+${finalized.js}
+
+// Bundle complete - ready for browser execution
+`;
+}
+/**
+ * Generate HTML with inline script
+ */
+export function generateHTMLWithScript(html, jsBundle, styles) {
+    // Inject styles as <style> tags
+    const styleTags = styles.map(style => `<style>${escapeHTML(style)}</style>`).join('\n');
+    // Inject JS bundle as inline script
+    const scriptTag = `<script>${jsBundle}</script>`;
+    // Find </head> or <body> to inject styles
+    // Find </body> to inject script
+    let result = html;
+    if (styleTags) {
+        if (result.includes('</head>')) {
+            result = result.replace('</head>', `${styleTags}\n</head>`);
+        }
+        else if (result.includes('<body')) {
+            result = result.replace('<body', `${styleTags}\n<body`);
+        }
+    }
+    if (scriptTag) {
+        if (result.includes('</body>')) {
+            result = result.replace('</body>', `${scriptTag}\n</body>`);
+        }
+        else {
+            result += scriptTag;
+        }
+    }
+    return result;
+}
+/**
+ * Escape HTML for safe embedding
+ */
+function escapeHTML(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { parseZenFile } from './parseZenFile';
+import type { ZenIR } from './ir/types';
+import type { CompiledTemplate, FinalizedOutput } from './output/types';
+export type ZenCompileOptions = {
+    /**
+     * Map of component names to their definitions.
+     */
+    components?: Map<string, any>;
+    /**
+     * Optional directory to discover components from
+     */
+    componentsDir?: string;
+    /**
+     * Optional layout to wrap the page in
+     */
+    layout?: any;
+    /**
+     * Initial props for layout processing
+     */
+    props?: Record<string, any>;
+};
+export type ZenCompileResult = {
+    ir: ZenIR;
+    compiled: CompiledTemplate;
+    finalized?: FinalizedOutput;
+};
+/**
+ * Compile Zenith source code using the unified "One True Bridge" (Native Syscall).
+ */
+export declare function compile(source: string, filePath: string, options?: ZenCompileOptions): Promise<ZenCompileResult>;
+export { parseZenFile };
+export type { FinalizedOutput, CompiledTemplate };
+export type { BundlePlan, ExpressionIR, ZenIR, TemplateNode } from './ir/types';
+export type { HookContext } from './core/plugins/bridge';

package/dist/index.js

@@ -0,0 +1,44 @@
+// Core Imports (Internal)
+import { parseZenFile } from './parseZenFile';
+import { InvariantError } from './errors/compilerError';
+import { discoverComponents } from './discovery/componentDiscovery';
+/**
+ * Compile Zenith source code using the unified "One True Bridge" (Native Syscall).
+ */
+export async function compile(source, filePath, options) {
+    const opts = options || {};
+    // Discover components if directory provided
+    let components = opts.components || new Map();
+    if (opts.componentsDir) {
+        const discovered = discoverComponents(opts.componentsDir);
+        components = new Map([...components, ...discovered]);
+    }
+    const finalized = parseZenFile(filePath, source, {
+        mode: 'full',
+        components: components ? Object.fromEntries(components) : {},
+        layout: opts.layout,
+        props: opts.props,
+        useCache: true
+    });
+    // If the native side returned a compiler error (camelCase or snake_case fields)
+    if (finalized.code && (finalized.errorType || finalized.error_type)) {
+        throw new InvariantError(finalized.code, finalized.message, finalized.guarantee || "Zenith Invariant Violation", // Guarantee provided by native code checks
+        filePath, finalized.line || 1, finalized.column || 1, finalized.context, finalized.hints);
+    }
+    return {
+        ir: finalized.ir,
+        compiled: {
+            html: finalized.html,
+            bindings: finalized.bindings || [],
+            scripts: finalized.js || null,
+            styles: finalized.styles || []
+        },
+        finalized: {
+            ...finalized,
+            js: finalized.js,
+            npmImports: finalized.npmImports,
+            bundlePlan: finalized.bundlePlan
+        }
+    };
+}
+export { parseZenFile };

package/dist/ir/types.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Zenith Intermediate Representation (IR)
+ *
+ * Phase 1: Parse & Extract
+ * This IR represents the parsed structure of a .zen file
+ * without any runtime execution or transformation.
+ */
+/**
+ * Structured ES module import metadata
+ * Parsed from component scripts, used for deterministic bundling
+ */
+export interface ScriptImport {
+    source: string;
+    specifiers: string;
+    typeOnly: boolean;
+    sideEffect: boolean;
+}
+/**
+ * Property extracted from interface/type definition
+ * Used by props<T>() constraint - shape-only parsing
+ */
+export interface PropTypeProperty {
+    name: string;
+    optional: boolean;
+    typeAnnotation: string;
+}
+/**
+ * TypeScript type binding parsed from props<T>() constraint
+ * This is a CONSTRAINT, not a declaration - it restricts allowed props
+ */
+export interface PropsTypeBinding {
+    typeName: string;
+    sourceFile?: string;
+    properties: PropTypeProperty[];
+}
+/**
+ * Component Script IR - represents a component's script block
+ * Used for collecting and bundling component scripts
+ */
+export type ComponentScriptIR = {
+    name: string;
+    script: string;
+    props: string[];
+    scriptAttributes: Record<string, string>;
+    imports: ScriptImport[];
+    instanceId?: string;
+    propValues?: Record<string, any>;
+    expressions?: ExpressionIR[];
+    propsTypeBinding?: PropsTypeBinding;
+};
+export type ZenIR = {
+    filePath: string;
+    template: TemplateIR;
+    script: ScriptIR | null;
+    styles: StyleIR[];
+    states?: Record<string, string>;
+    componentScripts?: ComponentScriptIR[];
+    pageBindings?: string[];
+    props?: string[];
+    mergedBindings?: string[];
+};
+export type TemplateIR = {
+    raw: string;
+    nodes: TemplateNode[];
+    expressions: ExpressionIR[];
+};
+export type TemplateNode = ElementNode | TextNode | ExpressionNode | ComponentNode | ConditionalFragmentNode | OptionalFragmentNode | LoopFragmentNode | DoctypeNode;
+export type DoctypeNode = {
+    type: 'doctype';
+    name: string;
+    publicId: string;
+    systemId: string;
+    location: SourceLocation;
+};
+export type ElementNode = {
+    type: 'element';
+    tag: string;
+    attributes: AttributeIR[];
+    children: TemplateNode[];
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+export type ComponentNode = {
+    type: 'component';
+    name: string;
+    attributes: AttributeIR[];
+    children: TemplateNode[];
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+export type TextNode = {
+    type: 'text';
+    value: string;
+    location: SourceLocation;
+};
+export type ExpressionNode = {
+    type: 'expression';
+    expression: string;
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+/**
+ * Conditional Fragment Node
+ *
+ * Represents ternary expressions with JSX branches: {cond ? <A /> : <B />}
+ *
+ * BOTH branches are compiled at compile time.
+ * Runtime toggles visibility — never creates DOM.
+ */
+export type ConditionalFragmentNode = {
+    type: 'conditional-fragment';
+    condition: string;
+    consequent: TemplateNode[];
+    alternate: TemplateNode[];
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+/**
+ * Optional Fragment Node
+ *
+ * Represents logical AND expressions with JSX: {cond && <A />}
+ *
+ * Fragment is compiled at compile time.
+ * Runtime toggles mount/unmount based on condition.
+ */
+export type OptionalFragmentNode = {
+    type: 'optional-fragment';
+    condition: string;
+    fragment: TemplateNode[];
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+/**
+ * Loop Fragment Node
+ *
+ * Represents .map() expressions with JSX body: {items.map(i => <li>...</li>)}
+ *
+ * Desugars to @for loop semantics at compile time.
+ * Body is compiled once, instantiated per item at runtime.
+ * Node identity is compiler-owned via stable keys.
+ */
+export type LoopFragmentNode = {
+    type: 'loop-fragment';
+    source: string;
+    itemVar: string;
+    indexVar?: string;
+    body: TemplateNode[];
+    location: SourceLocation;
+    loopContext: LoopContext;
+};
+export type AttributeIR = {
+    name: string;
+    value: string | ExpressionIR;
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+/**
+ * Loop context for expressions inside map iterations
+ * Phase 7: Tracks loop variables (e.g., todo, index) for expressions inside .map() calls
+ */
+export type LoopContext = {
+    variables: string[];
+    mapSource?: string;
+};
+export type ExpressionIR = {
+    id: string;
+    code: string;
+    location: SourceLocation;
+    loopContext?: LoopContext;
+};
+export type ScriptIR = {
+    raw: string;
+    attributes: Record<string, string>;
+    props?: string[];
+    states?: Record<string, string>;
+    bindings?: string[];
+};
+export type StyleIR = {
+    raw: string;
+};
+export type SourceLocation = {
+    line: number;
+    column: number;
+};
+/**
+ * BundlePlan - Compiler-emitted contract for bundler execution
+ *
+ * If a plan exists, bundling MUST occur.
+ * If no plan exists, bundling MUST NOT occur.
+ * The bundler performs ZERO inference—it executes exactly what the compiler specifies.
+ */
+export interface BundlePlan {
+    /** Entry point code (not a file path) */
+    entry: string;
+    /** Target platform */
+    platform: 'browser' | 'node';
+    /** Output format */
+    format: 'esm' | 'cjs';
+    /** Directories to resolve modules from */
+    resolveRoots: string[];
+    /** Virtual modules provided by the compiler */
+    virtualModules: Array<{
+        id: string;
+        code: string;
+    }>;
+}

package/dist/ir/types.js

@@ -0,0 +1,8 @@
+/**
+ * Zenith Intermediate Representation (IR)
+ *
+ * Phase 1: Parse & Extract
+ * This IR represents the parsed structure of a .zen file
+ * without any runtime execution or transformation.
+ */
+export {};

package/dist/output/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Compiled Template Output Types
+ *
+ * Phase 2: Transform IR → Static HTML + Runtime Bindings
+ */
+export type CompiledTemplate = {
+    html: string;
+    bindings: Binding[];
+    scripts: string | null;
+    styles: string;
+};
+export type Binding = {
+    id: string;
+    type: 'text' | 'attribute' | 'conditional' | 'optional' | 'loop';
+    target: string;
+    expression: string;
+    location?: {
+        line: number;
+        column: number;
+    };
+    loopContext?: LoopContext;
+};
+/**
+ * Loop context for expressions inside map iterations
+ * Phase 7: Tracks loop variables for runtime setter generation
+ */
+export type LoopContext = {
+    variables: string[];
+    mapSource?: string;
+};
+export type FinalizedOutput = {
+    html: string;
+    js: string;
+    npmImports: string;
+    styles: string;
+    hasErrors: boolean;
+    errors: string[];
+    bundlePlan?: any;
+};

package/dist/output/types.js

@@ -0,0 +1,6 @@
+/**
+ * Compiled Template Output Types
+ *
+ * Phase 2: Transform IR → Static HTML + Runtime Bindings
+ */
+export {};

package/dist/parseZenFile.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Zenith File Parser (Native Bridge)
+ *
+ * Delegates all Zenith compilation to the Rust native "syscall" bridge.
+ * Zero fallbacks. Zero runtime abstraction.
+ */
+export interface ParseOptions {
+    mode?: 'metadata' | 'full';
+    components?: Record<string, any>;
+    layout?: any;
+    props?: Record<string, any>;
+    useCache?: boolean;
+}
+/**
+ * Perform a Zenith "Syscall" to the native compiler
+ */
+export declare function parseZenFile(filePath: string, sourceInput?: string, options?: ParseOptions): any;