@zenithbuild/compiler 1.0.2

package/dist/css/index.js

@@ -0,0 +1,246 @@
+/**
+ * Zenith CSS Compiler Module
+ *
+ * Compiler-owned CSS processing that integrates Tailwind CSS v4 JIT
+ * at compile time. This module ensures:
+ *
+ * 1. All CSS is processed at build time (no runtime generation)
+ * 2. Tailwind sees all .zen templates for class scanning
+ * 3. HMR support for instant CSS updates in dev mode
+ * 4. Deterministic, cacheable output for production
+ *
+ * Per Zenith CSS Directive: The compiler owns styles.
+ */
+import { spawn, spawnSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+// ============================================
+// CSS Compilation
+// ============================================
+/**
+ * Compile CSS using Tailwind CSS v4 CLI
+ *
+ * This function synchronously compiles CSS for use in:
+ * - Dev server startup
+ * - SSG build
+ * - On-demand recompilation
+ *
+ * @param options Compilation options
+ * @returns Compiled CSS result
+ */
+export function compileCss(options) {
+    const startTime = performance.now();
+    const { input, output, minify = false } = options;
+    // Validate input exists
+    if (!fs.existsSync(input)) {
+        return {
+            css: '',
+            duration: 0,
+            success: false,
+            error: `CSS input file not found: ${input}`
+        };
+    }
+    try {
+        // Build Tailwind CLI arguments
+        const args = [
+            '@tailwindcss/cli',
+            '-i', input
+        ];
+        // For in-memory compilation, use stdout
+        const useStdout = output === ':memory:';
+        if (!useStdout) {
+            args.push('-o', output);
+        }
+        if (minify) {
+            args.push('--minify');
+        }
+        // Execute Tailwind CLI synchronously
+        const result = spawnSync('bunx', args, {
+            cwd: path.dirname(input),
+            encoding: 'utf-8',
+            stdio: useStdout ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'pipe'],
+            env: { ...process.env }
+        });
+        const duration = Math.round(performance.now() - startTime);
+        if (result.status !== 0) {
+            const errorMsg = result.stderr?.toString() || 'Unknown compilation error';
+            return {
+                css: '',
+                duration,
+                success: false,
+                error: `Tailwind compilation failed: ${errorMsg}`
+            };
+        }
+        // Get CSS content
+        let css = '';
+        if (useStdout) {
+            css = result.stdout?.toString() || '';
+        }
+        else if (fs.existsSync(output)) {
+            css = fs.readFileSync(output, 'utf-8');
+        }
+        return {
+            css,
+            duration,
+            success: true
+        };
+    }
+    catch (error) {
+        return {
+            css: '',
+            duration: Math.round(performance.now() - startTime),
+            success: false,
+            error: error.message
+        };
+    }
+}
+/**
+ * Compile CSS asynchronously (non-blocking)
+ *
+ * Used for HMR updates where we don't want to block the main thread.
+ */
+export async function compileCssAsync(options) {
+    return new Promise((resolve) => {
+        const startTime = performance.now();
+        const { input, output, minify = false } = options;
+        if (!fs.existsSync(input)) {
+            resolve({
+                css: '',
+                duration: 0,
+                success: false,
+                error: `CSS input file not found: ${input}`
+            });
+            return;
+        }
+        const args = ['@tailwindcss/cli', '-i', input];
+        const useStdout = output === ':memory:';
+        if (!useStdout) {
+            args.push('-o', output);
+        }
+        if (minify) {
+            args.push('--minify');
+        }
+        const child = spawn('bunx', args, {
+            cwd: path.dirname(input),
+            stdio: useStdout ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'pipe'],
+            env: { ...process.env }
+        });
+        let stdout = '';
+        let stderr = '';
+        if (useStdout && child.stdout) {
+            child.stdout.on('data', (data) => { stdout += data.toString(); });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => { stderr += data.toString(); });
+        }
+        child.on('close', (code) => {
+            const duration = Math.round(performance.now() - startTime);
+            if (code !== 0) {
+                resolve({
+                    css: '',
+                    duration,
+                    success: false,
+                    error: `Tailwind compilation failed: ${stderr}`
+                });
+                return;
+            }
+            let css = '';
+            if (useStdout) {
+                css = stdout;
+            }
+            else if (fs.existsSync(output)) {
+                css = fs.readFileSync(output, 'utf-8');
+            }
+            resolve({
+                css,
+                duration,
+                success: true
+            });
+        });
+        child.on('error', (err) => {
+            resolve({
+                css: '',
+                duration: Math.round(performance.now() - startTime),
+                success: false,
+                error: err.message
+            });
+        });
+    });
+}
+/**
+ * Watch CSS and source files for changes, recompile on change
+ *
+ * This is used by the dev server for HMR support.
+ * It watches both the CSS entry point AND all .zen files
+ * that Tailwind scans for class names.
+ */
+export function watchCss(options) {
+    const { input, output, minify, onChange, debounce = 100 } = options;
+    let timeout = null;
+    let isCompiling = false;
+    const recompile = async () => {
+        if (isCompiling)
+            return;
+        isCompiling = true;
+        const result = await compileCssAsync({ input, output, minify });
+        onChange(result);
+        isCompiling = false;
+    };
+    const debouncedRecompile = () => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(recompile, debounce);
+    };
+    // Watch the styles directory
+    const stylesDir = path.dirname(input);
+    const stylesWatcher = fs.watch(stylesDir, { recursive: true }, (event, filename) => {
+        if (filename?.endsWith('.css')) {
+            debouncedRecompile();
+        }
+    });
+    // Watch source files that Tailwind scans (for class changes)
+    // This assumes standard Zenith structure: src/pages, src/components, src/layouts
+    const srcDir = path.resolve(stylesDir, '..');
+    let srcWatcher = null;
+    if (fs.existsSync(srcDir)) {
+        srcWatcher = fs.watch(srcDir, { recursive: true }, (event, filename) => {
+            if (filename?.endsWith('.zen') || filename?.endsWith('.tsx') || filename?.endsWith('.jsx')) {
+                debouncedRecompile();
+            }
+        });
+    }
+    // Return cleanup function
+    return () => {
+        if (timeout)
+            clearTimeout(timeout);
+        stylesWatcher.close();
+        srcWatcher?.close();
+    };
+}
+// ============================================
+// Path Utilities
+// ============================================
+/**
+ * Resolve the canonical globals.css path for a Zenith project
+ */
+export function resolveGlobalsCss(projectRoot) {
+    // Check for globals.css (canonical)
+    const globalsPath = path.join(projectRoot, 'src', 'styles', 'globals.css');
+    if (fs.existsSync(globalsPath))
+        return globalsPath;
+    // Check for global.css (legacy)
+    const globalPath = path.join(projectRoot, 'src', 'styles', 'global.css');
+    if (fs.existsSync(globalPath))
+        return globalPath;
+    return null;
+}
+/**
+ * Get the output path for compiled CSS
+ */
+export function getCompiledCssPath(projectRoot, mode) {
+    if (mode === 'build') {
+        return path.join(projectRoot, 'dist', 'assets', 'styles.css');
+    }
+    // In dev mode, we use in-memory compilation
+    return ':memory:';
+}

package/dist/discovery/componentDiscovery.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Component Discovery
+ *
+ * Discovers and catalogs components in a Zenith project
+ * Similar to layout discovery but for reusable components
+ */
+import type { TemplateNode, ExpressionIR } from '../ir/types';
+export interface SlotDefinition {
+    name: string | null;
+    location: {
+        line: number;
+        column: number;
+    };
+}
+export interface ComponentMetadata {
+    name: string;
+    path: string;
+    template: string;
+    nodes: TemplateNode[];
+    expressions: ExpressionIR[];
+    slots: SlotDefinition[];
+    props: string[];
+    styles: string[];
+    script: string | null;
+    scriptAttributes: Record<string, string> | null;
+    hasScript: boolean;
+    hasStyles: boolean;
+}
+/**
+ * Discover all components in a directory
+ * @param baseDir - Base directory to search (e.g., src/components)
+ * @returns Map of component name to metadata
+ */
+export declare function discoverComponents(baseDir: string): Map<string, ComponentMetadata>;
+/**
+ * Use native bridge for tag name checks
+ */
+export declare function isComponentTag(tagName: string): boolean;
+/**
+ * Get component metadata by name
+ */
+export declare function getComponent(components: Map<string, ComponentMetadata>, name: string): ComponentMetadata | undefined;

package/dist/discovery/componentDiscovery.js

@@ -0,0 +1,56 @@
+/**
+ * Component Discovery
+ *
+ * Discovers and catalogs components in a Zenith project
+ * Similar to layout discovery but for reusable components
+ */
+let native;
+try {
+    try {
+        native = require('../../native/compiler-native');
+    }
+    catch {
+        native = require('../../native/compiler-native/index.js');
+    }
+}
+catch (e) {
+    // Bridge load handled elsewhere
+}
+/**
+ * Discover all components in a directory
+ * @param baseDir - Base directory to search (e.g., src/components)
+ * @returns Map of component name to metadata
+ */
+export function discoverComponents(baseDir) {
+    if (native && native.discoverComponentsNative) {
+        try {
+            const raw = native.discoverComponentsNative(baseDir);
+            // The native function returns a Map-like object or Record
+            const components = new Map();
+            for (const [name, metadata] of Object.entries(raw)) {
+                components.set(name, metadata);
+            }
+            return components;
+        }
+        catch (error) {
+            console.warn(`[Zenith Native] Discovery failed for ${baseDir}: ${error.message}`);
+        }
+    }
+    // Fallback or empty if native fails (bridge is required for performance)
+    return new Map();
+}
+/**
+ * Use native bridge for tag name checks
+ */
+export function isComponentTag(tagName) {
+    if (native && native.isComponentTagNative) {
+        return native.isComponentTagNative(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,13 @@
+export interface LayoutMetadata {
+    name: string;
+    filePath: string;
+    props: string[];
+    states: Map<string, string>;
+    html: string;
+    scripts: string[];
+    styles: string[];
+}
+/**
+ * Discover layouts in a directory
+ */
+export declare function discoverLayouts(layoutsDir: string): Map<string, LayoutMetadata>;

package/dist/discovery/layouts.js

@@ -0,0 +1,41 @@
+let native;
+try {
+    try {
+        native = require('../../native/compiler-native');
+    }
+    catch {
+        native = require('../../native/compiler-native/index.js');
+    }
+}
+catch (e) {
+    // Bridge load handled elsewhere
+}
+/**
+ * Discover layouts in a directory
+ */
+export function discoverLayouts(layoutsDir) {
+    if (native && native.discoverLayoutsNative) {
+        try {
+            const raw = native.discoverLayoutsNative(layoutsDir);
+            const layouts = new Map();
+            for (const [name, metadata] of Object.entries(raw)) {
+                // Adjust for Rust's camelCase vs Map mapping if needed
+                const meta = metadata;
+                layouts.set(name, {
+                    name: meta.name,
+                    filePath: meta.filePath,
+                    props: meta.props,
+                    states: new Map(Object.entries(meta.states || {})),
+                    html: meta.html,
+                    scripts: meta.scripts,
+                    styles: meta.styles
+                });
+            }
+            return layouts;
+        }
+        catch (error) {
+            console.warn(`[Zenith Native] Layout discovery failed for ${layoutsDir}: ${error.message}`);
+        }
+    }
+    return new Map();
+}

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/finalizeOutput.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Finalize Output
+ *
+ * NATIVE BRIDGE: Delegates ALL finalization (Phase 8/9/10) to Rust (`native/compiler-native/src/finalize.rs`).
+ */
+import type { CompiledTemplate } from '../output/types';
+import type { ZenIR, BundlePlan } from '../ir/types';
+/**
+ * Finalized output ready for browser
+ */
+export interface FinalizedOutput {
+    html: string;
+    js: string;
+    npmImports: string;
+    styles: string[];
+    hasErrors: boolean;
+    errors: string[];
+    /** Compiler-emitted bundling plan. If present, bundling MUST occur. If absent, bundling MUST NOT occur. */
+    bundlePlan?: BundlePlan;
+}
+/**
+ * Finalize compiler output (Native Bridge)
+ *
+ * @param ir - Intermediate representation
+ * @param compiled - Compiled template
+ * @returns Finalized output
+ */
+export declare function finalizeOutput(ir: ZenIR, compiled: CompiledTemplate): Promise<FinalizedOutput>;
+/**
+ * Generate final output with error handling
+ */
+export declare function finalizeOutputOrThrow(ir: ZenIR, compiled: CompiledTemplate): Promise<FinalizedOutput>;

package/dist/finalize/finalizeOutput.js

@@ -0,0 +1,62 @@
+/**
+ * Finalize Output
+ *
+ * NATIVE BRIDGE: Delegates ALL finalization (Phase 8/9/10) to Rust (`native/compiler-native/src/finalize.rs`).
+ */
+let native;
+try {
+    try {
+        native = require('../../native/compiler-native');
+    }
+    catch {
+        native = require('../../native/compiler-native/index.js');
+    }
+}
+catch (e) {
+    // Bridge load handled elsewhere
+}
+/**
+ * Finalize compiler output (Native Bridge)
+ *
+ * @param ir - Intermediate representation
+ * @param compiled - Compiled template
+ * @returns Finalized output
+ */
+export async function finalizeOutput(ir, compiled) {
+    if (native && native.finalizeOutputNative) {
+        try {
+            const result = native.finalizeOutputNative(ir, compiled);
+            return {
+                html: result.html,
+                js: result.js,
+                npmImports: result.npmImports,
+                styles: result.styles,
+                hasErrors: result.hasErrors,
+                errors: result.errors,
+                bundlePlan: result.bundlePlan
+            };
+        }
+        catch (error) {
+            return {
+                html: '',
+                js: '',
+                npmImports: '',
+                styles: [],
+                hasErrors: true,
+                errors: [`Native finalization failed: ${error.message}`]
+            };
+        }
+    }
+    throw new Error(`[Zenith Native] Finalize bridge unavailable - cannot finalize ${ir.filePath}`);
+}
+/**
+ * Generate final output with error handling
+ */
+export async function finalizeOutputOrThrow(ir, compiled) {
+    const output = await finalizeOutput(ir, compiled);
+    if (output.hasErrors) {
+        const errorMessage = output.errors.join('\n\n');
+        throw new Error(`Compilation failed:\n\n${errorMessage}`);
+    }
+    return output;
+}

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 './finalizeOutput';
+/**
+ * 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;');
+}