@zenithbuild/compiler 1.3.2 → 1.3.9

package/dist/build-analyzer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Zenith Build Analyzer
+ *
+ * Analyzes .zen page source to determine build strategy:
+ * - Static: Pure HTML+CSS, no JS needed
+ * - Hydration: Has state/events/hooks, needs page-specific JS
+ * - SSR: Uses useFetchServer, needs server rendering
+ * - SPA: Uses ZenLink with passHref, needs client router
+ */
+export interface PageAnalysis {
+    /** Page has state declarations that need hydration */
+    hasState: boolean;
+    /** Page has event handlers (onclick, etc.) */
+    hasEventHandlers: boolean;
+    /** Page uses lifecycle hooks (zenOnMount, zenOnUnmount) */
+    hasLifecycleHooks: boolean;
+    /** Page uses useFetchServer (requires SSR) */
+    usesServerFetch: boolean;
+    /** Page uses useFetchClient (client-side data) */
+    usesClientFetch: boolean;
+    /** Page uses ZenLink with passHref (SPA navigation) */
+    usesZenLink: boolean;
+    /** Page uses reactive expressions in templates */
+    hasReactiveExpressions: boolean;
+    /** Computed: page needs any JavaScript */
+    needsHydration: boolean;
+    /** Computed: page is purely static (no JS) */
+    isStatic: boolean;
+    /** Computed: page needs SSR */
+    needsSSR: boolean;
+}
+/**
+ * Analyze a .zen page source to determine build requirements
+ */
+export declare function analyzePageSource(source: string): PageAnalysis;
+/**
+ * Get a human-readable summary of the page analysis
+ */
+export declare function getAnalysisSummary(analysis: PageAnalysis): string;
+/**
+ * Determine build output type for a page
+ */
+export type BuildOutputType = 'static' | 'hydrated' | 'ssr';
+export declare function getBuildOutputType(analysis: PageAnalysis): BuildOutputType;

package/dist/build-analyzer.js

@@ -0,0 +1,87 @@
+/**
+ * Zenith Build Analyzer
+ *
+ * Analyzes .zen page source to determine build strategy:
+ * - Static: Pure HTML+CSS, no JS needed
+ * - Hydration: Has state/events/hooks, needs page-specific JS
+ * - SSR: Uses useFetchServer, needs server rendering
+ * - SPA: Uses ZenLink with passHref, needs client router
+ */
+/**
+ * Analyze a .zen page source to determine build requirements
+ */
+export function analyzePageSource(source) {
+    // Extract script content for analysis
+    const scriptMatch = source.match(/<script[^>]*>([\s\S]*?)<\/script>/i);
+    const scriptContent = scriptMatch?.[1] || '';
+    // Extract template content (everything outside script/style)
+    const templateContent = source
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '');
+    // Check for state declarations: "state varName = ..."
+    const hasState = /\bstate\s+\w+\s*=/.test(scriptContent);
+    // Check for event handlers in template
+    const hasEventHandlers = /\bon(click|change|input|submit|focus|blur|keydown|keyup|keypress|mousedown|mouseup|mouseover|mouseout|mouseenter|mouseleave|load)\s*=\s*["'{]/.test(templateContent);
+    // Check for lifecycle hooks
+    const hasLifecycleHooks = /\bzen(OnMount|OnUnmount)\s*\(/.test(scriptContent);
+    // Check for server fetch
+    const usesServerFetch = /\buseFetchServer\s*\(/.test(scriptContent);
+    // Check for client fetch
+    const usesClientFetch = /\buseFetchClient\s*\(/.test(scriptContent);
+    // Check for ZenLink with passHref
+    const usesZenLink = /<ZenLink[^>]*passHref[^>]*>/.test(templateContent);
+    // Check for reactive expressions in template: {expression}
+    // Must be actual expressions, not just static text
+    // Exclude attribute values like href="/path"
+    const hasReactiveExpressions = /{[^{}]+}/.test(templateContent);
+    // Compute derived properties
+    const needsHydration = hasState || hasEventHandlers || hasLifecycleHooks ||
+        usesClientFetch || hasReactiveExpressions;
+    const isStatic = !needsHydration && !usesServerFetch;
+    const needsSSR = usesServerFetch;
+    return {
+        hasState,
+        hasEventHandlers,
+        hasLifecycleHooks,
+        usesServerFetch,
+        usesClientFetch,
+        usesZenLink,
+        hasReactiveExpressions,
+        needsHydration,
+        isStatic,
+        needsSSR
+    };
+}
+/**
+ * Get a human-readable summary of the page analysis
+ */
+export function getAnalysisSummary(analysis) {
+    const flags = [];
+    if (analysis.isStatic) {
+        flags.push('STATIC (no JS)');
+    }
+    else {
+        if (analysis.hasState)
+            flags.push('state');
+        if (analysis.hasEventHandlers)
+            flags.push('events');
+        if (analysis.hasLifecycleHooks)
+            flags.push('lifecycle');
+        if (analysis.hasReactiveExpressions)
+            flags.push('reactive');
+        if (analysis.usesClientFetch)
+            flags.push('clientFetch');
+    }
+    if (analysis.needsSSR)
+        flags.push('SSR');
+    if (analysis.usesZenLink)
+        flags.push('SPA');
+    return flags.length > 0 ? flags.join(', ') : 'minimal';
+}
+export function getBuildOutputType(analysis) {
+    if (analysis.needsSSR)
+        return 'ssr';
+    if (analysis.needsHydration)
+        return 'hydrated';
+    return 'static';
+}

package/dist/bundler.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @zenithbuild/core - Page Script Bundler
+ *
+ * COMPILER-FIRST ARCHITECTURE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * This bundler performs ZERO inference. It executes exactly what the compiler specifies.
+ *
+ * Rules:
+ * - If a BundlePlan is provided, bundling MUST occur
+ * - If bundling fails, throw a hard error (no fallback)
+ * - The bundler never inspects source code for intent
+ * - No temp files, no heuristics, no recovery
+ *
+ * Bundler failure = compiler bug.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import type { BundlePlan } from './ir/types';
+/**
+ * Execute a compiler-emitted BundlePlan
+ *
+ * This is a PURE PLAN EXECUTOR. It does not:
+ * - Inspect source code for imports
+ * - Decide whether bundling is needed
+ * - Fall back on failure
+ * - Use temp files
+ *
+ * @param plan - Compiler-emitted BundlePlan (must exist; caller must not call if no plan)
+ * @throws Error if bundling fails (no fallback, no recovery)
+ */
+export declare function bundlePageScript(plan: BundlePlan): Promise<string>;

package/dist/bundler.js

@@ -0,0 +1,92 @@
+/**
+ * @zenithbuild/core - Page Script Bundler
+ *
+ * COMPILER-FIRST ARCHITECTURE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * This bundler performs ZERO inference. It executes exactly what the compiler specifies.
+ *
+ * Rules:
+ * - If a BundlePlan is provided, bundling MUST occur
+ * - If bundling fails, throw a hard error (no fallback)
+ * - The bundler never inspects source code for intent
+ * - No temp files, no heuristics, no recovery
+ *
+ * Bundler failure = compiler bug.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import { rolldown } from 'rolldown';
+/**
+ * Execute a compiler-emitted BundlePlan
+ *
+ * This is a PURE PLAN EXECUTOR. It does not:
+ * - Inspect source code for imports
+ * - Decide whether bundling is needed
+ * - Fall back on failure
+ * - Use temp files
+ *
+ * @param plan - Compiler-emitted BundlePlan (must exist; caller must not call if no plan)
+ * @throws Error if bundling fails (no fallback, no recovery)
+ */
+export async function bundlePageScript(plan) {
+    // Virtual entry module ID
+    const VIRTUAL_ENTRY = '\0zenith:entry.tsx';
+    /*
+    console.log('[Zenith Bundler] Input entry length:', plan.entry.length)
+    if (plan.entry.length > 4000) {
+        console.log('[Zenith Bundler] Input entry tail:', plan.entry.slice(-200))
+    }
+    */
+    // Build virtual modules map from plan
+    const virtualModules = new Map();
+    virtualModules.set(VIRTUAL_ENTRY, plan.entry);
+    for (const vm of plan.virtualModules) {
+        virtualModules.set(vm.id, vm.code);
+    }
+    // Execute Rolldown with plan-specified configuration
+    // No inference, no heuristics, no semantic analysis
+    const bundle = await rolldown({
+        input: VIRTUAL_ENTRY,
+        platform: plan.platform,
+        resolve: {
+            modules: plan.resolveRoots
+        },
+        plugins: [{
+                name: 'zenith-virtual',
+                resolveId(source) {
+                    // Virtual modules from plan
+                    if (virtualModules.has(source)) {
+                        return { id: source, moduleSideEffects: true };
+                    }
+                    // Special case: zenith:content namespace
+                    if (source === 'zenith:content') {
+                        return { id: '\0zenith:content', moduleSideEffects: true };
+                    }
+                    return null;
+                },
+                load(id) {
+                    return virtualModules.get(id) ?? null;
+                }
+            }],
+        // DETERMINISTIC OUTPUT: Disable all semantic optimizations
+        // Tree-shaking implies semantic analysis - bundler must not infer
+        treeshake: false,
+        // HARD FAILURE on unresolved imports - no silent external treatment
+        onLog(level, log) {
+            if (log.code === 'UNRESOLVED_IMPORT') {
+                throw new Error(`[Zenith Bundler] Unresolved import: ${log.message}. ` +
+                    `This is a compiler error - the BundlePlan references a module that cannot be resolved.`);
+            }
+        }
+    });
+    // Generate output with plan-specified format
+    const { output } = await bundle.generate({
+        format: plan.format
+    });
+    // Hard failure if no output - this is a compiler bug
+    if (!output[0]?.code) {
+        throw new Error('[Zenith Bundler] Rolldown produced no output. ' +
+            'This is a compiler error - the BundlePlan was invalid or Rolldown failed silently.');
+    }
+    return output[0].code;
+}

package/dist/core/config/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Zenith Config
+ *
+ * Public exports for zenith/config
+ *
+ * Core exports ONLY generic plugin infrastructure.
+ * Plugin-specific types are owned by their respective plugins.
+ */
+export { defineConfig } from './types';
+export type { ZenithConfig, ZenithPlugin, PluginContext, PluginData } from './types';
+export { loadZenithConfig, hasZenithConfig } from './loader';

package/dist/core/config/index.js

@@ -0,0 +1,10 @@
+/**
+ * Zenith Config
+ *
+ * Public exports for zenith/config
+ *
+ * Core exports ONLY generic plugin infrastructure.
+ * Plugin-specific types are owned by their respective plugins.
+ */
+export { defineConfig } from './types';
+export { loadZenithConfig, hasZenithConfig } from './loader';

package/dist/core/config/loader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Zenith Config Loader
+ *
+ * Loads zenith.config.ts from the project root
+ */
+import type { ZenithConfig } from './types';
+/**
+ * Load zenith.config.ts from the project root
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Parsed ZenithConfig or empty config if not found
+ */
+export declare function loadZenithConfig(projectRoot: string): Promise<ZenithConfig>;
+/**
+ * Check if a zenith.config.ts exists in the project
+ */
+export declare function hasZenithConfig(projectRoot: string): boolean;

package/dist/core/config/loader.js

@@ -0,0 +1,60 @@
+/**
+ * Zenith Config Loader
+ *
+ * Loads zenith.config.ts from the project root
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Load zenith.config.ts from the project root
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Parsed ZenithConfig or empty config if not found
+ */
+export async function loadZenithConfig(projectRoot) {
+    // Check for TypeScript config first, then JavaScript
+    const configPaths = [
+        path.join(projectRoot, 'zenith.config.ts'),
+        path.join(projectRoot, 'zenith.config.js'),
+        path.join(projectRoot, 'zenith.config.mjs'),
+    ];
+    let configPath = null;
+    for (const p of configPaths) {
+        if (fs.existsSync(p)) {
+            configPath = p;
+            break;
+        }
+    }
+    if (!configPath) {
+        // No config file found, return empty config
+        return { plugins: [] };
+    }
+    try {
+        // Use dynamic import to load the config
+        // Bun supports importing TS files directly
+        const configModule = await import(configPath);
+        const config = configModule.default || configModule;
+        // Validate basic structure
+        if (typeof config !== 'object' || config === null) {
+            console.warn(`[Zenith] Invalid config format in ${configPath}`);
+            return { plugins: [] };
+        }
+        return config;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[Zenith] Failed to load config from ${configPath}:`, message);
+        return { plugins: [] };
+    }
+}
+/**
+ * Check if a zenith.config.ts exists in the project
+ */
+export function hasZenithConfig(projectRoot) {
+    const configPaths = [
+        path.join(projectRoot, 'zenith.config.ts'),
+        path.join(projectRoot, 'zenith.config.js'),
+        path.join(projectRoot, 'zenith.config.mjs'),
+    ];
+    return configPaths.some(p => fs.existsSync(p));
+}

package/dist/core/config/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Zenith Config Types
+ *
+ * Configuration interfaces for zenith.config.ts
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOOK OWNERSHIP RULE (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Core may ONLY define types that are universally valid in all Zenith applications.
+ * Plugin-specific types MUST be owned by their respective plugins.
+ *
+ * ✅ ALLOWED in Core:
+ *    - ZenithConfig, ZenithPlugin, PluginContext (generic plugin infrastructure)
+ *    - Universal lifecycle hooks (onMount, onUnmount)
+ *    - Reactivity primitives (signal, effect, etc.)
+ *
+ * ❌ PROHIBITED in Core:
+ *    - Content plugin types (ContentItem, ContentSourceConfig, etc.)
+ *    - Router plugin types (RouteState, NavigationGuard, etc.)
+ *    - Documentation plugin types
+ *    - Any type that exists only because a plugin exists
+ *
+ * If removing a plugin would make a type meaningless, that type belongs to the plugin.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import type { CLIBridgeAPI } from '../plugins/bridge';
+/**
+ * Generic data record for plugin data exchange
+ * Plugins define their own specific types internally
+ */
+export type PluginData = Record<string, unknown[]>;
+/**
+ * Context passed to plugins during setup
+ *
+ * This is intentionally generic - plugins define their own data shapes.
+ * Core provides the stage, plugins bring the actors.
+ */
+export interface PluginContext {
+    /** Absolute path to project root */
+    projectRoot: string;
+    /**
+     * Set plugin data for the runtime
+     *
+     * Generic setter - plugins define their own data structures.
+     * The runtime stores this data and makes it available to components.
+     *
+     * @example
+     * // Content plugin uses it for content items
+     * ctx.setPluginData('content', contentItems);
+     *
+     * // Analytics plugin uses it for tracking config
+     * ctx.setPluginData('analytics', analyticsConfig);
+     */
+    setPluginData: (namespace: string, data: unknown[]) => void;
+    /** Additional options passed from config */
+    options?: Record<string, unknown>;
+}
+/**
+ * A Zenith plugin definition
+ *
+ * Plugins are self-contained, removable extensions.
+ * Core must build and run identically with or without any plugin installed.
+ */
+export interface ZenithPlugin {
+    /** Unique plugin name */
+    name: string;
+    /** Setup function called during initialization */
+    setup: (ctx: PluginContext) => void | Promise<void>;
+    /** Plugin-specific configuration (preserved for reference) */
+    config?: unknown;
+    /**
+     * Optional CLI registration
+     *
+     * Plugin receives the CLI bridge API to register namespaced hooks.
+     * CLI lifecycle hooks: 'cli:*' (owned by CLI)
+     * Plugin hooks: '<namespace>:*' (owned by plugin)
+     *
+     * @example
+     * registerCLI(api) {
+     *   api.on('cli:runtime:collect', (ctx) => {
+     *     return { namespace: 'myPlugin', payload: ctx.getPluginData('myPlugin') }
+     *   })
+     * }
+     */
+    registerCLI?: (api: CLIBridgeAPI) => void;
+}
+/**
+ * Zenith configuration object
+ */
+export interface ZenithConfig {
+    /** List of plugins to load */
+    plugins?: ZenithPlugin[];
+}
+/**
+ * Define a Zenith configuration with full type safety
+ */
+export declare function defineConfig(config: ZenithConfig): ZenithConfig;

package/dist/core/config/types.js

@@ -0,0 +1,32 @@
+/**
+ * Zenith Config Types
+ *
+ * Configuration interfaces for zenith.config.ts
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOOK OWNERSHIP RULE (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Core may ONLY define types that are universally valid in all Zenith applications.
+ * Plugin-specific types MUST be owned by their respective plugins.
+ *
+ * ✅ ALLOWED in Core:
+ *    - ZenithConfig, ZenithPlugin, PluginContext (generic plugin infrastructure)
+ *    - Universal lifecycle hooks (onMount, onUnmount)
+ *    - Reactivity primitives (signal, effect, etc.)
+ *
+ * ❌ PROHIBITED in Core:
+ *    - Content plugin types (ContentItem, ContentSourceConfig, etc.)
+ *    - Router plugin types (RouteState, NavigationGuard, etc.)
+ *    - Documentation plugin types
+ *    - Any type that exists only because a plugin exists
+ *
+ * If removing a plugin would make a type meaningless, that type belongs to the plugin.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * Define a Zenith configuration with full type safety
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Zenith Compiler Core Modules
+ */
+export { loadZenithConfig } from './config/loader';
+export { PluginRegistry, createPluginContext, getPluginDataByNamespace } from './plugins/registry';
+export { createBridgeAPI, runPluginHooks, collectHookReturns, buildRuntimeEnvelope, clearHooks } from './plugins/bridge';
+export type { HookContext } from './plugins/bridge';

package/dist/core/index.js

@@ -0,0 +1,6 @@
+/**
+ * Zenith Compiler Core Modules
+ */
+export { loadZenithConfig } from './config/loader';
+export { PluginRegistry, createPluginContext, getPluginDataByNamespace } from './plugins/registry';
+export { createBridgeAPI, runPluginHooks, collectHookReturns, buildRuntimeEnvelope, clearHooks } from './plugins/bridge';

package/dist/core/plugins/bridge.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Zenith CLI Bridge
+ *
+ * The ONLY interface between CLI and plugins.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * CLI BRIDGE RULES (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * 1. No runtime emitters - plugins return data, CLI serializes blindly
+ * 2. No plugin typing - all data is unknown
+ * 3. No semantic helpers - CLI is blind to what data means
+ *
+ * The CLI dispatches hooks and collects returns. It never inspects payloads.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * CLI Bridge API - passed to plugins during CLI registration
+ *
+ * Plugins use this to register namespaced hooks.
+ * CLI lifecycle hooks: 'cli:*'
+ * Plugin hooks: '<namespace>:*'
+ */
+export interface CLIBridgeAPI {
+    /**
+     * Register a hook handler
+     *
+     * @param hook - Namespaced hook name (e.g., 'cli:runtime:collect', 'content:dev:watch')
+     * @param handler - Handler function that receives context and optionally returns data
+     */
+    on(hook: string, handler: (ctx: HookContext) => unknown | void | Promise<unknown | void>): void;
+}
+/**
+ * Context passed to hook handlers
+ *
+ * CLI provides this but never uses getPluginData itself.
+ * Only plugins call getPluginData with their own namespace.
+ */
+export interface HookContext {
+    /** Absolute path to project root */
+    projectRoot: string;
+    /**
+     * Opaque data accessor
+     *
+     * CLI passes this function but NEVER calls it.
+     * Only plugins use it to access their own namespaced data.
+     */
+    getPluginData: (namespace: string) => unknown;
+    /** Additional context data (e.g., filename for file-change hooks) */
+    [key: string]: unknown;
+}
+/**
+ * Runtime payload returned by plugins
+ *
+ * CLI collects these and serializes without inspection.
+ * The envelope structure is: { [namespace]: payload }
+ */
+export interface RuntimePayload {
+    /** Plugin namespace (e.g., 'content', 'router') */
+    namespace: string;
+    /** Opaque payload - CLI never inspects this */
+    payload: unknown;
+}
+type HookHandler = (ctx: HookContext) => unknown | void | Promise<unknown | void>;
+/**
+ * Register a hook handler
+ *
+ * @internal Called by CLIBridgeAPI.on()
+ */
+export declare function registerHook(hook: string, handler: HookHandler): void;
+/**
+ * Clear all registered hooks
+ *
+ * @internal Used for testing and cleanup
+ */
+export declare function clearHooks(): void;
+/**
+ * Run all handlers for a hook (fire-and-forget)
+ *
+ * CLI calls this for lifecycle events.
+ * No return values are collected.
+ *
+ * @param hook - Hook name to dispatch
+ * @param ctx - Hook context
+ */
+export declare function runPluginHooks(hook: string, ctx: HookContext): Promise<void>;
+/**
+ * Collect return values from all handlers for a hook
+ *
+ * CLI calls this for 'cli:runtime:collect' to gather plugin payloads.
+ * Only RuntimePayload-shaped returns are collected.
+ *
+ * @param hook - Hook name to dispatch
+ * @param ctx - Hook context
+ * @returns Array of runtime payloads from plugins
+ */
+export declare function collectHookReturns(hook: string, ctx: HookContext): Promise<RuntimePayload[]>;
+/**
+ * Build runtime envelope from collected payloads
+ *
+ * CLI calls this to serialize plugin data for injection.
+ * CLI never inspects the envelope contents.
+ *
+ * @param payloads - Array of runtime payloads from collectHookReturns
+ * @returns Envelope object: { [namespace]: payload }
+ */
+export declare function buildRuntimeEnvelope(payloads: RuntimePayload[]): Record<string, unknown>;
+/**
+ * Create a CLI Bridge API for plugin registration
+ *
+ * CLI calls this once and passes to each plugin's registerCLI method.
+ *
+ * @returns CLIBridgeAPI instance
+ */
+export declare function createBridgeAPI(): CLIBridgeAPI;
+export {};