@zenithbuild/core 0.1.0

package/compiler/test/validate-test.ts

@@ -0,0 +1,104 @@
+/**
+ * Test Cases for Expression Validation
+ * 
+ * Phase 8/9/10: Tests that invalid expressions fail the build
+ */
+
+import { validateExpressions, validateExpressionsOrThrow } from '../validate/validateExpressions'
+import type { ExpressionIR } from '../ir/types'
+
+/**
+ * Test valid expressions
+ */
+function testValidExpressions() {
+  const validExpressions: ExpressionIR[] = [
+    {
+      id: 'expr_0',
+      code: 'user.name',
+      location: { line: 10, column: 5 }
+    },
+    {
+      id: 'expr_1',
+      code: 'count + 1',
+      location: { line: 11, column: 8 }
+    },
+    {
+      id: 'expr_2',
+      code: 'isActive ? "on" : "off"',
+      location: { line: 12, column: 12 }
+    }
+  ]
+  
+  const result = validateExpressions(validExpressions, 'test.zen')
+  console.assert(result.valid === true, 'Valid expressions should pass validation')
+  console.assert(result.errors.length === 0, 'Valid expressions should have no errors')
+  console.log('✅ Valid expressions test passed')
+}
+
+/**
+ * Test invalid expressions
+ */
+function testInvalidExpressions() {
+  const invalidExpressions: ExpressionIR[] = [
+    {
+      id: 'expr_0',
+      code: 'user.name}', // Mismatched brace
+      location: { line: 10, column: 5 }
+    }
+  ]
+  
+  const result = validateExpressions(invalidExpressions, 'test.zen')
+  console.assert(result.valid === false, 'Invalid expressions should fail validation')
+  console.assert(result.errors.length > 0, 'Invalid expressions should have errors')
+  console.log('✅ Invalid expressions test passed')
+}
+
+/**
+ * Test unsafe code detection
+ */
+function testUnsafeCode() {
+  const unsafeExpressions: ExpressionIR[] = [
+    {
+      id: 'expr_0',
+      code: 'eval("alert(1)")',
+      location: { line: 10, column: 5 }
+    }
+  ]
+  
+  const result = validateExpressions(unsafeExpressions, 'test.zen')
+  console.assert(result.valid === false, 'Unsafe code should fail validation')
+  console.assert(result.errors.length > 0, 'Unsafe code should have errors')
+  console.log('✅ Unsafe code detection test passed')
+}
+
+/**
+ * Test validateExpressionsOrThrow
+ */
+function testThrowOnInvalid() {
+  const invalidExpressions: ExpressionIR[] = [
+    {
+      id: 'expr_0',
+      code: 'user.name}', // Mismatched brace
+      location: { line: 10, column: 5 }
+    }
+  ]
+  
+  try {
+    validateExpressionsOrThrow(invalidExpressions, 'test.zen')
+    console.assert(false, 'Should have thrown on invalid expressions')
+  } catch (error) {
+    console.assert(error instanceof Error, 'Should throw Error')
+    console.log('✅ Throw on invalid expressions test passed')
+  }
+}
+
+// Run tests
+if (require.main === module) {
+  console.log('Running validation tests...')
+  testValidExpressions()
+  testInvalidExpressions()
+  testUnsafeCode()
+  testThrowOnInvalid()
+  console.log('✅ All validation tests passed!')
+}
+

package/compiler/transform/generateBindings.ts

@@ -0,0 +1,47 @@
+/**
+ * Generate Bindings
+ * 
+ * This module is handled by transformNode, but kept here for future extensibility
+ */
+
+import type { Binding } from '../output/types'
+
+/**
+ * Validate bindings structure
+ */
+export function validateBindings(bindings: Binding[]): void {
+  for (const binding of bindings) {
+    if (!binding.id || !binding.type || !binding.target || !binding.expression) {
+      throw new Error(`Invalid binding: ${JSON.stringify(binding)}`)
+    }
+    
+    if (binding.type !== 'text' && binding.type !== 'attribute') {
+      throw new Error(`Invalid binding type: ${binding.type}`)
+    }
+    
+    if (binding.type === 'text' && binding.target !== 'data-zen-text') {
+      throw new Error(`Text binding must have target 'data-zen-text', got: ${binding.target}`)
+    }
+    
+    if (binding.type === 'attribute' && !binding.target.startsWith('data-zen-attr-')) {
+      // This is handled in transformNode, but validate here too
+      // Actually, the target should be the attribute name (e.g., "class")
+      // and we prepend "data-zen-attr-" when generating HTML
+      // So this validation is correct
+    }
+  }
+}
+
+/**
+ * Sort bindings by location for deterministic output
+ */
+export function sortBindings(bindings: Binding[]): Binding[] {
+  return [...bindings].sort((a, b) => {
+    if (!a.location || !b.location) return 0
+    if (a.location.line !== b.location.line) {
+      return a.location.line - b.location.line
+    }
+    return a.location.column - b.location.column
+  })
+}
+

package/compiler/transform/generateHTML.ts

@@ -0,0 +1,28 @@
+/**
+ * Generate Static HTML from Transformed Nodes
+ * 
+ * This generates pure HTML with no expressions or runtime code
+ */
+
+import type { TemplateNode } from '../ir/types'
+import { transformNode } from './transformNode'
+
+/**
+ * Generate HTML string from template nodes
+ */
+export function generateHTML(
+  nodes: TemplateNode[],
+  expressions: any[]
+): { html: string; bindings: any[] } {
+  let html = ''
+  const allBindings: any[] = []
+  
+  for (const node of nodes) {
+    const { html: nodeHtml, bindings } = transformNode(node, expressions)
+    html += nodeHtml
+    allBindings.push(...bindings)
+  }
+  
+  return { html, bindings: allBindings }
+}
+

package/compiler/transform/transformNode.ts

@@ -0,0 +1,126 @@
+/**
+ * Transform Template Nodes
+ * 
+ * Transforms IR nodes into HTML strings and collects bindings
+ */
+
+import type { TemplateNode, ElementNode, TextNode, ExpressionNode, ExpressionIR, LoopContext } from '../ir/types'
+import type { Binding } from '../output/types'
+
+let bindingIdCounter = 0
+
+function generateBindingId(): string {
+  return `exp_${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 = generateBindingId()
+        // 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}"></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 = generateBindingId()
+            // 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}>`
+      }
+    }
+  }
+  
+  const html = transform(node, parentLoopContext)
+  return { html, bindings }
+}
+
+/**
+ * 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

@@ -0,0 +1,38 @@
+/**
+ * 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/validateExpressions.ts

@@ -0,0 +1,168 @@
+/**
+ * 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/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Zenith Core Runtime
+ * 
+ * This is the foundational layer of the Zenith framework, providing:
+ * - Reactive primitives (signals, state, effects, memos)
+ * - Lifecycle hooks (onMount, onUnmount)
+ * 
+ * Design principles:
+ * - Auto-tracked reactivity (no dependency arrays)
+ * - No VDOM or render loops
+ * - Runtime-agnostic (works in browser, SSR, tests)
+ * - Hybrid naming: internal `zen*` + public clean names
+ * 
+ * @example
+ * ```ts
+ * // Using clean names (recommended for application code)
+ * import { signal, effect, onMount } from 'zenith/core'
+ * 
+ * const count = signal(0)
+ * 
+ * effect(() => {
+ *   console.log('Count:', count())
+ * })
+ * 
+ * onMount(() => {
+ *   console.log('Mounted!')
+ * })
+ * ```
+ * 
+ * @example
+ * ```ts
+ * // Using explicit zen* names (for library/internal code)
+ * import { zenSignal, zenEffect, zenOnMount } from 'zenith/core'
+ * 
+ * const count = zenSignal(0)
+ * zenEffect(() => console.log(count()))
+ * zenOnMount(() => console.log('Ready'))
+ * ```
+ * 
+ * @example
+ * ```ts
+ * // For navigation, import from router
+ * import { navigate, isActive } from 'zenith/router'
+ * 
+ * navigate('/about')
+ * if (isActive('/blog')) {
+ *   // Handle active state
+ * }
+ * ```
+ */
+
+// ============================================
+// Reactivity Primitives
+// ============================================
+
+// Explicit zen* exports (internal naming)
+export {
+  zenSignal,
+  zenState,
+  zenEffect,
+  zenMemo,
+  zenRef,
+  zenBatch,
+  zenUntrack
+} from './reactivity'
+
+// Types
+export type {
+  Signal,
+  Memo,
+  Ref,
+  EffectFn,
+  DisposeFn,
+  Subscriber,
+  TrackingContext
+} from './reactivity'
+
+// Clean name exports (public DX)
+export {
+  signal,
+  state,
+  effect,
+  memo,
+  ref,
+  batch,
+  untrack
+} from './reactivity'
+
+// Internal tracking utilities (advanced use)
+export {
+  trackDependency,
+  notifySubscribers,
+  getCurrentContext,
+  pushContext,
+  popContext,
+  cleanupContext,
+  runUntracked,
+  startBatch,
+  endBatch,
+  isBatching
+} from './reactivity'
+
+// ============================================
+// Lifecycle Hooks
+// ============================================
+
+// Explicit zen* exports (internal naming)
+export {
+  zenOnMount,
+  zenOnUnmount
+} from './lifecycle'
+
+// Clean name exports (public DX)
+export {
+  onMount,
+  onUnmount
+} from './lifecycle'
+
+// Types
+export type {
+  MountCallback,
+  UnmountCallback
+} from './lifecycle'
+
+// Internal lifecycle utilities (for component system)
+export {
+  triggerMount,
+  triggerUnmount,
+  executeUnmountCallbacks,
+  getIsMounted,
+  getUnmountCallbackCount,
+  resetMountState,
+  resetUnmountState
+} from './lifecycle'
+

package/core/lifecycle/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Zenith Lifecycle Hooks
+ * 
+ * This module exports lifecycle hooks for component mount/unmount events.
+ * These are effect wrappers that integrate with the component lifecycle system.
+ * 
+ * Exports both explicit `zen*` names (internal) and clean aliases (public DX).
+ */
+
+// Import lifecycle hooks
+import {
+  zenOnMount as _zenOnMount,
+  triggerMount,
+  triggerUnmount,
+  getIsMounted,
+  resetMountState,
+  type MountCallback
+} from './zen-mount'
+
+import {
+  zenOnUnmount as _zenOnUnmount,
+  executeUnmountCallbacks,
+  getUnmountCallbackCount,
+  resetUnmountState,
+  type UnmountCallback
+} from './zen-unmount'
+
+// Re-export with explicit names
+export const zenOnMount = _zenOnMount
+export const zenOnUnmount = _zenOnUnmount
+
+// Re-export utilities
+export {
+  triggerMount,
+  triggerUnmount,
+  getIsMounted,
+  resetMountState,
+  executeUnmountCallbacks,
+  getUnmountCallbackCount,
+  resetUnmountState
+}
+
+// Re-export types
+export type { MountCallback, UnmountCallback }
+
+// Public DX aliases - clean names
+export const onMount = _zenOnMount
+export const onUnmount = _zenOnUnmount
+