@zenithbuild/core 0.4.2 → 0.4.4

package/compiler/transform/slotResolver.ts

@@ -0,0 +1,292 @@
+/**
+ * Slot Resolution - Compound Component Model
+ * 
+ * Resolves slots using compound component pattern (Card.Header, Card.Body)
+ * NOT template tags. This matches React/Astro semantics.
+ * 
+ * IMPORTANT: Slot content must preserve the parent reactive scope.
+ * Components are purely structural transforms - they don't create new reactive boundaries.
+ * 
+ * Example usage:
+ * <Card>
+ *   <Card.Header><h3>Title</h3></Card.Header>
+ *   <p>Body content goes to default slot</p>
+ *   <Card.Footer><Button>OK</Button></Card.Footer>
+ * </Card>
+ */
+
+import type { TemplateNode, ComponentNode, ElementNode, LoopContext } from '../ir/types'
+
+export interface ResolvedSlots {
+    default: TemplateNode[]
+    named: Map<string, TemplateNode[]>
+    // Preserve the parent's reactive scope for slot content
+    parentLoopContext?: LoopContext
+}
+
+/**
+ * Extract slots from component children using compound component pattern
+ * 
+ * Children named `ParentComponent.SlotName` become named slots.
+ * All other children go to the default slot.
+ * Preserves the parent's reactive scope (loopContext) for all slot content.
+ * 
+ * @param parentName - Name of the parent component (e.g., "Card")
+ * @param children - Child nodes from component usage
+ * @param parentLoopContext - The reactive scope from the parent (must be preserved)
+ */
+export function extractSlotsFromChildren(
+    parentName: string,
+    children: TemplateNode[],
+    parentLoopContext?: LoopContext
+): ResolvedSlots {
+    const defaultSlot: TemplateNode[] = []
+    const namedSlots = new Map<string, TemplateNode[]>()
+
+    for (const child of children) {
+        // Check if this is a compound component (e.g., Card.Header)
+        if (child.type === 'component') {
+            const compoundMatch = parseCompoundName(child.name, parentName)
+
+            if (compoundMatch) {
+                // This is a named slot (e.g., Card.Header -> "header")
+                const slotName = compoundMatch.toLowerCase()
+
+                if (!namedSlots.has(slotName)) {
+                    namedSlots.set(slotName, [])
+                }
+
+                // The compound component's children become the slot content
+                // Preserve parent's loopContext on each child
+                const scopedChildren = child.children.map(c =>
+                    rebindNodeToScope(c, parentLoopContext)
+                )
+                namedSlots.get(slotName)!.push(...scopedChildren)
+            } else {
+                // Regular component, goes to default slot
+                // Preserve parent's loopContext
+                defaultSlot.push(rebindNodeToScope(child, parentLoopContext))
+            }
+        } else {
+            // Elements, text, expressions go to default slot
+            // Preserve parent's loopContext
+            defaultSlot.push(rebindNodeToScope(child, parentLoopContext))
+        }
+    }
+
+    return {
+        default: defaultSlot,
+        named: namedSlots,
+        parentLoopContext
+    }
+}
+
+/**
+ * Rebind a node to the parent's reactive scope
+ * 
+ * This ensures that expressions and event bindings in slot content
+ * remain connected to the parent component's reactive graph.
+ * Components must be purely structural - they don't create new reactive boundaries.
+ */
+function rebindNodeToScope(node: TemplateNode, loopContext?: LoopContext): TemplateNode {
+    // If no parent scope to preserve, return as-is
+    if (!loopContext) {
+        return node
+    }
+
+    // Merge the parent's loopContext with existing loopContext
+    // Parent scope takes precedence to ensure reactivity flows through
+    switch (node.type) {
+        case 'expression':
+            return {
+                ...node,
+                loopContext: mergeLoopContext(node.loopContext, loopContext)
+            }
+
+        case 'element':
+            return {
+                ...node,
+                loopContext: mergeLoopContext(node.loopContext, loopContext),
+                attributes: node.attributes.map(attr => ({
+                    ...attr,
+                    loopContext: attr.loopContext
+                        ? mergeLoopContext(attr.loopContext, loopContext)
+                        : loopContext
+                })),
+                children: node.children.map(c => rebindNodeToScope(c, loopContext))
+            }
+
+        case 'component':
+            return {
+                ...node,
+                loopContext: mergeLoopContext(node.loopContext, loopContext),
+                children: node.children.map(c => rebindNodeToScope(c, loopContext))
+            }
+
+        case 'text':
+            // Text nodes don't have reactive bindings
+            return node
+
+        default:
+            return node
+    }
+}
+
+/**
+ * Merge two loop contexts, combining their variables
+ * Parent context variables take precedence (added last so they shadow)
+ */
+function mergeLoopContext(existing?: LoopContext, parent?: LoopContext): LoopContext | undefined {
+    if (!existing && !parent) return undefined
+    if (!existing) return parent
+    if (!parent) return existing
+
+    // Combine variables, parent variables shadow existing
+    const allVars = new Set([...existing.variables, ...parent.variables])
+
+    return {
+        variables: Array.from(allVars),
+        mapSource: parent.mapSource || existing.mapSource
+    }
+}
+
+/**
+ * Parse compound component name
+ * 
+ * Given "Card.Header" and parent "Card", returns "Header"
+ * Given "Card.Footer" and parent "Card", returns "Footer"
+ * Given "Button" and parent "Card", returns null (not a compound)
+ * 
+ * @param componentName - Full component name (e.g., "Card.Header")
+ * @param parentName - Parent component name (e.g., "Card")
+ * @returns Slot name or null if not a compound of this parent
+ */
+function parseCompoundName(componentName: string, parentName: string): string | null {
+    const prefix = `${parentName}.`
+
+    if (componentName.startsWith(prefix)) {
+        return componentName.slice(prefix.length)
+    }
+
+    return null
+}
+
+/**
+ * Resolve slots in component template nodes
+ * 
+ * Replaces <slot /> and <slot name="X" /> with children from resolved slots.
+ * All slot content is rebound to the parent's reactive scope.
+ */
+export function resolveSlots(
+    componentNodes: TemplateNode[],
+    slots: ResolvedSlots
+): TemplateNode[] {
+    const resolved: TemplateNode[] = []
+
+    for (const node of componentNodes) {
+        const result = resolveNode(node, slots)
+        if (Array.isArray(result)) {
+            resolved.push(...result)
+        } else {
+            resolved.push(result)
+        }
+    }
+
+    return resolved
+}
+
+/**
+ * Resolve a single node, replacing slot tags with content
+ * Ensures all slot content maintains the parent's reactive scope
+ */
+function resolveNode(
+    node: TemplateNode,
+    slots: ResolvedSlots
+): TemplateNode | TemplateNode[] {
+    if (node.type === 'element' && node.tag === 'slot') {
+        // This is a slot tag - replace it with children
+        const nameAttr = node.attributes.find(attr => attr.name === 'name')
+        const slotName = typeof nameAttr?.value === 'string' ? nameAttr.value : null
+
+        if (slotName) {
+            // Named slot
+            const namedChildren = slots.named.get(slotName.toLowerCase()) || []
+
+            // If no children provided and slot has fallback content, use fallback
+            if (namedChildren.length === 0 && node.children.length > 0) {
+                return node.children
+            }
+
+            // Return slot content (already scoped during extraction)
+            return namedChildren.length > 0 ? namedChildren : []
+        } else {
+            // Default slot
+            // If no children provided and slot has fallback content, use fallback
+            if (slots.default.length === 0 && node.children.length > 0) {
+                return node.children
+            }
+
+            // Return slot content (already scoped during extraction)
+            return slots.default
+        }
+    }
+
+    if (node.type === 'element') {
+        // Recursively resolve slots in children
+        const resolvedChildren: TemplateNode[] = []
+        for (const child of node.children) {
+            const result = resolveNode(child, slots)
+            if (Array.isArray(result)) {
+                resolvedChildren.push(...result)
+            } else {
+                resolvedChildren.push(result)
+            }
+        }
+
+        return {
+            ...node,
+            children: resolvedChildren
+        }
+    }
+
+    if (node.type === 'component') {
+        // Recursively resolve slots in component children
+        const resolvedChildren: TemplateNode[] = []
+        for (const child of node.children) {
+            const result = resolveNode(child, slots)
+            if (Array.isArray(result)) {
+                resolvedChildren.push(...result)
+            } else {
+                resolvedChildren.push(result)
+            }
+        }
+
+        return {
+            ...node,
+            children: resolvedChildren
+        }
+    }
+
+    // Text and expression nodes pass through unchanged
+    return node
+}
+
+/**
+ * Check if a node tree contains any slots
+ */
+export function hasSlots(nodes: TemplateNode[]): boolean {
+    function checkNode(node: TemplateNode): boolean {
+        if (node.type === 'element') {
+            if (node.tag === 'slot') {
+                return true
+            }
+            return node.children.some(checkNode)
+        }
+        if (node.type === 'component') {
+            return node.children.some(checkNode)
+        }
+        return false
+    }
+
+    return nodes.some(checkNode)
+}

package/compiler/validate/invariants.ts

@@ -0,0 +1,292 @@
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Core library for the Zenith framework",
   "license": "MIT",
   "type": "module",