@zenithbuild/core 0.4.2 → 0.4.4

package/cli/commands/dev.ts

@@ -90,6 +90,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     function compilePageInMemory(pagePath: string): CompiledPage | null {
         try {
             const layoutsDir = path.join(pagesDir, '../layouts')
+            const componentsDir = path.join(pagesDir, '../components')
             const layouts = discoverLayouts(layoutsDir)
             const source = fs.readFileSync(pagePath, 'utf-8')
 
@@ -98,7 +99,9 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
             if (layoutToUse) processedSource = processLayout(source, layoutToUse)
 
-            const result = compileZenSource(processedSource, pagePath)
+            const result = compileZenSource(processedSource, pagePath, {
+                componentsDir: fs.existsSync(componentsDir) ? componentsDir : undefined
+            })
             if (!result.finalized) throw new Error('Compilation failed')
 
             const routeDef = generateRouteDefinition(pagePath, pagesDir)

package/compiler/discovery/componentDiscovery.ts

@@ -0,0 +1,174 @@
+/**
+ * Component Discovery
+ * 
+ * Discovers and catalogs components in a Zenith project
+ * Similar to layout discovery but for reusable components
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { parseZenFile } from '../parse/parseZenFile'
+import type { TemplateNode } from '../ir/types'
+
+export interface SlotDefinition {
+    name: string | null  // null = default slot, string = named slot
+    location: {
+        line: number
+        column: number
+    }
+}
+
+export interface ComponentMetadata {
+    name: string          // Component name (e.g., "Card", "Button")
+    path: string          // Absolute path to .zen file
+    template: string      // Raw template HTML
+    nodes: TemplateNode[] // Parsed template nodes
+    slots: SlotDefinition[]
+    props: string[]       // Declared props
+    styles: string[]      // Raw CSS from <style> blocks
+    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 function discoverComponents(baseDir: string): Map<string, ComponentMetadata> {
+    const components = new Map<string, ComponentMetadata>()
+
+    // Check if components directory exists
+    if (!fs.existsSync(baseDir)) {
+        return components
+    }
+
+    // Recursively find all .zen files
+    const zenFiles = findZenFiles(baseDir)
+
+    for (const filePath of zenFiles) {
+        try {
+            const metadata = parseComponentFile(filePath)
+            if (metadata) {
+                components.set(metadata.name, metadata)
+            }
+        } catch (error: any) {
+            console.warn(`[Zenith] Failed to parse component ${filePath}: ${error.message}`)
+        }
+    }
+
+    return components
+}
+
+/**
+ * Recursively find all .zen files in a directory
+ */
+function findZenFiles(dir: string): string[] {
+    const files: string[] = []
+
+    if (!fs.existsSync(dir)) {
+        return files
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name)
+
+        if (entry.isDirectory()) {
+            files.push(...findZenFiles(fullPath))
+        } else if (entry.isFile() && entry.name.endsWith('.zen')) {
+            files.push(fullPath)
+        }
+    }
+
+    return files
+}
+
+/**
+ * Parse a component file and extract metadata
+ */
+function parseComponentFile(filePath: string): ComponentMetadata | null {
+    const ir = parseZenFile(filePath)
+
+    // Extract component name from filename
+    const basename = path.basename(filePath, '.zen')
+    const componentName = basename
+
+    // Extract slots from template
+    const slots = extractSlots(ir.template.nodes)
+
+    // Extract props from script attributes
+    const props = ir.script?.attributes['props']?.split(',').map(p => p.trim()) || []
+
+    // Extract raw CSS from styles
+    const styles = ir.styles.map(s => s.raw)
+
+    return {
+        name: componentName,
+        path: filePath,
+        template: ir.template.raw,
+        nodes: ir.template.nodes,
+        slots,
+        props,
+        styles,
+        hasScript: ir.script !== null,
+        hasStyles: ir.styles.length > 0
+    }
+}
+
+/**
+ * Extract slot definitions from template nodes
+ */
+function extractSlots(nodes: TemplateNode[]): SlotDefinition[] {
+    const slots: SlotDefinition[] = []
+
+    function traverse(node: TemplateNode) {
+        if (node.type === 'element') {
+            // Check if this is a <slot> tag
+            if (node.tag === 'slot') {
+                // Extract slot name from attributes
+                const nameAttr = node.attributes.find(attr => attr.name === 'name')
+                const slotName = typeof nameAttr?.value === 'string' ? nameAttr.value : null
+
+                slots.push({
+                    name: slotName,
+                    location: node.location
+                })
+            }
+
+            // Traverse children
+            for (const child of node.children) {
+                traverse(child)
+            }
+        } else if (node.type === 'component') {
+            // Also traverse component children
+            for (const child of node.children) {
+                traverse(child)
+            }
+        }
+    }
+
+    for (const node of nodes) {
+        traverse(node)
+    }
+
+    return slots
+}
+
+/**
+ * Check if a tag name represents a component (starts with uppercase)
+ */
+export function isComponentTag(tagName: string): boolean {
+    return tagName.length > 0 && tagName[0] !== undefined && tagName[0] === tagName[0].toUpperCase()
+}
+
+/**
+ * Get component metadata by name
+ */
+export function getComponent(
+    components: Map<string, ComponentMetadata>,
+    name: string
+): ComponentMetadata | undefined {
+    return components.get(name)
+}

package/compiler/errors/compilerError.ts

@@ -22,3 +22,35 @@ export class CompilerError extends Error {
   }
 }
 
+/**
+ * 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: string
+  guarantee: string
+
+  constructor(
+    invariantId: string,
+    message: string,
+    guarantee: string,
+    file: string,
+    line: number,
+    column: number
+  ) {
+    super(`[${invariantId}] ${message}\n\n  Zenith Guarantee: ${guarantee}`, file, line, column)
+    this.name = 'InvariantError'
+    this.invariantId = invariantId
+    this.guarantee = guarantee
+  }
+
+  override toString(): string {
+    return `${this.file}:${this.line}:${this.column} [${this.invariantId}] ${this.message}`
+  }
+}
+

package/compiler/finalize/finalizeOutput.ts

@@ -106,17 +106,29 @@ export function finalizeOutput(
  * Verify HTML contains no raw {expression} syntax
  * 
  * This is a critical check - browser must never see raw expressions
+ * 
+ * Excludes:
+ * - Content inside <pre>, <code> tags (display code samples)
+ * - Content that looks like HTML tags (from entity decoding)
+ * - Comments
+ * - Data attributes
  */
 function verifyNoRawExpressions(html: string, filePath: string): string[] {
   const errors: string[] = []
-  
+
+  // Remove content inside <pre> and <code> tags before checking
+  // These are code samples that may contain { } legitimately
+  let htmlToCheck = html
+    .replace(/<pre[^>]*>[\s\S]*?<\/pre>/gi, '')
+    .replace(/<code[^>]*>[\s\S]*?<\/code>/gi, '')
+
   // Check for raw {expression} patterns (not data-zen-* attributes)
   // Allow data-zen-text, data-zen-attr-* but not raw { }
   const rawExpressionPattern = /\{[^}]*\}/g
-  const matches = html.match(rawExpressionPattern)
-  
+  const matches = htmlToCheck.match(rawExpressionPattern)
+
   if (matches && matches.length > 0) {
-    // Filter out false positives (comments, data attributes, etc.)
+    // Filter out false positives
     const actualExpressions = matches.filter(match => {
       // Exclude if it's in a comment
       if (html.includes(`<!--${match}`) || html.includes(`${match}-->`)) {
@@ -126,10 +138,27 @@ function verifyNoRawExpressions(html: string, filePath: string): string[] {
       if (match.includes('data-zen-')) {
         return false
       }
+      // Exclude if it contains HTML tags (likely from entity decoding in display content)
+      // Real expressions don't start with < inside braces
+      if (match.match(/^\{[\s]*</)) {
+        return false
+      }
+      // Exclude if it looks like display content containing HTML (spans, divs, etc)
+      if (/<[a-zA-Z]/.test(match)) {
+        return false
+      }
+      // Exclude CSS-like content (common in style attributes)
+      if (match.includes(';') && match.includes(':')) {
+        return false
+      }
+      // Exclude if it's a single closing tag pattern (from multiline display)
+      if (/^\{[\s]*<\//.test(match)) {
+        return false
+      }
       // This looks like a raw expression
       return true
     })
-    
+
     if (actualExpressions.length > 0) {
       errors.push(
         `HTML contains raw expressions that were not compiled: ${actualExpressions.join(', ')}\n` +
@@ -138,7 +167,7 @@ function verifyNoRawExpressions(html: string, filePath: string): string[] {
       )
     }
   }
-  
+
   return errors
 }
 
@@ -152,12 +181,12 @@ export function finalizeOutputOrThrow(
   compiled: CompiledTemplate
 ): FinalizedOutput {
   const output = finalizeOutput(ir, compiled)
-  
+
   if (output.hasErrors) {
     const errorMessage = output.errors.join('\n\n')
     throw new Error(`Compilation failed:\n\n${errorMessage}`)
   }
-  
+
   return output
 }
 

package/compiler/index.ts

@@ -3,6 +3,8 @@ import { parseTemplate } from './parse/parseTemplate'
 import { parseScript } from './parse/parseScript'
 import { transformTemplate } from './transform/transformTemplate'
 import { finalizeOutputOrThrow } from './finalize/finalizeOutput'
+import { validateInvariants } from './validate/invariants'
+import { InvariantError } from './errors/compilerError'
 import type { ZenIR, StyleIR } from './ir/types'
 import type { CompiledTemplate } from './output/types'
 import type { FinalizedOutput } from './finalize/finalizeOutput'
@@ -22,7 +24,13 @@ export function compileZen(filePath: string): {
 /**
  * Compile Zen source string into IR and CompiledTemplate
  */
-export function compileZenSource(source: string, filePath: string): {
+export function compileZenSource(
+  source: string,
+  filePath: string,
+  options?: {
+    componentsDir?: string
+  }
+): {
   ir: ZenIR
   compiled: CompiledTemplate
   finalized?: FinalizedOutput
@@ -34,27 +42,40 @@ export function compileZenSource(source: string, filePath: string): {
   const script = parseScript(source)
 
   // Parse styles
-  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi
+  const styleRegex = /\u003cstyle[^\u003e]*\u003e([\s\S]*?)\u003c\/style\u003e/gi
   const styles: StyleIR[] = []
   let match
   while ((match = styleRegex.exec(source)) !== null) {
     if (match[1]) styles.push({ raw: match[1].trim() })
   }
 
-  const ir: ZenIR = {
+  let ir: ZenIR = {
     filePath,
     template,
     script,
     styles
   }
 
+  // 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
+  validateInvariants(ir, filePath)
+
   const compiled = transformTemplate(ir)
 
   try {
     const finalized = finalizeOutputOrThrow(ir, compiled)
     return { ir, compiled, finalized }
   } catch (error: any) {
-    throw new Error(`Failed to finalize output for ${filePath}:\n${error.message}`)
+    throw new Error(`Failed to finalize output for ${filePath}:\\n${error.message}`)
   }
 }
-

package/compiler/ir/types.ts

@@ -23,6 +23,10 @@ export type TemplateNode =
   | ElementNode
   | TextNode
   | ExpressionNode
+  | ComponentNode
+  | ConditionalFragmentNode  // JSX ternary: {cond ? <A /> : <B />}
+  | OptionalFragmentNode     // JSX logical AND: {cond && <A />}
+  | LoopFragmentNode         // JSX map: {items.map(i => <li>...</li>)}
 
 export type ElementNode = {
   type: 'element'
@@ -33,6 +37,15 @@ export type ElementNode = {
   loopContext?: LoopContext  // Phase 7: Inherited loop context from parent map expressions
 }
 
+export type ComponentNode = {
+  type: 'component'
+  name: string
+  attributes: AttributeIR[]
+  children: TemplateNode[]
+  location: SourceLocation
+  loopContext?: LoopContext
+}
+
 export type TextNode = {
   type: 'text'
   value: string
@@ -46,6 +59,58 @@ export type ExpressionNode = {
   loopContext?: LoopContext  // Phase 7: Loop context for expressions inside map iterations
 }
 
+/**
+ * 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           // The condition expression code
+  consequent: TemplateNode[]  // Precompiled "true" branch
+  alternate: TemplateNode[]   // Precompiled "false" branch
+  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           // The condition expression code
+  fragment: TemplateNode[]    // Precompiled fragment
+  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              // Array expression (e.g., 'items')
+  itemVar: string             // Loop variable (e.g., 'item')
+  indexVar?: string           // Optional index variable
+  body: TemplateNode[]        // Precompiled loop body template
+  location: SourceLocation
+  loopContext: LoopContext    // Extended with this loop's variables
+}
+
 export type AttributeIR = {
   name: string
   value: string | ExpressionIR
@@ -82,3 +147,4 @@ export type SourceLocation = {
   column: number
 }
 
+

package/compiler/parse/parseTemplate.ts

@@ -7,10 +7,12 @@
 
 import { parse, parseFragment } from 'parse5'
 import type { TemplateIR, TemplateNode, ElementNode, TextNode, ExpressionNode, AttributeIR, ExpressionIR, SourceLocation, LoopContext } from '../ir/types'
-import { CompilerError } from '../errors/compilerError'
+import { CompilerError, InvariantError } from '../errors/compilerError'
 import { parseScript } from './parseScript'
 import { detectMapExpression, extractLoopVariables, referencesLoopVariable } from './detectMapExpressions'
 import { shouldAttachLoopContext, mergeLoopContext, extractLoopContextFromExpression } from './trackLoopContext'
+import { INVARIANT } from '../validate/invariants'
+import { lowerFragments } from '../transform/fragmentLowering'
 
 // Generate stable IDs for expressions
 let expressionIdCounter = 0
@@ -362,6 +364,29 @@ function parseNode(
     const location = getLocation(node, originalHtml)
     const tag = node.tagName?.toLowerCase() || node.nodeName
 
+    // Extract original tag name from source HTML to preserve casing (parse5 lowercases everything)
+    let originalTag = node.tagName || node.nodeName
+    if (node.sourceCodeLocation && node.sourceCodeLocation.startOffset !== undefined) {
+      const startOffset = node.sourceCodeLocation.startOffset
+      // Find the tag name in original HTML (after '<')
+      const tagMatch = originalHtml.slice(startOffset).match(/^<([a-zA-Z][a-zA-Z0-9._-]*)/)
+      if (tagMatch && tagMatch[1]) {
+        originalTag = tagMatch[1]
+      }
+    }
+
+    // INV005: <template> tags are forbidden — use compound components instead
+    if (tag === 'template') {
+      throw new InvariantError(
+        INVARIANT.TEMPLATE_TAG,
+        `<template> tags are forbidden in Zenith. Use compound components (e.g., Card.Header) for named slots.`,
+        'Named slots use compound component pattern (Card.Header), not <template> tags.',
+        'unknown', // filePath passed to parseTemplate
+        location.line,
+        location.column
+      )
+    }
+
     // Parse attributes
     const attributes: AttributeIR[] = []
     if (node.attrs) {
@@ -373,6 +398,18 @@ function parseNode(
           }
           : location
 
+        // INV006: slot="" attributes are forbidden — use compound components instead
+        if (attr.name === 'slot') {
+          throw new InvariantError(
+            INVARIANT.SLOT_ATTRIBUTE,
+            `slot="${attr.value || ''}" attribute is forbidden. Use compound components (e.g., Card.Header) for named slots.`,
+            'Named slots use compound component pattern (Card.Header), not slot="" attributes.',
+            'unknown',
+            attrLocation.line,
+            attrLocation.column
+          )
+        }
+
         // Handle :attr="expr" syntax (colon-prefixed reactive attributes)
         let attrName = attr.name
         let attrValue = attr.value || ''
@@ -474,13 +511,29 @@ function parseNode(
       }
     }
 
-    return {
-      type: 'element',
-      tag,
-      attributes,
-      children,
-      location,
-      loopContext: elementLoopContext  // Phase 7: Inherited loop context for child processing
+    // Check if this is a custom component (starts with uppercase)
+    const isComponent = originalTag.length > 0 && originalTag[0] === originalTag[0].toUpperCase()
+
+    if (isComponent) {
+      // This is a component node
+      return {
+        type: 'component',
+        name: originalTag,
+        attributes,
+        children,
+        location,
+        loopContext: elementLoopContext
+      }
+    } else {
+      // This is a regular HTML element
+      return {
+        type: 'element',
+        tag,
+        attributes,
+        children,
+        location,
+        loopContext: elementLoopContext
+      }
     }
   }
 
@@ -517,9 +570,13 @@ export function parseTemplate(html: string, filePath: string): TemplateIR {
       }
     }
 
+    // Phase 8: Lower JSX expressions to structural fragments
+    // This transforms expressions like {cond ? <A /> : <B />} into ConditionalFragmentNode
+    const loweredNodes = lowerFragments(nodes, filePath, expressions)
+
     return {
       raw: templateHtml,
-      nodes,
+      nodes: loweredNodes,
       expressions
     }
   } catch (error: any) {