@zenithbuild/compiler 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import type { ZenIR } from './ir/types';
+import type { CompiledTemplate } from './output/types';
+import type { FinalizedOutput } from './finalize/finalizeOutput';
+import { parseZenFile } from './parseZenFile';
+/**
+ * Compile a .zen file into IR and CompiledTemplate
+ */
+export declare function compileZen(filePath: string): Promise<{
+    ir: ZenIR;
+    compiled: CompiledTemplate;
+    finalized?: FinalizedOutput;
+}>;
+/**
+ * Compile Zen source string into IR and CompiledTemplate
+ */
+export declare function compileZenSource(source: string, filePath: string, options?: {
+    componentsDir?: string;
+}): Promise<{
+    ir: ZenIR;
+    compiled: CompiledTemplate;
+    finalized?: FinalizedOutput;
+}>;
+export { parseZenFile };
+export { discoverLayouts } from './discovery/layouts';
+export { processLayout } from './transform/layoutProcessor';
+export { bundlePageScript } from './bundler';
+export { buildSSG } from './ssg-build';
+export { buildSPA } from './spa-build';
+export { generateBundleJS } from './runtime/bundle-generator';
+export { generateRouteDefinition } from '@zenithbuild/router/manifest';
+export { compileCss, compileCssAsync, resolveGlobalsCss } from './css';
+export { loadZenithConfig } from './core/config/loader';
+export { PluginRegistry, createPluginContext, getPluginDataByNamespace } from './core/plugins/registry';
+export { createBridgeAPI, runPluginHooks, collectHookReturns, buildRuntimeEnvelope, clearHooks } from './core/plugins/bridge';
+export type { HookContext } from './core/plugins/bridge';
+export type { BundlePlan, ExpressionIR, ZenIR, TemplateNode } from './ir/types';

package/dist/index.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'fs';
+import { transformTemplate } from './transform/transformTemplate';
+import { finalizeOutputOrThrow } from './finalize/finalizeOutput';
+import { validateIr } from './validate/invariants';
+import { parseZenFile } from './parseZenFile';
+/**
+ * Compile a .zen file into IR and CompiledTemplate
+ */
+export async function compileZen(filePath) {
+    const source = readFileSync(filePath, 'utf-8');
+    return compileZenSource(source, filePath);
+}
+/**
+ * Compile Zen source string into IR and CompiledTemplate
+ */
+export async function compileZenSource(source, filePath, options) {
+    // Parse with native bridge
+    let ir = parseZenFile(filePath, source);
+    // Resolve components if components directory is provided
+    if (options?.componentsDir) {
+        const { discoverComponents } = require('./discovery/componentDiscovery');
+        const { resolveComponentsInIR } = require('./transform/componentResolver');
+        // Component resolution may throw InvariantError — let it propagate
+        const components = discoverComponents(options.componentsDir);
+        ir = resolveComponentsInIR(ir, components);
+    }
+    // Validate all compiler invariants after resolution
+    // Throws InvariantError if any invariant is violated
+    validateIr(ir);
+    const compiled = transformTemplate(ir);
+    try {
+        const finalized = await finalizeOutputOrThrow(ir, compiled);
+        return { ir, compiled, finalized };
+    }
+    catch (error) {
+        throw new Error(`Failed to finalize output for ${filePath}:\n${error.message}`);
+    }
+}
+export { parseZenFile };
+// Feature exports
+export { discoverLayouts } from './discovery/layouts';
+export { processLayout } from './transform/layoutProcessor';
+export { bundlePageScript } from './bundler';
+export { buildSSG } from './ssg-build';
+export { buildSPA } from './spa-build';
+export { generateBundleJS } from './runtime/bundle-generator';
+export { generateRouteDefinition } from '@zenithbuild/router/manifest';
+export { compileCss, compileCssAsync, resolveGlobalsCss } from './css';
+export { loadZenithConfig } from './core/config/loader';
+export { PluginRegistry, createPluginContext, getPluginDataByNamespace } from './core/plugins/registry';
+export { createBridgeAPI, runPluginHooks, collectHookReturns, buildRuntimeEnvelope, clearHooks } from './core/plugins/bridge';

package/dist/ir/types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 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;
+}
+/**
+ * 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[];
+};
+export type ZenIR = {
+    filePath: string;
+    template: TemplateIR;
+    script: ScriptIR | null;
+    styles: StyleIR[];
+    componentScripts?: ComponentScriptIR[];
+    pageBindings?: 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>;
+};
+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,30 @@
+/**
+ * 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;
+};

package/dist/output/types.js

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

package/dist/parse/detectMapExpressions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Map Expression Detection
+ *
+ * Phase 7: Detects .map() expressions and extracts loop context information
+ *
+ * This module analyzes expression code to detect map expressions like:
+ * - todoItems.map(todo => ...)
+ * - notifications.map((n, index) => ...)
+ *
+ * It extracts:
+ * - The array source (todoItems, notifications)
+ * - Loop variable names (todo, n, index)
+ * - The map body/template
+ */
+import type { ExpressionIR } from '../ir/types';
+/**
+ * Detected map expression information
+ */
+export interface MapExpressionInfo {
+    isMap: boolean;
+    arraySource?: string;
+    itemVariable?: string;
+    indexVariable?: string;
+    mapBody?: string;
+    fullExpression?: string;
+}
+/**
+ * Detect if an expression is a map expression and extract loop context
+ *
+ * Patterns detected:
+ * - arraySource.map(item => body)
+ * - arraySource.map((item, index) => body)
+ * - arraySource.map(item => (body))
+ */
+export declare function detectMapExpression(expr: ExpressionIR): MapExpressionInfo;
+/**
+ * Extract loop variables from a map expression
+ * Returns array of variable names in order: [itemVariable, indexVariable?]
+ */
+export declare function extractLoopVariables(mapInfo: MapExpressionInfo): string[];
+/**
+ * Check if an expression references a loop variable
+ * Used to determine if an expression needs loop context
+ */
+export declare function referencesLoopVariable(exprCode: string, loopVars: string[]): boolean;

package/dist/parse/detectMapExpressions.js

@@ -0,0 +1,77 @@
+/**
+ * Map Expression Detection
+ *
+ * Phase 7: Detects .map() expressions and extracts loop context information
+ *
+ * This module analyzes expression code to detect map expressions like:
+ * - todoItems.map(todo => ...)
+ * - notifications.map((n, index) => ...)
+ *
+ * It extracts:
+ * - The array source (todoItems, notifications)
+ * - Loop variable names (todo, n, index)
+ * - The map body/template
+ */
+/**
+ * Detect if an expression is a map expression and extract loop context
+ *
+ * Patterns detected:
+ * - arraySource.map(item => body)
+ * - arraySource.map((item, index) => body)
+ * - arraySource.map(item => (body))
+ */
+export function detectMapExpression(expr) {
+    const { code } = expr;
+    // Pattern: arraySource.map(item => body)
+    // Pattern: arraySource.map((item, index) => body)
+    // Pattern: arraySource.map(item => (body))
+    const mapPattern = /^(.+?)\.\s*map\s*\(\s*\(?([^)=,\s]+)(?:\s*,\s*([^)=,\s]+))?\s*\)?\s*=>\s*(.+?)\)?$/s;
+    const match = code.match(mapPattern);
+    if (!match) {
+        return { isMap: false };
+    }
+    const arraySource = match[1]?.trim();
+    const itemVariable = match[2]?.trim();
+    const indexVariable = match[3]?.trim();
+    const mapBody = match[4]?.trim();
+    if (!arraySource || !itemVariable || !mapBody) {
+        return { isMap: false };
+    }
+    return {
+        isMap: true,
+        arraySource,
+        itemVariable,
+        indexVariable,
+        mapBody,
+        fullExpression: code
+    };
+}
+/**
+ * Extract loop variables from a map expression
+ * Returns array of variable names in order: [itemVariable, indexVariable?]
+ */
+export function extractLoopVariables(mapInfo) {
+    if (!mapInfo.isMap || !mapInfo.itemVariable) {
+        return [];
+    }
+    const vars = [mapInfo.itemVariable];
+    if (mapInfo.indexVariable) {
+        vars.push(mapInfo.indexVariable);
+    }
+    return vars;
+}
+/**
+ * Check if an expression references a loop variable
+ * Used to determine if an expression needs loop context
+ */
+export function referencesLoopVariable(exprCode, loopVars) {
+    for (const loopVar of loopVars) {
+        // Match variable references: loopVar.property, loopVar, etc.
+        // Use word boundaries to avoid partial matches
+        const pattern = new RegExp(`\\b${loopVar}\\b`);
+        if (pattern.test(exprCode)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/parse/parseScript.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Script Parser
+ *
+ * Extracts <script> blocks from .zen files
+ * Phase 1: Only extracts raw content, no evaluation
+ */
+import type { ScriptIR } from '../ir/types';
+export declare function parseScript(html: string): ScriptIR | null;

package/dist/parse/parseScript.js

@@ -0,0 +1,36 @@
+/**
+ * Script Parser
+ *
+ * Extracts <script> blocks from .zen files
+ * Phase 1: Only extracts raw content, no evaluation
+ */
+export function parseScript(html) {
+    const scripts = [];
+    const attributes = {};
+    const scriptRegex = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+    let match;
+    while ((match = scriptRegex.exec(html)) !== null) {
+        const attrString = match[1] || '';
+        const content = match[2] || '';
+        // Parse attributes
+        const attrRegex = /([a-z0-9-]+)(?:=(?:"([^"]*)"|'([^']*)'|([^>\s]+)))?/gi;
+        let attrMatch;
+        while ((attrMatch = attrRegex.exec(attrString)) !== null) {
+            const name = attrMatch[1];
+            if (name) {
+                const value = attrMatch[2] || attrMatch[3] || attrMatch[4] || 'true';
+                attributes[name] = value;
+            }
+        }
+        if (content) {
+            scripts.push(content.trim());
+        }
+    }
+    if (scripts.length === 0) {
+        return null;
+    }
+    return {
+        raw: scripts.join('\n\n'),
+        attributes
+    };
+}

package/dist/parse/parseTemplate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Template Parser
+ *
+ * Parses HTML template and extracts expressions
+ * Phase 1: Only extracts, does not execute
+ */
+import type { TemplateIR } from '../ir/types';
+/**
+ * Parse template from HTML string
+ */
+export declare function parseTemplate(html: string, filePath: string): TemplateIR;