@zenithbuild/core 0.4.7 → 0.6.0

package/cli/commands/dev.ts

@@ -1,5 +1,6 @@
 import path from 'path'
 import fs from 'fs'
+import os from 'os'
 import { serve, type ServerWebSocket } from 'bun'
 import { requireProject } from '../utils/project'
 import * as logger from '../utils/logger'
@@ -29,6 +30,53 @@ interface CompiledPage {
 
 const pageCache = new Map<string, CompiledPage>()
 
+/**
+ * Bundle page script using Bun's bundler to resolve npm imports at compile time.
+ * This allows ES module imports like `import { gsap } from 'gsap'` to work.
+ */
+async function bundlePageScript(script: string, projectRoot: string): Promise<string> {
+    // If no import statements, return as-is
+    if (!script.includes('import ')) {
+        return script
+    }
+
+    // Create a temporary file for bundling
+    const tempDir = os.tmpdir()
+    const tempFile = path.join(tempDir, `zenith-bundle-${Date.now()}.js`)
+
+    try {
+        // Write script to temp file
+        fs.writeFileSync(tempFile, script, 'utf-8')
+
+        // Use Bun.build to bundle with npm resolution
+        const result = await Bun.build({
+            entrypoints: [tempFile],
+            target: 'browser',
+            format: 'esm',
+            minify: false,
+            // Resolve modules from the project's node_modules
+            external: [], // Bundle everything
+        })
+
+        if (!result.success || !result.outputs[0]) {
+            console.error('[Zenith] Bundle errors:', result.logs)
+            return script // Fall back to original
+        }
+
+        // Get the bundled output
+        const bundledCode = await result.outputs[0].text()
+        return bundledCode
+    } catch (error: any) {
+        console.error('[Zenith] Failed to bundle page script:', error.message)
+        return script // Fall back to original
+    } finally {
+        // Clean up temp file
+        try {
+            fs.unlinkSync(tempFile)
+        } catch { }
+    }
+}
+
 export async function dev(options: DevOptions = {}): Promise<void> {
     const project = requireProject()
     const port = options.port || parseInt(process.env.PORT || '3000', 10)
@@ -105,7 +153,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     /**
      * Compile a .zen page in memory
      */
-    function compilePageInMemory(pagePath: string): CompiledPage | null {
+    async function compilePageInMemory(pagePath: string): Promise<CompiledPage | null> {
         try {
             const layoutsDir = path.join(pagesDir, '../layouts')
             const componentsDir = path.join(pagesDir, '../components')
@@ -117,16 +165,19 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
             if (layoutToUse) processedSource = processLayout(source, layoutToUse)
 
-            const result = compileZenSource(processedSource, pagePath, {
+            const result = await compileZenSource(processedSource, pagePath, {
                 componentsDir: fs.existsSync(componentsDir) ? componentsDir : undefined
             })
             if (!result.finalized) throw new Error('Compilation failed')
 
             const routeDef = generateRouteDefinition(pagePath, pagesDir)
 
+            // Bundle the script to resolve npm imports at compile time
+            const bundledScript = await bundlePageScript(result.finalized.js, rootDir)
+
             return {
                 html: result.finalized.html,
-                script: result.finalized.js,
+                script: bundledScript,
                 styles: result.finalized.styles,
                 route: routeDef.path,
                 lastModified: Date.now()
@@ -189,7 +240,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
     const server = serve({
         port,
-        fetch(req, server) {
+        async fetch(req, server) {
             const startTime = performance.now()
             const url = new URL(req.url)
             const pathname = url.pathname
@@ -246,7 +297,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
                 const stat = fs.statSync(pagePath)
 
                 if (!cached || stat.mtimeMs > cached.lastModified) {
-                    cached = compilePageInMemory(pagePath) || undefined
+                    cached = await compilePageInMemory(pagePath) || undefined
                     if (cached) pageCache.set(pagePath, cached)
                 }
                 const compileEnd = performance.now()
@@ -327,7 +378,8 @@ function generateDevHTML(page: CompiledPage, contentData: any = {}): string {
     // Escape </script> sequences in JSON content to prevent breaking the script tag
     const contentJson = JSON.stringify(contentData).replace(/<\//g, '<\\/')
     const contentTag = `<script>window.__ZENITH_CONTENT__ = ${contentJson};</script>`
-    const scriptTag = `<script>\n${page.script}\n</script>`
+    // Use type="module" to support ES6 imports from npm packages
+    const scriptTag = `<script type="module">\n${page.script}\n</script>`
     const allScripts = `${runtimeTag}\n${contentTag}\n${scriptTag}`
     return page.html.includes('</body>')
         ? page.html.replace('</body>', `${allScripts}\n</body>`)

package/compiler/finalize/finalizeOutput.ts

@@ -39,10 +39,10 @@ export interface FinalizedOutput {
  * @param compiled - Compiled template from Phase 2
  * @returns Finalized output
  */
-export function finalizeOutput(
+export async function finalizeOutput(
   ir: ZenIR,
   compiled: CompiledTemplate
-): FinalizedOutput {
+): Promise<FinalizedOutput> {
   const errors: string[] = []
 
   // 1. Validate all expressions (Phase 8/9/10 requirement)
@@ -77,7 +77,7 @@ export function finalizeOutput(
   // 3. Generate runtime code
   let runtimeCode: RuntimeCode
   try {
-    runtimeCode = transformIR(ir)
+    runtimeCode = await transformIR(ir)
   } catch (error: any) {
     errors.push(`Runtime generation failed: ${error.message}`)
     return {
@@ -176,11 +176,11 @@ function verifyNoRawExpressions(html: string, filePath: string): string[] {
  * 
  * Throws if validation fails (build must fail on errors)
  */
-export function finalizeOutputOrThrow(
+export async function finalizeOutputOrThrow(
   ir: ZenIR,
   compiled: CompiledTemplate
-): FinalizedOutput {
-  const output = finalizeOutput(ir, compiled)
+): Promise<FinalizedOutput> {
+  const output = await finalizeOutput(ir, compiled)
 
   if (output.hasErrors) {
     const errorMessage = output.errors.join('\n\n')

package/compiler/index.ts

@@ -12,11 +12,11 @@ import type { FinalizedOutput } from './finalize/finalizeOutput'
 /**
  * Compile a .zen file into IR and CompiledTemplate
  */
-export function compileZen(filePath: string): {
+export async function compileZen(filePath: string): Promise<{
   ir: ZenIR
   compiled: CompiledTemplate
   finalized?: FinalizedOutput
-} {
+}> {
   const source = readFileSync(filePath, 'utf-8')
   return compileZenSource(source, filePath)
 }
@@ -24,17 +24,17 @@ export function compileZen(filePath: string): {
 /**
  * Compile Zen source string into IR and CompiledTemplate
  */
-export function compileZenSource(
+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)
 
@@ -42,7 +42,7 @@ export function compileZenSource(
   const script = parseScript(source)
 
   // Parse styles
-  const styleRegex = /\u003cstyle[^\u003e]*\u003e([\s\S]*?)\u003c\/style\u003e/gi
+  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi
   const styles: StyleIR[] = []
   let match
   while ((match = styleRegex.exec(source)) !== null) {
@@ -74,9 +74,10 @@ export function compileZenSource(
   const compiled = transformTemplate(ir)
 
   try {
-    const finalized = finalizeOutputOrThrow(ir, compiled)
+    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

@@ -6,6 +6,17 @@
  * 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
@@ -15,6 +26,7 @@ export type ComponentScriptIR = {
   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 = {

package/compiler/parse/importTypes.ts

@@ -0,0 +1,78 @@
+/**
+ * Import Metadata Types
+ * 
+ * Structured types for deterministic import parsing.
+ * These types represent the parsed AST data for all ES module import forms.
+ * 
+ * Phase 1: Analysis only - no bundling, no resolution, no emission.
+ */
+
+/**
+ * Import kind classification covering all static import forms
+ */
+export type ImportKind =
+    | 'default'        // import x from "mod"
+    | 'named'          // import { a, b } from "mod"
+    | 'namespace'      // import * as x from "mod"
+    | 'side-effect'    // import "mod"
+    | 're-export'      // export { x } from "mod"
+    | 're-export-all'  // export * from "mod"
+
+/**
+ * Individual specifier within an import declaration
+ */
+export interface ImportSpecifier {
+    /** Local binding name used in this module */
+    local: string
+    /** Original exported name (differs from local when aliased: `import { x as y }`) */
+    imported?: string
+}
+
+/**
+ * Structured import metadata - parsed from AST
+ * 
+ * This is the canonical representation of an import declaration.
+ * All imports in source MUST appear as ParsedImport entries.
+ */
+export interface ParsedImport {
+    /** Classification of import type */
+    kind: ImportKind
+    /** Module specifier (e.g., 'gsap', './Button.zen', '../utils') */
+    source: string
+    /** Bound names and their aliases */
+    specifiers: ImportSpecifier[]
+    /** TypeScript type-only import (import type { ... }) */
+    isTypeOnly: boolean
+    /** Source location for error reporting */
+    location: {
+        start: number
+        end: number
+        line: number
+        column: number
+    }
+    /** Original source text of the import statement */
+    raw: string
+}
+
+/**
+ * Result of parsing all imports from a source file
+ */
+export interface ImportParseResult {
+    /** All parsed imports */
+    imports: ParsedImport[]
+    /** Source file path for error context */
+    filePath: string
+    /** Whether parsing completed successfully */
+    success: boolean
+    /** Any errors encountered during parsing */
+    errors: ImportParseError[]
+}
+
+/**
+ * Error encountered during import parsing
+ */
+export interface ImportParseError {
+    message: string
+    line?: number
+    column?: number
+}

package/compiler/parse/parseImports.ts

@@ -0,0 +1,309 @@
+/**
+ * Import Parser Module
+ * 
+ * Phase 1: Deterministic import parsing using Acorn AST.
+ * 
+ * This module parses JavaScript/TypeScript source code and extracts
+ * structured metadata for all import declarations. It does NOT:
+ * - Resolve imports
+ * - Bundle dependencies
+ * - Emit any code
+ * 
+ * All import analysis happens at compile time.
+ */
+
+import * as acorn from 'acorn'
+import type {
+    ParsedImport,
+    ImportSpecifier,
+    ImportKind,
+    ImportParseResult,
+    ImportParseError
+} from './importTypes'
+
+// Acorn AST node types (simplified for our use case)
+interface AcornNode {
+    type: string
+    start: number
+    end: number
+    loc?: {
+        start: { line: number; column: number }
+        end: { line: number; column: number }
+    }
+}
+
+interface ImportDeclarationNode extends AcornNode {
+    type: 'ImportDeclaration'
+    source: { value: string; raw: string }
+    specifiers: Array<{
+        type: 'ImportDefaultSpecifier' | 'ImportSpecifier' | 'ImportNamespaceSpecifier'
+        local: { name: string }
+        imported?: { name: string }
+    }>
+    importKind?: 'type' | 'value'
+}
+
+interface ExportNamedDeclarationNode extends AcornNode {
+    type: 'ExportNamedDeclaration'
+    source?: { value: string; raw: string }
+    specifiers: Array<{
+        type: 'ExportSpecifier'
+        local: { name: string }
+        exported: { name: string }
+    }>
+    exportKind?: 'type' | 'value'
+}
+
+interface ExportAllDeclarationNode extends AcornNode {
+    type: 'ExportAllDeclaration'
+    source: { value: string; raw: string }
+    exported?: { name: string }
+}
+
+interface ProgramNode extends AcornNode {
+    type: 'Program'
+    body: AcornNode[]
+}
+
+/**
+ * Parse an ImportDeclaration AST node into structured metadata
+ */
+function parseImportDeclaration(
+    node: ImportDeclarationNode,
+    source: string
+): ParsedImport {
+    const specifiers: ImportSpecifier[] = []
+    let kind: ImportKind = 'side-effect'
+
+    for (const spec of node.specifiers) {
+        if (spec.type === 'ImportDefaultSpecifier') {
+            kind = 'default'
+            specifiers.push({ local: spec.local.name })
+        } else if (spec.type === 'ImportNamespaceSpecifier') {
+            kind = 'namespace'
+            specifiers.push({ local: spec.local.name })
+        } else if (spec.type === 'ImportSpecifier') {
+            kind = 'named'
+            specifiers.push({
+                local: spec.local.name,
+                imported: spec.imported?.name !== spec.local.name
+                    ? spec.imported?.name
+                    : undefined
+            })
+        }
+    }
+
+    // If no specifiers, it's a side-effect import
+    if (node.specifiers.length === 0) {
+        kind = 'side-effect'
+    }
+
+    return {
+        kind,
+        source: node.source.value,
+        specifiers,
+        isTypeOnly: node.importKind === 'type',
+        location: {
+            start: node.start,
+            end: node.end,
+            line: node.loc?.start.line ?? 1,
+            column: node.loc?.start.column ?? 0
+        },
+        raw: source.slice(node.start, node.end)
+    }
+}
+
+/**
+ * Parse an ExportNamedDeclaration with source (re-export)
+ */
+function parseReExport(
+    node: ExportNamedDeclarationNode,
+    source: string
+): ParsedImport {
+    const specifiers: ImportSpecifier[] = node.specifiers.map(spec => ({
+        local: spec.exported.name,
+        imported: spec.local.name !== spec.exported.name
+            ? spec.local.name
+            : undefined
+    }))
+
+    return {
+        kind: 're-export',
+        source: node.source!.value,
+        specifiers,
+        isTypeOnly: node.exportKind === 'type',
+        location: {
+            start: node.start,
+            end: node.end,
+            line: node.loc?.start.line ?? 1,
+            column: node.loc?.start.column ?? 0
+        },
+        raw: source.slice(node.start, node.end)
+    }
+}
+
+/**
+ * Parse an ExportAllDeclaration (export * from "mod")
+ */
+function parseExportAll(
+    node: ExportAllDeclarationNode,
+    source: string
+): ParsedImport {
+    return {
+        kind: 're-export-all',
+        source: node.source.value,
+        specifiers: node.exported
+            ? [{ local: node.exported.name }]
+            : [],
+        isTypeOnly: false,
+        location: {
+            start: node.start,
+            end: node.end,
+            line: node.loc?.start.line ?? 1,
+            column: node.loc?.start.column ?? 0
+        },
+        raw: source.slice(node.start, node.end)
+    }
+}
+
+/**
+ * Parse all imports from a source file using Acorn AST parser
+ * 
+ * @param source - JavaScript/TypeScript source code
+ * @param filePath - Path to the source file (for error context)
+ * @returns ParsedImport[] - All import declarations found
+ * 
+ * @example
+ * const result = parseImports(`
+ *   import { gsap } from 'gsap';
+ *   import Button from './Button.zen';
+ * `, 'MyComponent.zen');
+ * 
+ * // result.imports[0].kind === 'named'
+ * // result.imports[0].source === 'gsap'
+ */
+export function parseImports(
+    source: string,
+    filePath: string
+): ImportParseResult {
+    const imports: ParsedImport[] = []
+    const errors: ImportParseError[] = []
+
+    // Strip TypeScript type annotations for parsing
+    // Acorn doesn't support TypeScript, so we handle type imports specially
+    const strippedSource = stripTypeAnnotations(source)
+
+    let ast: ProgramNode
+
+    try {
+        ast = acorn.parse(strippedSource, {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            locations: true
+        }) as unknown as ProgramNode
+    } catch (error: any) {
+        // Parse error - return with error info
+        return {
+            imports: [],
+            filePath,
+            success: false,
+            errors: [{
+                message: `Parse error: ${error.message}`,
+                line: error.loc?.line,
+                column: error.loc?.column
+            }]
+        }
+    }
+
+    // Walk the AST to find all import/export declarations
+    for (const node of ast.body) {
+        try {
+            if (node.type === 'ImportDeclaration') {
+                imports.push(parseImportDeclaration(
+                    node as ImportDeclarationNode,
+                    strippedSource
+                ))
+            } else if (node.type === 'ExportNamedDeclaration') {
+                const exportNode = node as ExportNamedDeclarationNode
+                // Only process re-exports (exports with a source)
+                if (exportNode.source) {
+                    imports.push(parseReExport(exportNode, strippedSource))
+                }
+            } else if (node.type === 'ExportAllDeclaration') {
+                imports.push(parseExportAll(
+                    node as ExportAllDeclarationNode,
+                    strippedSource
+                ))
+            }
+        } catch (error: any) {
+            errors.push({
+                message: `Failed to parse node: ${error.message}`,
+                line: (node as any).loc?.start?.line
+            })
+        }
+    }
+
+    return {
+        imports,
+        filePath,
+        success: errors.length === 0,
+        errors
+    }
+}
+
+/**
+ * Strip TypeScript-specific syntax that Acorn can't parse
+ * This is a simple preprocessing step for common patterns
+ */
+function stripTypeAnnotations(source: string): string {
+    // Handle `import type` by converting to regular import
+    // The isTypeOnly flag will be set based on the original text
+    let result = source
+
+    // Track which imports are type-only before stripping
+    const typeImportPattern = /import\s+type\s+/g
+    result = result.replace(typeImportPattern, 'import ')
+
+    // Strip inline type annotations in destructuring
+    // e.g., `import { type Foo, Bar }` -> `import { Foo, Bar }`
+    result = result.replace(/,\s*type\s+(\w+)/g, ', $1')
+    result = result.replace(/{\s*type\s+(\w+)/g, '{ $1')
+
+    // Strip type-only exports
+    result = result.replace(/export\s+type\s+{/g, 'export {')
+
+    return result
+}
+
+/**
+ * Check if the original source has a type import at the given position
+ */
+export function isTypeImportAtPosition(source: string, position: number): boolean {
+    const before = source.slice(Math.max(0, position - 20), position)
+    return /import\s+type\s*$/.test(before)
+}
+
+/**
+ * Categorize imports by their module source type
+ */
+export function categorizeImports(imports: ParsedImport[]): {
+    zenImports: ParsedImport[]      // .zen file imports (compile-time)
+    npmImports: ParsedImport[]      // Package imports (npm)
+    relativeImports: ParsedImport[] // Relative path imports
+} {
+    const zenImports: ParsedImport[] = []
+    const npmImports: ParsedImport[] = []
+    const relativeImports: ParsedImport[] = []
+
+    for (const imp of imports) {
+        if (imp.source.endsWith('.zen')) {
+            zenImports.push(imp)
+        } else if (imp.source.startsWith('./') || imp.source.startsWith('../')) {
+            relativeImports.push(imp)
+        } else {
+            npmImports.push(imp)
+        }
+    }
+
+    return { zenImports, npmImports, relativeImports }
+}

package/compiler/runtime/transformIR.ts

@@ -4,14 +4,14 @@
  * Phase 4: Transform ZenIR into runtime-ready JavaScript code with full reactivity
  */
 
-import type { ZenIR } from '../ir/types'
+import type { ZenIR, ScriptImport } from '../ir/types'
 import { generateExpressionWrappers } from './wrapExpression'
 import { generateDOMFunction } from './generateDOM'
 import { generateHydrationRuntime, generateExpressionRegistry } from './generateHydrationBundle'
 import { analyzeAllExpressions } from './dataExposure'
 import { generateNavigationRuntime } from './navigation'
 import { extractStateDeclarations, extractProps, transformStateDeclarations } from '../parse/scriptAnalysis'
-import { transformAllComponentScripts } from '../transform/componentScriptTransformer'
+import { transformAllComponentScripts, emitImports } from '../transform/componentScriptTransformer'
 
 export interface RuntimeCode {
   expressions: string  // Expression wrapper functions
@@ -26,7 +26,7 @@ export interface RuntimeCode {
 /**
  * Transform ZenIR into runtime JavaScript code
  */
-export function transformIR(ir: ZenIR): RuntimeCode {
+export async function transformIR(ir: ZenIR): Promise<RuntimeCode> {
   // Phase 6: Analyze expression dependencies for explicit data exposure
   const expressionDependencies = analyzeAllExpressions(
     ir.template.expressions,
@@ -71,8 +71,8 @@ export function transformIR(ir: ZenIR): RuntimeCode {
   // Transform script (remove state and prop declarations, they're handled by runtime)
   const scriptCode = transformStateDeclarations(scriptContent)
 
-  // Transform component scripts for instance-scoped execution
-  const componentScriptCode = transformAllComponentScripts(ir.componentScripts || [])
+  // Transform component scripts for instance-scoped execution (synchronous - Acorn)
+  const componentScriptResult = transformAllComponentScripts(ir.componentScripts || [])
 
   // Generate complete runtime bundle
   const bundle = generateRuntimeBundle({
@@ -83,7 +83,8 @@ export function transformIR(ir: ZenIR): RuntimeCode {
     stylesCode,
     scriptCode,
     stateInitCode,
-    componentScriptCode  // Component factories
+    componentScriptCode: componentScriptResult.code,
+    npmImports: componentScriptResult.imports
   })
 
   return {
@@ -109,14 +110,20 @@ function generateRuntimeBundle(parts: {
   scriptCode: string
   stateInitCode: string
   componentScriptCode: string  // Component factories
+  npmImports: ScriptImport[]   // Structured npm imports from component scripts
 }): string {
   // Extract function declarations from script code to register on window
   const functionRegistrations = extractFunctionRegistrations(parts.scriptCode)
 
+  // Generate npm imports header (hoisted, deduplicated, deterministic)
+  const npmImportsHeader = parts.npmImports.length > 0
+    ? `// NPM Imports (hoisted from component scripts)\n${emitImports(parts.npmImports)}\n\n`
+    : ''
+
   return `// Zenith Runtime Bundle (Phase 5)
 // Generated at compile time - no .zen parsing in browser
 
-${parts.expressions}
+${npmImportsHeader}${parts.expressions}
 
 ${parts.expressionRegistry}