@zenithbuild/core 1.2.2 → 1.2.4

package/compiler/transform/transformNode.ts

@@ -1,314 +0,0 @@
-/**
- * Transform Template Nodes
- * 
- * Transforms IR nodes into HTML strings and collects bindings
- * 
- * Phase 8: Supports fragment node types (loop-fragment, conditional-fragment, optional-fragment)
- */
-
-import type {
-  TemplateNode,
-  ElementNode,
-  TextNode,
-  ExpressionNode,
-  ExpressionIR,
-  LoopContext,
-  LoopFragmentNode,
-  ConditionalFragmentNode,
-  OptionalFragmentNode,
-  ComponentNode,
-  SourceLocation
-} from '../ir/types'
-import type { Binding } from '../output/types'
-import { InvariantError } from '../errors/compilerError'
-import { INVARIANT } from '../validate/invariants'
-
-let loopIdCounter = 0
-
-function generateLoopId(): string {
-  return `loop_${loopIdCounter++}`
-}
-
-let bindingIdCounter = 0
-
-function generateBindingId(): string {
-  return `expr_${bindingIdCounter++}`
-}
-
-/**
- * Transform a template node to HTML and collect bindings
- * Phase 7: Supports loop context propagation for map expressions
- */
-export function transformNode(
-  node: TemplateNode,
-  expressions: ExpressionIR[],
-  parentLoopContext?: LoopContext  // Phase 7: Loop context from parent map expressions
-): { html: string; bindings: Binding[] } {
-  const bindings: Binding[] = []
-
-  function transform(node: TemplateNode, loopContext?: LoopContext): string {
-    switch (node.type) {
-      case 'text':
-        return escapeHtml((node as TextNode).value)
-
-      case 'expression': {
-        const exprNode = node as ExpressionNode
-        // Find the expression in the expressions array
-        const expr = expressions.find(e => e.id === exprNode.expression)
-        if (!expr) {
-          throw new Error(`Expression ${exprNode.expression} not found`)
-        }
-
-        const bindingId = expr.id
-        // Phase 7: Use loop context from ExpressionNode if available, otherwise use passed context
-        const activeLoopContext = exprNode.loopContext || loopContext
-
-        bindings.push({
-          id: bindingId,
-          type: 'text',
-          target: 'data-zen-text',
-          expression: expr.code,
-          location: expr.location,
-          loopContext: activeLoopContext  // Phase 7: Attach loop context to binding
-        })
-
-        return `<span data-zen-text="${bindingId}" style="display: contents;"></span>`
-      }
-
-      case 'element': {
-        const elNode = node as ElementNode
-        const tag = elNode.tag
-
-        // Build attributes
-        const attrs: string[] = []
-        for (const attr of elNode.attributes) {
-          if (typeof attr.value === 'string') {
-            // Static attribute
-            const value = escapeHtml(attr.value)
-            attrs.push(`${attr.name}="${value}"`)
-          } else {
-            // Expression attribute
-            const expr = attr.value as ExpressionIR
-            const bindingId = expr.id
-            // Phase 7: Use loop context from AttributeIR if available, otherwise use element's loop context
-            const activeLoopContext = attr.loopContext || loopContext
-
-            bindings.push({
-              id: bindingId,
-              type: 'attribute',
-              target: attr.name,  // e.g., "class", "style"
-              expression: expr.code,
-              location: expr.location,
-              loopContext: activeLoopContext  // Phase 7: Attach loop context to binding
-            })
-
-            // Use data-zen-attr-{name} for attribute expressions
-            attrs.push(`data-zen-attr-${attr.name}="${bindingId}"`)
-          }
-        }
-
-        const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : ''
-
-        // Phase 7: Use loop context from ElementNode if available, otherwise use passed context
-        const activeLoopContext = elNode.loopContext || loopContext
-
-        // Transform children
-        const childrenHtml = elNode.children.map(child => transform(child, activeLoopContext)).join('')
-
-        // Self-closing tags
-        const voidElements = new Set([
-          'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
-          'link', 'meta', 'param', 'source', 'track', 'wbr'
-        ])
-
-        if (voidElements.has(tag.toLowerCase()) && childrenHtml === '') {
-          return `<${tag}${attrStr} />`
-        }
-
-        return `<${tag}${attrStr}>${childrenHtml}</${tag}>`
-      }
-
-      case 'loop-fragment': {
-        // Loop fragment: {items.map(item => <li>...</li>)}
-        // .map() is compile-time sugar, lowered to LoopFragmentNode
-        // For SSR/SSG, we render one instance of the body as a template
-        // The runtime will hydrate and expand this for each actual item
-        const loopNode = node as LoopFragmentNode
-        const loopId = generateLoopId()
-        const activeLoopContext = loopNode.loopContext || loopContext
-
-        // Create a binding for the loop expression
-        bindings.push({
-          id: loopId,
-          type: 'loop',
-          target: 'data-zen-loop',
-          expression: loopNode.source,
-          location: loopNode.location,
-          loopContext: activeLoopContext,
-          loopMeta: {
-            itemVar: loopNode.itemVar,
-            indexVar: loopNode.indexVar,
-            bodyTemplate: loopNode.body
-          }
-        })
-
-        // Generate the loop body template HTML
-        // For SSR, we render ONE visible instance of the body as a template/placeholder
-        // The runtime will clone this for each item in the array
-        const bodyHtml = loopNode.body.map(child => transform(child, activeLoopContext)).join('')
-
-        // Render container with body visible for SSR (not in hidden <template>)
-        // Runtime will clear and re-render with actual data
-        return `<div data-zen-loop="${loopId}" data-zen-source="${escapeHtml(loopNode.source)}" data-zen-item="${loopNode.itemVar}"${loopNode.indexVar ? ` data-zen-index="${loopNode.indexVar}"` : ''} style="display: contents;">${bodyHtml}</div>`
-      }
-
-      case 'conditional-fragment': {
-        // Conditional fragment: {cond ? <A /> : <B />}
-        // Both branches are pre-rendered, runtime toggles visibility
-        const condNode = node as ConditionalFragmentNode
-        const condId = generateBindingId()
-        const activeLoopContext = condNode.loopContext || loopContext
-
-        bindings.push({
-          id: condId,
-          type: 'conditional',
-          target: 'data-zen-cond',
-          expression: condNode.condition,
-          location: condNode.location,
-          loopContext: activeLoopContext
-        })
-
-        // Render both branches
-        const consequentHtml = condNode.consequent.map(child => transform(child, activeLoopContext)).join('')
-        const alternateHtml = condNode.alternate.map(child => transform(child, activeLoopContext)).join('')
-
-        return `<div data-zen-cond="${condId}" data-zen-cond-true style="display: contents;">${consequentHtml}</div><div data-zen-cond="${condId}" data-zen-cond-false style="display: none;">${alternateHtml}</div>`
-      }
-
-      case 'optional-fragment': {
-        // Optional fragment: {cond && <A />}
-        // Fragment is pre-rendered, runtime toggles mount/unmount
-        const optNode = node as OptionalFragmentNode
-        const optId = generateBindingId()
-        const activeLoopContext = optNode.loopContext || loopContext
-
-        bindings.push({
-          id: optId,
-          type: 'optional',
-          target: 'data-zen-opt',
-          expression: optNode.condition,
-          location: optNode.location,
-          loopContext: activeLoopContext
-        })
-
-        const fragmentHtml = optNode.fragment.map(child => transform(child, activeLoopContext)).join('')
-
-        return `<div data-zen-opt="${optId}" style="display: contents;">${fragmentHtml}</div>`
-      }
-
-      case 'component': {
-        // Component node - should have been resolved before reaching here
-        // This is a fallback for unresolved components
-        const compNode = node as ComponentNode
-        console.warn(`[Zenith] Unresolved component in transformNode: ${compNode.name}`)
-
-        // Render children as a fragment
-        const childrenHtml = compNode.children.map(child => transform(child, loopContext)).join('')
-        return `<!-- unresolved: ${compNode.name} -->${childrenHtml}`
-      }
-
-      default: {
-        // Handle any unknown node types
-        console.warn(`[Zenith] Unknown node type in transformNode: ${(node as any).type}`)
-        return ''
-      }
-    }
-  }
-
-  const html = transform(node, parentLoopContext)
-
-  // INV-EXPR-REG-001 Enforcement: Before emitting HTML, assert all bindings resolve
-  checkEveryBindingResolves(bindings, expressions)
-
-  return { html, bindings }
-}
-
-/**
- * INV-EXPR-REG-001: Assert every data-zen-* reference resolves to a registered expression
- */
-function checkEveryBindingResolves(bindings: Binding[], expressions: ExpressionIR[]): void {
-  const errorPrefix = `Compiler invariant violated: runtime expression used without registration. This is a compiler bug, not a user error.`
-
-  for (const binding of bindings) {
-    const exprId = binding.id
-    const resolved = expressions.find(e => e.id === exprId)
-
-    if (!resolved && binding.type !== 'loop') {
-      // Loop bindings might have a generated loopId that doesn't 
-      // exist in the expressions array, but they have a source expression ID
-    }
-
-    // Check loop source specifically
-    if (binding.type === 'loop') {
-      const sourceExprId = binding.expression
-      if (!sourceExprId.startsWith('expr_')) {
-        throw new InvariantError(
-          'INV-EXPR-REG-001',
-          `${errorPrefix}\nLoop fragment references invalid source expression: "${sourceExprId}"`,
-          'Loop fragments must reference a valid registered expression ID.',
-          'unknown', // transformNode doesn't have filePath, but we can't easily get it here without changing signature
-          binding.location?.line || 1,
-          binding.location?.column || 1
-        )
-      }
-
-      const sourceResolved = expressions.find(e => e.id === sourceExprId)
-      if (!sourceResolved) {
-        throw new InvariantError(
-          'INV-EXPR-REG-001',
-          `${errorPrefix}\nLoop source expression "${sourceExprId}" not found in registry.`,
-          'Every loop source must be registered as an ExpressionIR.',
-          'unknown',
-          binding.location?.line || 1,
-          binding.location?.column || 1
-        )
-      }
-    } else {
-      // General expression check
-      if (!exprId.startsWith('expr_')) {
-        throw new InvariantError(
-          'INV-EXPR-REG-001',
-          `${errorPrefix}\nBinding references invalid expression ID: "${exprId}"`,
-          'Every binding must reference a valid registered expression ID.',
-          'unknown',
-          binding.location?.line || 1,
-          binding.location?.column || 1
-        )
-      }
-
-      if (!resolved) {
-        throw new InvariantError(
-          'INV-EXPR-REG-001',
-          `${errorPrefix}\nExpression ID "${exprId}" not found in registry.`,
-          'Every binding must resolve to a registered expression.',
-          'unknown',
-          binding.location?.line || 1,
-          binding.location?.column || 1
-        )
-      }
-    }
-  }
-}
-
-/**
- * Escape HTML special characters
- */
-function escapeHtml(text: string): string {
-  return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;')
-}
-

package/compiler/transform/transformTemplate.ts

@@ -1,38 +0,0 @@
-/**
- * Transform Template IR to Compiled Template
- * 
- * Phase 2: Transform IR → Static HTML + Runtime Bindings
- */
-
-import type { ZenIR } from '../ir/types'
-import type { CompiledTemplate } from '../output/types'
-import { generateHTML } from './generateHTML'
-import { validateBindings, sortBindings } from './generateBindings'
-
-/**
- * Transform a ZenIR into CompiledTemplate
- */
-export function transformTemplate(ir: ZenIR): CompiledTemplate {
-  // Generate HTML and collect bindings
-  const { html, bindings } = generateHTML(ir.template.nodes, ir.template.expressions)
-  
-  // Validate bindings
-  validateBindings(bindings)
-  
-  // Sort bindings by location for deterministic output
-  const sortedBindings = sortBindings(bindings)
-  
-  // Extract scripts (raw content, pass through)
-  const scripts = ir.script ? ir.script.raw : null
-  
-  // Extract styles (raw content, pass through)
-  const styles = ir.styles.map(s => s.raw)
-  
-  return {
-    html,
-    bindings: sortedBindings,
-    scripts,
-    styles
-  }
-}
-

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
-    )
-}