@zenithbuild/core 0.6.2 → 1.0.1

package/compiler/validate/invariants.ts

@@ -1,292 +0,0 @@
-/**
- * Invariant Validation
- * 
- * Compile-time checks that enforce Zenith's non-negotiable invariants.
- * If any invariant is violated, compilation fails immediately with a clear explanation.
- * 
- * INVARIANTS:
- * 1. Components are structural only — no reactive scopes, no state
- * 2. Reactivity is scope-owned — flows through components, never into them
- * 3. Slot projection preserves identity — loopContext is preserved or merged upward
- * 4. Attribute ownership belongs to usage — must be forwarded to semantic root
- * 5. All resolution is compile-time — no unresolved components
- * 6. Failure is a compiler error — no silent degradation
- */
-
-import type { ZenIR, TemplateNode, ElementNode, ComponentNode, LoopContext } from '../ir/types'
-import { InvariantError } from '../errors/compilerError'
-
-/**
- * Invariant Codes
- * 
- * Each invariant has a unique ID for tracking and documentation.
- */
-export const INVARIANT = {
-    LOOP_CONTEXT_LOST: 'INV001',
-    ATTRIBUTE_NOT_FORWARDED: 'INV002',
-    UNRESOLVED_COMPONENT: 'INV003',
-    REACTIVE_BOUNDARY: 'INV004',
-    TEMPLATE_TAG: 'INV005',
-    SLOT_ATTRIBUTE: 'INV006',
-    ORPHAN_COMPOUND: 'INV007',
-    NON_ENUMERABLE_JSX: 'INV008',
-} as const
-
-/**
- * Guarantee Messages
- * 
- * Human-readable explanations of what each invariant guarantees.
- */
-const GUARANTEES: Record<string, string> = {
-    [INVARIANT.LOOP_CONTEXT_LOST]:
-        'Slot content retains its original reactive scope. Expressions and event handlers continue to work after projection.',
-    [INVARIANT.ATTRIBUTE_NOT_FORWARDED]:
-        'Attributes passed to components are forwarded to the semantic root element.',
-    [INVARIANT.UNRESOLVED_COMPONENT]:
-        'All components are resolved at compile time. No runtime component discovery.',
-    [INVARIANT.REACTIVE_BOUNDARY]:
-        'Components are purely structural transforms. They do not create reactive scopes.',
-    [INVARIANT.TEMPLATE_TAG]:
-        'Named slots use compound component pattern (Card.Header), not <template> tags.',
-    [INVARIANT.SLOT_ATTRIBUTE]:
-        'Named slots use compound component pattern (Card.Header), not slot="" attributes.',
-    [INVARIANT.ORPHAN_COMPOUND]:
-        'Compound slot markers (Card.Header) must be direct children of their parent component.',
-    [INVARIANT.NON_ENUMERABLE_JSX]:
-        'JSX expressions must have statically enumerable output. The compiler must know all possible DOM shapes at compile time.',
-}
-
-/**
- * Validate all invariants on a compiled IR
- * 
- * Called after component resolution to ensure all invariants hold.
- * Throws InvariantError if any invariant is violated.
- */
-export function validateInvariants(ir: ZenIR, filePath: string): void {
-    validateNoUnresolvedComponents(ir.template.nodes, filePath)
-    // Additional invariant checks can be added here
-}
-
-/**
- * INV003: Validate that no unresolved components remain
- * 
- * After component resolution, all ComponentNode instances should be
- * resolved to ElementNode instances. If any remain, the compiler failed.
- */
-export function validateNoUnresolvedComponents(
-    nodes: TemplateNode[],
-    filePath: string
-): void {
-    for (const node of nodes) {
-        checkNodeForUnresolvedComponent(node, filePath)
-    }
-}
-
-function checkNodeForUnresolvedComponent(node: TemplateNode, filePath: string): void {
-    if (node.type === 'component') {
-        throw new InvariantError(
-            INVARIANT.UNRESOLVED_COMPONENT,
-            `Unresolved component: <${node.name}>. Component was not found or failed to resolve.`,
-            GUARANTEES[INVARIANT.UNRESOLVED_COMPONENT]!,
-            filePath,
-            node.location.line,
-            node.location.column
-        )
-    }
-
-    if (node.type === 'element') {
-        for (const child of node.children) {
-            checkNodeForUnresolvedComponent(child, filePath)
-        }
-    }
-}
-
-/**
- * INV005: Validate no <template> tags are used
- * 
- * Zenith uses compound component pattern for named slots.
- * <template> tags are a different mental model and are forbidden.
- */
-export function validateNoTemplateTags(
-    nodes: TemplateNode[],
-    filePath: string
-): void {
-    for (const node of nodes) {
-        checkNodeForTemplateTag(node, filePath)
-    }
-}
-
-function checkNodeForTemplateTag(node: TemplateNode, filePath: string): void {
-    if (node.type === 'element' && node.tag === 'template') {
-        throw new InvariantError(
-            INVARIANT.TEMPLATE_TAG,
-            `<template> tags are forbidden in Zenith. Use compound components (e.g., Card.Header) for named slots.`,
-            GUARANTEES[INVARIANT.TEMPLATE_TAG]!,
-            filePath,
-            node.location.line,
-            node.location.column
-        )
-    }
-
-    if (node.type === 'element') {
-        for (const child of node.children) {
-            checkNodeForTemplateTag(child, filePath)
-        }
-    }
-}
-
-/**
- * INV006: Validate no slot="" attributes are used
- * 
- * Zenith uses compound component pattern, not slot props.
- */
-export function validateNoSlotAttributes(
-    nodes: TemplateNode[],
-    filePath: string
-): void {
-    for (const node of nodes) {
-        checkNodeForSlotAttribute(node, filePath)
-    }
-}
-
-function checkNodeForSlotAttribute(node: TemplateNode, filePath: string): void {
-    if (node.type === 'element') {
-        const slotAttr = node.attributes.find(attr => attr.name === 'slot')
-        if (slotAttr) {
-            throw new InvariantError(
-                INVARIANT.SLOT_ATTRIBUTE,
-                `slot="${typeof slotAttr.value === 'string' ? slotAttr.value : '...'}" attribute is forbidden. Use compound components (e.g., Card.Header) for named slots.`,
-                GUARANTEES[INVARIANT.SLOT_ATTRIBUTE]!,
-                filePath,
-                slotAttr.location.line,
-                slotAttr.location.column
-            )
-        }
-
-        for (const child of node.children) {
-            checkNodeForSlotAttribute(child, filePath)
-        }
-    }
-
-    if (node.type === 'component') {
-        for (const child of node.children) {
-            checkNodeForSlotAttribute(child, filePath)
-        }
-    }
-}
-
-/**
- * INV001: Validate loopContext is preserved during slot projection
- * 
- * When slot content is moved from the usage site to the slot target,
- * the loopContext must be preserved so reactivity continues to work.
- * 
- * @param originalNodes - Nodes before slot projection
- * @param projectedNodes - Nodes after slot projection
- */
-export function validateLoopContextPreservation(
-    originalNodes: TemplateNode[],
-    projectedNodes: TemplateNode[],
-    filePath: string
-): void {
-    // Collect all loopContext from original nodes
-    const originalContexts = collectLoopContexts(originalNodes)
-
-    // Verify all contexts are still present in projected nodes
-    const projectedContexts = collectLoopContexts(projectedNodes)
-
-    for (const entry of Array.from(originalContexts.entries())) {
-        const [nodeId, context] = entry
-        const projected = projectedContexts.get(nodeId)
-        if (context && !projected) {
-            // loopContext was lost during projection
-            // This is a compiler bug, not a user error
-            throw new InvariantError(
-                INVARIANT.LOOP_CONTEXT_LOST,
-                `Reactive scope was lost during slot projection. This is a Zenith compiler bug.`,
-                GUARANTEES[INVARIANT.LOOP_CONTEXT_LOST]!,
-                filePath,
-                1, // We don't have precise location, use line 1
-                1
-            )
-        }
-    }
-}
-
-function collectLoopContexts(nodes: TemplateNode[]): Map<string, LoopContext | undefined> {
-    const contexts = new Map<string, LoopContext | undefined>()
-    let nodeId = 0
-
-    function visit(node: TemplateNode): void {
-        const id = `node_${nodeId++}`
-
-        if (node.type === 'expression') {
-            contexts.set(id, node.loopContext)
-        } else if (node.type === 'element') {
-            contexts.set(id, node.loopContext)
-            for (const attr of node.attributes) {
-                if (attr.loopContext) {
-                    contexts.set(`${id}_attr_${attr.name}`, attr.loopContext)
-                }
-            }
-            for (const child of node.children) {
-                visit(child)
-            }
-        } else if (node.type === 'component') {
-            contexts.set(id, node.loopContext)
-            for (const child of node.children) {
-                visit(child)
-            }
-        }
-    }
-
-    for (const node of nodes) {
-        visit(node)
-    }
-
-    return contexts
-}
-
-/**
- * INV007: Throw error for orphan compound slot markers
- * 
- * Called when a compound component (Card.Header) is found outside
- * its parent component context.
- */
-export function throwOrphanCompoundError(
-    componentName: string,
-    parentName: string,
-    filePath: string,
-    line: number,
-    column: number
-): never {
-    throw new InvariantError(
-        INVARIANT.ORPHAN_COMPOUND,
-        `<${componentName}> must be a direct child of <${parentName}>. Compound slot markers cannot be used outside their parent component.`,
-        GUARANTEES[INVARIANT.ORPHAN_COMPOUND]!,
-        filePath,
-        line,
-        column
-    )
-}
-
-/**
- * INV003: Throw error for unresolved component
- * 
- * Called when a component definition cannot be found.
- */
-export function throwUnresolvedComponentError(
-    componentName: string,
-    filePath: string,
-    line: number,
-    column: number
-): never {
-    throw new InvariantError(
-        INVARIANT.UNRESOLVED_COMPONENT,
-        `Component <${componentName}> not found. All components must be defined in the components directory.`,
-        GUARANTEES[INVARIANT.UNRESOLVED_COMPONENT]!,
-        filePath,
-        line,
-        column
-    )
-}

package/compiler/validate/validateExpressions.ts

@@ -1,168 +0,0 @@
-/**
- * Expression Validation
- * 
- * Phase 8/9/10: Compile-time validation of all expressions
- * 
- * Ensures all expressions are valid JavaScript and will not cause runtime errors.
- * Build fails immediately if any expression is invalid.
- */
-
-import type { ExpressionIR } from '../ir/types'
-import { CompilerError } from '../errors/compilerError'
-
-/**
- * Validation result
- */
-export interface ValidationResult {
-  valid: boolean
-  errors: CompilerError[]
-}
-
-/**
- * Validate all expressions in the IR
- * 
- * @param expressions - Array of expressions to validate
- * @param filePath - Source file path for error reporting
- * @returns Validation result with errors
- */
-export function validateExpressions(
-  expressions: ExpressionIR[],
-  filePath: string
-): ValidationResult {
-  const errors: CompilerError[] = []
-
-  for (const expr of expressions) {
-    const exprErrors = validateSingleExpression(expr, filePath)
-    errors.push(...exprErrors)
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors
-  }
-}
-
-/**
- * Validate a single expression
- */
-function validateSingleExpression(
-  expr: ExpressionIR,
-  filePath: string
-): CompilerError[] {
-  const errors: CompilerError[] = []
-  const { id, code, location } = expr
-
-  // Basic syntax validation using a safe approach
-  // We don't execute the code, just validate syntax
-  // Note: Expressions may contain JSX/HTML syntax (e.g., condition && <element>)
-  // which is not valid JavaScript but is valid in our expression language.
-  // We skip strict JavaScript validation for expressions that contain JSX.
-  
-  const hasJSX = /<[a-zA-Z]/.test(code) || /\/>/.test(code)
-  
-  if (!hasJSX) {
-    // Only validate JavaScript syntax if there's no JSX
-    // Note: Using Function constructor here is for syntax validation only (compile-time)
-    // This is safe because:
-    // 1. It's only called at compile time, not runtime
-    // 2. We're only checking syntax, not executing the code
-    // 3. The actual runtime uses pre-compiled functions, not Function constructor
-    try {
-      // Use Function constructor to validate syntax (doesn't execute)
-      // This is compile-time only - runtime never uses Function constructor
-      new Function('state', 'loaderData', 'props', 'stores', `return ${code}`)
-    } catch (error: any) {
-      errors.push(
-        new CompilerError(
-          `Invalid expression syntax: ${code}\n${error.message}`,
-          filePath,
-          location.line,
-          location.column
-        )
-      )
-    }
-  }
-  // If hasJSX, we skip JavaScript validation - JSX syntax is handled by the parser/runtime
-
-  // Check for dangerous patterns
-  if (code.includes('eval(') || code.includes('Function(') || code.includes('with (')) {
-    errors.push(
-      new CompilerError(
-        `Expression contains unsafe code: ${code}`,
-        filePath,
-        location.line,
-        location.column
-      )
-    )
-  }
-
-  // Check for undefined global references (basic heuristic)
-  // This is a simple check - can be enhanced with AST parsing
-  const globalPattern = /\b(window|document|console|globalThis)\./g
-  const matches = code.match(globalPattern)
-  if (matches && matches.length > 0) {
-    // Warn but don't fail - some global access might be intentional
-    // In a stricter mode, we could fail here
-  }
-
-  // Check for common syntax errors
-  const openBraces = (code.match(/\{/g) || []).length
-  const closeBraces = (code.match(/\}/g) || []).length
-  const openParens = (code.match(/\(/g) || []).length
-  const closeParens = (code.match(/\)/g) || []).length
-  const openBrackets = (code.match(/\[/g) || []).length
-  const closeBrackets = (code.match(/\]/g) || []).length
-
-  if (openBraces !== closeBraces) {
-    errors.push(
-      new CompilerError(
-        `Mismatched braces in expression: ${code}`,
-        filePath,
-        location.line,
-        location.column
-      )
-    )
-  }
-
-  if (openParens !== closeParens) {
-    errors.push(
-      new CompilerError(
-        `Mismatched parentheses in expression: ${code}`,
-        filePath,
-        location.line,
-        location.column
-      )
-    )
-  }
-
-  if (openBrackets !== closeBrackets) {
-    errors.push(
-      new CompilerError(
-        `Mismatched brackets in expression: ${code}`,
-        filePath,
-        location.line,
-        location.column
-      )
-    )
-  }
-
-  return errors
-}
-
-/**
- * Validate and throw if invalid
- * 
- * @throws CompilerError if any expression is invalid
- */
-export function validateExpressionsOrThrow(
-  expressions: ExpressionIR[],
-  filePath: string
-): void {
-  const result = validateExpressions(expressions, filePath)
-  
-  if (!result.valid && result.errors.length > 0) {
-    // Throw the first error (can be enhanced to collect all)
-    throw result.errors[0]
-  }
-}
-

package/core/config/index.ts

@@ -1,16 +0,0 @@
-/**
- * Zenith Config
- * 
- * Public exports for zenith/config
- */
-
-export { defineConfig } from './types';
-export type {
-    ZenithConfig,
-    ZenithPlugin,
-    PluginContext,
-    ContentSourceConfig,
-    ContentPluginOptions,
-    ContentItem
-} from './types';
-export { loadZenithConfig, hasZenithConfig } from './loader';

package/core/config/loader.ts

@@ -1,69 +0,0 @@
-/**
- * Zenith Config Loader
- * 
- * Loads zenith.config.ts from the project root
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import type { ZenithConfig } from './types';
-
-/**
- * Load zenith.config.ts from the project root
- * 
- * @param projectRoot - Absolute path to the project root
- * @returns Parsed ZenithConfig or empty config if not found
- */
-export async function loadZenithConfig(projectRoot: string): Promise<ZenithConfig> {
-    // Check for TypeScript config first, then JavaScript
-    const configPaths = [
-        path.join(projectRoot, 'zenith.config.ts'),
-        path.join(projectRoot, 'zenith.config.js'),
-        path.join(projectRoot, 'zenith.config.mjs'),
-    ];
-
-    let configPath: string | null = null;
-    for (const p of configPaths) {
-        if (fs.existsSync(p)) {
-            configPath = p;
-            break;
-        }
-    }
-
-    if (!configPath) {
-        // No config file found, return empty config
-        return { plugins: [] };
-    }
-
-    try {
-        // Use dynamic import to load the config
-        // Bun supports importing TS files directly
-        const configModule = await import(configPath);
-        const config = configModule.default || configModule;
-
-        // Validate basic structure
-        if (typeof config !== 'object' || config === null) {
-            console.warn(`[Zenith] Invalid config format in ${configPath}`);
-            return { plugins: [] };
-        }
-
-        return config as ZenithConfig;
-    } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`[Zenith] Failed to load config from ${configPath}:`, message);
-        return { plugins: [] };
-    }
-}
-
-/**
- * Check if a zenith.config.ts exists in the project
- */
-export function hasZenithConfig(projectRoot: string): boolean {
-    const configPaths = [
-        path.join(projectRoot, 'zenith.config.ts'),
-        path.join(projectRoot, 'zenith.config.js'),
-        path.join(projectRoot, 'zenith.config.mjs'),
-    ];
-
-    return configPaths.some(p => fs.existsSync(p));
-}

package/core/config/types.ts

@@ -1,89 +0,0 @@
-/**
- * Zenith Config Types
- * 
- * Configuration interfaces for zenith.config.ts
- */
-
-// ============================================
-// Content Plugin Types
-// ============================================
-
-/**
- * Configuration for a content source
- */
-export interface ContentSourceConfig {
-    /** Root directory relative to project root (e.g., "../zenith-docs" or "content") */
-    root: string;
-    /** Folders to include from the root (e.g., ["documentation"]). Defaults to all. */
-    include?: string[];
-    /** Folders to exclude from the root (e.g., ["changelog"]) */
-    exclude?: string[];
-}
-
-/**
- * Options for the content plugin
- */
-export interface ContentPluginOptions {
-    /** Named content sources mapped to their configuration */
-    sources?: Record<string, ContentSourceConfig>;
-    /** Legacy: Single content directory (deprecated, use sources instead) */
-    contentDir?: string;
-}
-
-// ============================================
-// Core Plugin Types
-// ============================================
-
-/**
- * Context passed to plugins during setup
- */
-export interface PluginContext {
-    /** Absolute path to project root */
-    projectRoot: string;
-    /** Set content data for the runtime */
-    setContentData: (data: Record<string, ContentItem[]>) => void;
-    /** Additional options passed from config */
-    options?: Record<string, unknown>;
-}
-
-/**
- * A content item loaded from a source
- */
-export interface ContentItem {
-    id?: string | number;
-    slug?: string | null;
-    collection?: string | null;
-    content?: string | null;
-    [key: string]: unknown;
-}
-
-/**
- * A Zenith plugin definition
- */
-export interface ZenithPlugin {
-    /** Unique plugin name */
-    name: string;
-    /** Setup function called during initialization */
-    setup: (ctx: PluginContext) => void | Promise<void>;
-    /** Plugin-specific configuration (preserved for reference) */
-    config?: unknown;
-}
-
-// ============================================
-// Main Config Types
-// ============================================
-
-/**
- * Zenith configuration object
- */
-export interface ZenithConfig {
-    /** List of plugins to load */
-    plugins?: ZenithPlugin[];
-}
-
-/**
- * Define a Zenith configuration with full type safety
- */
-export function defineConfig(config: ZenithConfig): ZenithConfig {
-    return config;
-}

package/core/plugins/index.ts

@@ -1,7 +0,0 @@
-/**
- * Zenith Plugins
- * 
- * Public exports for plugin system
- */
-
-export { PluginRegistry, createPluginContext } from './registry';