@zenithbuild/core 1.2.2 → 1.2.3

package/compiler/finalize/finalizeOutput.ts

@@ -1,192 +0,0 @@
-/**
- * Finalize Output
- * 
- * Phase 8/9/10: Generate final compiled HTML + JS output with hydration markers
- * 
- * Ensures:
- * - All expressions are replaced with hydration markers
- * - HTML contains no raw {expression} syntax
- * - JS runtime is ready for browser execution
- * - Hydration markers are correctly placed
- */
-
-import type { CompiledTemplate } from '../output/types'
-import type { ZenIR } from '../ir/types'
-import { transformIR, type RuntimeCode } from '../runtime/transformIR'
-import { validateExpressionsOrThrow } from '../validate/validateExpressions'
-
-/**
- * Finalized output ready for browser
- */
-export interface FinalizedOutput {
-  html: string
-  js: string
-  styles: string[]
-  hasErrors: boolean
-  errors: string[]
-}
-
-/**
- * Finalize compiler output
- * 
- * This is the final step that ensures:
- * 1. All expressions are validated
- * 2. HTML contains no raw expressions
- * 3. JS runtime is generated
- * 4. Output is ready for browser
- * 
- * @param ir - Intermediate representation
- * @param compiled - Compiled template from Phase 2
- * @returns Finalized output
- */
-export async function finalizeOutput(
-  ir: ZenIR,
-  compiled: CompiledTemplate
-): Promise<FinalizedOutput> {
-  const errors: string[] = []
-
-  // 1. Validate all expressions (Phase 8/9/10 requirement)
-  try {
-    validateExpressionsOrThrow(ir.template.expressions, ir.filePath)
-  } catch (error: any) {
-    if (error instanceof Error) {
-      errors.push(error.message)
-      return {
-        html: '',
-        js: '',
-        styles: [],
-        hasErrors: true,
-        errors
-      }
-    }
-  }
-
-  // 2. Verify HTML contains no raw expressions
-  const htmlErrors = verifyNoRawExpressions(compiled.html, ir.filePath)
-  if (htmlErrors.length > 0) {
-    errors.push(...htmlErrors)
-    return {
-      html: '',
-      js: '',
-      styles: [],
-      hasErrors: true,
-      errors
-    }
-  }
-
-  // 3. Generate runtime code
-  let runtimeCode: RuntimeCode
-  try {
-    runtimeCode = await transformIR(ir)
-  } catch (error: any) {
-    errors.push(`Runtime generation failed: ${error.message}`)
-    return {
-      html: '',
-      js: '',
-      styles: [],
-      hasErrors: true,
-      errors
-    }
-  }
-
-  // 4. Combine HTML and JS
-  const finalHTML = compiled.html
-  const finalJS = runtimeCode.bundle
-
-  return {
-    html: finalHTML,
-    js: finalJS,
-    styles: compiled.styles,
-    hasErrors: false,
-    errors: []
-  }
-}
-
-/**
- * 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 = htmlToCheck.match(rawExpressionPattern)
-
-  if (matches && matches.length > 0) {
-    // Filter out false positives
-    const actualExpressions = matches.filter(match => {
-      // Exclude if it's in a comment
-      if (html.includes(`<!--${match}`) || html.includes(`${match}-->`)) {
-        return false
-      }
-      // Exclude if it's in a data attribute value (already processed)
-      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` +
-        `File: ${filePath}\n` +
-        `All expressions must be replaced with hydration markers (data-zen-text, data-zen-attr-*)`
-      )
-    }
-  }
-
-  return errors
-}
-
-/**
- * Generate final output with error handling
- * 
- * Throws if validation fails (build must fail on errors)
- */
-export async function finalizeOutputOrThrow(
-  ir: ZenIR,
-  compiled: CompiledTemplate
-): Promise<FinalizedOutput> {
-  const output = await 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/finalize/generateFinalBundle.ts

@@ -1,82 +0,0 @@
-/**
- * Generate Final Bundle
- * 
- * Phase 8/9/10: Generate final browser-ready bundle
- * 
- * Combines:
- * - Compiled HTML
- * - Runtime JS
- * - Expression functions
- * - Event bindings
- * - Style injection
- */
-
-import type { FinalizedOutput } from './finalizeOutput'
-import type { RuntimeCode } from '../runtime/transformIR'
-
-/**
- * Generate final bundle code
- * 
- * This is the complete JavaScript bundle that will execute in the browser.
- * All expressions are pre-compiled - no template parsing at runtime.
- */
-export function generateFinalBundle(finalized: FinalizedOutput): string {
-  return `// Zenith Compiled Bundle (Phase 8/9/10)
-// Generated at compile time - no .zen parsing in browser
-// All expressions are pre-compiled - deterministic output
-
-${finalized.js}
-
-// Bundle complete - ready for browser execution
-`
-}
-
-/**
- * Generate HTML with inline script
- */
-export function generateHTMLWithScript(
-  html: string,
-  jsBundle: string,
-  styles: string[]
-): string {
-  // Inject styles as <style> tags
-  const styleTags = styles.map(style => `<style>${escapeHTML(style)}</style>`).join('\n')
-  
-  // Inject JS bundle as inline script
-  const scriptTag = `<script>${jsBundle}</script>`
-  
-  // Find </head> or <body> to inject styles
-  // Find </body> to inject script
-  let result = html
-  
-  if (styleTags) {
-    if (result.includes('</head>')) {
-      result = result.replace('</head>', `${styleTags}\n</head>`)
-    } else if (result.includes('<body')) {
-      result = result.replace('<body', `${styleTags}\n<body`)
-    }
-  }
-  
-  if (scriptTag) {
-    if (result.includes('</body>')) {
-      result = result.replace('</body>', `${scriptTag}\n</body>`)
-    } else {
-      result += scriptTag
-    }
-  }
-  
-  return result
-}
-
-/**
- * Escape HTML for safe embedding
- */
-function escapeHTML(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#039;')
-}
-

package/compiler/index.ts

@@ -1,83 +0,0 @@
-import { readFileSync } from 'fs'
-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'
-
-/**
- * Compile a .zen file into IR and CompiledTemplate
- */
-export async function compileZen(filePath: string): Promise<{
-  ir: ZenIR
-  compiled: CompiledTemplate
-  finalized?: FinalizedOutput
-}> {
-  const source = readFileSync(filePath, 'utf-8')
-  return compileZenSource(source, filePath)
-}
-
-/**
- * Compile Zen source string into IR and CompiledTemplate
- */
-export async function compileZenSource(
-  source: string,
-  filePath: string,
-  options?: {
-    componentsDir?: string
-  }
-): Promise<{
-  ir: ZenIR
-  compiled: CompiledTemplate
-  finalized?: FinalizedOutput
-}> {
-  // Parse template
-  const template = parseTemplate(source, filePath)
-
-  // Parse script
-  const script = parseScript(source)
-
-  // Parse styles
-  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi
-  const styles: StyleIR[] = []
-  let match
-  while ((match = styleRegex.exec(source)) !== null) {
-    if (match[1]) styles.push({ raw: match[1].trim() })
-  }
-
-  let ir: ZenIR = {
-    filePath,
-    template,
-    script,
-    // componentScripts: [],
-    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 = await finalizeOutputOrThrow(ir, compiled)
-    return { ir, compiled, finalized }
-  } catch (error: any) {
-    throw new Error(`Failed to finalize output for ${filePath}:\\n${error.message}`)
-  }
-}
-

package/compiler/ir/types.ts

@@ -1,174 +0,0 @@
-/**
- * Zenith Intermediate Representation (IR)
- * 
- * Phase 1: Parse & Extract
- * This IR represents the parsed structure of a .zen file
- * without any runtime execution or transformation.
- */
-
-/**
- * Structured ES module import metadata
- * Parsed from component scripts, used for deterministic bundling
- */
-export interface ScriptImport {
-  source: string         // Module specifier, e.g. 'gsap'
-  specifiers: string     // Import clause, e.g. '{ gsap }' or 'gsap' or ''
-  typeOnly: boolean      // TypeScript type-only import
-  sideEffect: boolean    // Side-effect import (no specifiers)
-}
-
-/**
- * Component Script IR - represents a component's script block
- * Used for collecting and bundling component scripts
- */
-export type ComponentScriptIR = {
-  name: string                           // Component name (e.g., 'HeroSection')
-  script: string                         // Raw script content
-  props: string[]                        // Declared props
-  scriptAttributes: Record<string, string>  // Script attributes (setup, lang)
-  imports: ScriptImport[]                // Parsed npm imports for bundling
-}
-
-export type ZenIR = {
-  filePath: string
-  template: TemplateIR
-  script: ScriptIR | null
-  styles: StyleIR[]
-  componentScripts?: ComponentScriptIR[]  // Scripts from used components
-}
-
-export type TemplateIR = {
-  raw: string
-  nodes: TemplateNode[]
-  expressions: ExpressionIR[]
-}
-
-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'
-  tag: string
-  attributes: AttributeIR[]
-  children: TemplateNode[]
-  location: SourceLocation
-  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
-  location: SourceLocation
-}
-
-export type ExpressionNode = {
-  type: 'expression'
-  expression: string
-  location: SourceLocation
-  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
-  location: SourceLocation
-  loopContext?: LoopContext  // Phase 7: Loop context for expressions inside map iterations
-}
-
-/**
- * Loop context for expressions inside map iterations
- * Phase 7: Tracks loop variables (e.g., todo, index) for expressions inside .map() calls
- */
-export type LoopContext = {
-  variables: string[]  // e.g., ['todo', 'index'] for todoItems.map((todo, index) => ...)
-  mapSource?: string   // The array being mapped, e.g., 'todoItems'
-}
-
-export type ExpressionIR = {
-  id: string
-  code: string
-  location: SourceLocation
-}
-
-export type ScriptIR = {
-  raw: string
-  attributes: Record<string, string>
-}
-
-export type StyleIR = {
-  raw: string
-}
-
-export type SourceLocation = {
-  line: number
-  column: number
-}
-
-

package/compiler/output/types.ts

@@ -1,48 +0,0 @@
-/**
- * Compiled Template Output Types
- * 
- * Phase 2: Transform IR → Static HTML + Runtime Bindings
- * Phase 8: Extended with fragment binding types (loop, conditional, optional)
- */
-
-import type { TemplateNode } from '../ir/types'
-
-export type CompiledTemplate = {
-  html: string
-  bindings: Binding[]
-  scripts: string | null
-  styles: string[]
-}
-
-export type Binding = {
-  id: string
-  type: 'text' | 'attribute' | 'loop' | 'conditional' | 'optional'
-  target: string  // e.g., "data-zen-text" or "class" for attribute bindings
-  expression: string  // The original expression code
-  location?: {
-    line: number
-    column: number
-  }
-  loopContext?: LoopContext  // Phase 7: Loop context for expressions inside map iterations
-  loopMeta?: LoopMeta  // Phase 8: Metadata for loop bindings
-}
-
-/**
- * Loop binding metadata
- * Phase 8: Contains loop variable names and body template for runtime instantiation
- */
-export type LoopMeta = {
-  itemVar: string
-  indexVar?: string
-  bodyTemplate: TemplateNode[]
-}
-
-/**
- * Loop context for expressions inside map iterations
- * Phase 7: Tracks loop variables for runtime setter generation
- */
-export type LoopContext = {
-  variables: string[]  // e.g., ['todo', 'index']
-  mapSource?: string   // The array being mapped, e.g., 'todoItems'
-}
-

package/compiler/parse/detectMapExpressions.ts

@@ -1,102 +0,0 @@
-/**
- * Map Expression Detection
- * 
- * Phase 7: Detects .map() expressions and extracts loop context information
- * 
- * This module analyzes expression code to detect map expressions like:
- * - todoItems.map(todo => ...)
- * - notifications.map((n, index) => ...)
- * 
- * It extracts:
- * - The array source (todoItems, notifications)
- * - Loop variable names (todo, n, index)
- * - The map body/template
- */
-
-import type { ExpressionIR } from '../ir/types'
-
-/**
- * Detected map expression information
- */
-export interface MapExpressionInfo {
-  isMap: boolean
-  arraySource?: string      // e.g., 'todoItems'
-  itemVariable?: string     // e.g., 'todo'
-  indexVariable?: string    // e.g., 'index'
-  mapBody?: string          // The template/body inside the map
-  fullExpression?: string   // The full expression code
-}
-
-/**
- * Detect if an expression is a map expression and extract loop context
- * 
- * Patterns detected:
- * - arraySource.map(item => body)
- * - arraySource.map((item, index) => body)
- * - arraySource.map(item => (body))
- */
-export function detectMapExpression(expr: ExpressionIR): MapExpressionInfo {
-  const { code } = expr
-  
-  // Pattern: arraySource.map(item => body)
-  // Pattern: arraySource.map((item, index) => body)
-  // Pattern: arraySource.map(item => (body))
-  const mapPattern = /^(.+?)\.\s*map\s*\(\s*\(?([^)=,\s]+)(?:\s*,\s*([^)=,\s]+))?\s*\)?\s*=>\s*(.+?)\)?$/s
-  
-  const match = code.match(mapPattern)
-  if (!match) {
-    return { isMap: false }
-  }
-  
-  const arraySource = match[1]?.trim()
-  const itemVariable = match[2]?.trim()
-  const indexVariable = match[3]?.trim()
-  const mapBody = match[4]?.trim()
-  
-  if (!arraySource || !itemVariable || !mapBody) {
-    return { isMap: false }
-  }
-  
-  return {
-    isMap: true,
-    arraySource,
-    itemVariable,
-    indexVariable,
-    mapBody,
-    fullExpression: code
-  }
-}
-
-/**
- * Extract loop variables from a map expression
- * Returns array of variable names in order: [itemVariable, indexVariable?]
- */
-export function extractLoopVariables(mapInfo: MapExpressionInfo): string[] {
-  if (!mapInfo.isMap || !mapInfo.itemVariable) {
-    return []
-  }
-  
-  const vars = [mapInfo.itemVariable]
-  if (mapInfo.indexVariable) {
-    vars.push(mapInfo.indexVariable)
-  }
-  
-  return vars
-}
-
-/**
- * Check if an expression references a loop variable
- * Used to determine if an expression needs loop context
- */
-export function referencesLoopVariable(exprCode: string, loopVars: string[]): boolean {
-  for (const loopVar of loopVars) {
-    // Match variable references: loopVar.property, loopVar, etc.
-    // Use word boundaries to avoid partial matches
-    const pattern = new RegExp(`\\b${loopVar}\\b`)
-    if (pattern.test(exprCode)) {
-      return true
-    }
-  }
-  return false
-}
-