create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/build/code-splitter.js

@@ -0,0 +1,194 @@
+/**
+ * Intelligent code splitting analyzer
+ *
+ * Splits bundles into logical chunks:
+ * - Vendor: node_modules dependencies (high cache hit rate)
+ * - Runtime: Framework runtime/hydration (shared across all pages)
+ * - Common: Shared components (used by multiple routes)
+ * - Route: Per-route chunks (lazy-loaded on demand)
+ * - Entry: Main application bundle
+ */
+export class CodeSplitter {
+  strategies = [];
+  routeAnalysis = new Map();
+  constructor() {
+    this.initializeDefaultStrategies();
+  }
+  /**
+   * Initialize default splitting strategies in priority order
+   */
+  initializeDefaultStrategies() {
+    // Vendor chunks (highest priority - most stable)
+    this.strategies.push({
+      name: "vendor",
+      test: (path) => {
+        return /node_modules/.test(path) && !this.isFrameworkInternal(path);
+      },
+      priority: 100,
+    });
+    // Framework runtime (stable, shared across all pages)
+    this.strategies.push({
+      name: "runtime",
+      test: (path) => {
+        return (
+          this.isFrameworkInternal(path) && /runtime|hydrate|ssr/.test(path)
+        );
+      },
+      priority: 90,
+    });
+    // Common utilities (shared components)
+    this.strategies.push({
+      name: "common",
+      test: (path) => {
+        return /components|utils|helpers/.test(path);
+      },
+      priority: 80,
+    });
+    // Route-specific chunks (lazy-loaded)
+    this.strategies.push({
+      name: "route",
+      test: (path) => {
+        return /pages|routes|site/.test(path);
+      },
+      priority: 50,
+    });
+  }
+  /**
+   * Determine which chunk a module should belong to
+   */
+  determineChunk(modulePath) {
+    // Sort by priority (descending)
+    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
+    for (const strategy of sorted) {
+      if (strategy.test(modulePath)) {
+        return strategy.name;
+      }
+    }
+    return "entry"; // Default to main entry chunk
+  }
+  /**
+   * Analyze route dependencies for splitting decisions
+   *
+   * @param routePath Path to route file
+   * @param dependencies List of imported module paths
+   */
+  analyzeRouteDependencies(routePath, dependencies) {
+    this.routeAnalysis.set(routePath, dependencies);
+  }
+  /**
+   * Generate esbuild manual chunks configuration
+   *
+   * Implements intelligent bundling:
+   * - Vendor libraries in separate chunk (external dependencies)
+   * - Runtime/hydration in separate chunk (framework internals)
+   * - Common code in separate chunk (shared components)
+   * - Route-specific code in separate chunks (per-route lazy-loading)
+   */
+  generateManualChunks() {
+    const chunks = {};
+    // Vendor chunk patterns
+    chunks.vendor = [
+      "preact",
+      "preact/compat",
+      "preact/hooks",
+      "preact/compat/scheduler",
+      "htm",
+    ];
+    // Runtime chunk patterns
+    chunks.runtime = [
+      "../runtime/hydrate.js",
+      "../runtime/render.js",
+      "../runtime/ssr.js",
+    ];
+    // Common utilities patterns
+    chunks.common = [];
+    return chunks;
+  }
+  /**
+   * Generate esbuild splitting configuration
+   */
+  generateSplittingConfig() {
+    return {
+      splitting: true,
+      format: "esm",
+      chunkNames: "[name]-[hash]",
+      manualChunks: this.generateManualChunks(),
+    };
+  }
+  /**
+   * Generate chunk dependency graph for debugging
+   *
+   * Shows which chunks depend on which others, useful for:
+   * - Understanding load order
+   * - Optimizing prefetching
+   * - Detecting circular dependencies
+   */
+  generateDependencyGraph() {
+    let graph = "# Chunk Dependency Graph\n\n";
+    graph += "## Splitting Strategy\n";
+    graph += "- **vendor**: External dependencies (preact, utilities)\n";
+    graph += "- **runtime**: Framework runtime (hydration, SSR, hooks)\n";
+    graph += "- **common**: Shared components and utilities\n";
+    graph += "- **route**: Per-route lazy-loaded chunks\n";
+    graph += "- **entry**: Main application bundle\n\n";
+    graph += "## Load Order\n";
+    graph += "1. Entry (main bundle) - executes immediately\n";
+    graph += "2. Vendor - loaded on demand, cached long-term\n";
+    graph += "3. Runtime - loaded before any route rendering\n";
+    graph += "4. Common - loaded when needed by routes\n";
+    graph += "5. Route chunks - lazy-loaded per page\n\n";
+    graph += "## Cache Strategy\n";
+    graph +=
+      "- Vendor: `max-age=31536000, immutable` (1 year, never changes)\n";
+    graph += "- Runtime: `max-age=2592000` (30 days, updated with framework)\n";
+    graph += "- Entry: `max-age=3600` (1 hour, updated frequently)\n";
+    graph += "- Routes: `max-age=86400` (1 day, per-route updates)\n\n";
+    return graph;
+  }
+  /**
+   * Check if path is internal framework code
+   */
+  isFrameworkInternal(path) {
+    return /@src|src\//.test(path);
+  }
+  /**
+   * Register custom splitting strategy
+   */
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+    // Re-sort by priority
+    this.strategies.sort((a, b) => b.priority - a.priority);
+  }
+  /**
+   * Generate splitting report
+   */
+  generateReport() {
+    let report = "# Code Splitting Report\n\n";
+    report += "## Active Strategies\n";
+    for (const strategy of this.strategies) {
+      report += `- **${strategy.name}** (priority: ${strategy.priority})\n`;
+    }
+    report += "\n## Route Analysis\n";
+    if (this.routeAnalysis.size === 0) {
+      report += "No routes analyzed yet.\n";
+    } else {
+      for (const [route, deps] of this.routeAnalysis) {
+        report += `- **${route}**: ${deps.length} dependencies\n`;
+      }
+    }
+    return report;
+  }
+}
+/**
+ * Helper: Create esbuild configuration for code splitting
+ */
+export function createSplitConfig(outdir = "dist") {
+  const splitter = new CodeSplitter();
+  return {
+    ...splitter.generateSplittingConfig(),
+    outdir,
+    minify: true,
+    format: "esm",
+    target: "es2022",
+  };
+}

package/templates/static/lib/build/feature-analyzer.js

@@ -0,0 +1,190 @@
+import {
+  resolveFeatures,
+  getEnabledFeatures,
+  createBuildMetadata,
+} from "../core/features.js";
+/**
+ * Build-time feature analyzer.
+ * Determines which features are enabled and generates metadata.
+ * Used to inform bundling decisions and eliminate unused code.
+ */
+export class FeatureAnalyzer {
+  config;
+  resolved;
+  metadata;
+  constructor(config) {
+    this.config = config;
+    this.resolved = resolveFeatures(config.features);
+    this.metadata = createBuildMetadata(this.resolved, config.features);
+  }
+  /**
+   * Returns resolved feature configuration.
+   */
+  getResolved() {
+    return this.resolved;
+  }
+  /**
+   * Returns build metadata for debugging/introspection.
+   */
+  getMetadata() {
+    return this.metadata;
+  }
+  /**
+   * Checks if a feature is enabled.
+   */
+  isEnabled(feature) {
+    return this.resolved[feature] ?? false;
+  }
+  /**
+   * Gets list of enabled features.
+   */
+  getEnabled() {
+    return getEnabledFeatures(this.resolved);
+  }
+  /**
+   * Generates feature metadata JSON string.
+   */
+  generateMetadataJson() {
+    return JSON.stringify(this.metadata, null, 2);
+  }
+  /**
+   * Generates a feature flag constant object for runtime checks.
+   * Can be tree-shaken by bundler for disabled features.
+   *
+   * @example
+   * ```typescript
+   * export const FEATURES = {
+   *   api: true,
+   *   middleware: true,
+   *   cache: false,
+   *   // ... rest
+   * } as const;
+   * ```
+   */
+  generateFeatureFlagsCode() {
+    const features = this.resolved;
+    const lines = Object.entries(features).map(
+      ([name, enabled]) => `  ${name}: ${enabled},`,
+    );
+    return `
+/**
+ * Build-time feature flags.
+ * Disabled features are tree-shaken by the bundler.
+ */
+export const FEATURES = {
+${lines.join("\n")}
+} as const;
+
+export type EnabledFeatures = {
+  ${getEnabledFeatures(this.resolved)
+    .map((f) => `${f}: typeof FEATURES.${f}`)
+    .join(";\n  ")};
+};
+`;
+  }
+  /**
+   * Generates TypeScript definitions for feature-gated code.
+   * Enables type-safe access to enabled features only.
+   */
+  generateTypeDefinitions() {
+    const enabled = getEnabledFeatures(this.resolved);
+    return `
+/**
+ * Auto-generated feature type definitions
+ * Features not listed here are disabled and not available at runtime
+ */
+
+declare global {
+  interface FeatureFlags {
+    ${enabled.map((f) => `${f}: true;`).join("\n    ")}
+  }
+}
+
+export {};
+`;
+  }
+  /**
+   * Generates a dynamic import guard for feature modules.
+   * Prevents importing disabled feature modules.
+   */
+  generateFeatureGuard(feature) {
+    const isEnabled = this.isEnabled(feature);
+    return `
+if (!${isEnabled}) {
+  throw new Error(
+    'Feature "${feature}" is not enabled. ' +
+    'Enable it in jen.config.ts: features: { ${feature}: true }'
+  );
+}
+`;
+  }
+  /**
+   * Generates code to conditionally include feature handlers.
+   * Used in server request handlers.
+   */
+  generateConditionalHandlers() {
+    const enabled = getEnabledFeatures(this.resolved);
+    let code = `
+// Auto-generated feature handlers
+// Only enabled features are included
+
+`;
+    if (enabled.includes("api")) {
+      code += `
+// API Routes Handler
+import { tryHandleApiRoute } from "../server/api-routes.js";
+`;
+    }
+    if (enabled.includes("middleware")) {
+      code += `
+// Middleware Handler
+import { Kernel } from "../middleware/kernel.js";
+`;
+    }
+    if (enabled.includes("cache")) {
+      code += `
+// Cache Handler
+import { MemoryCache } from "../cache/memory.js";
+`;
+    }
+    if (enabled.includes("streaming")) {
+      code += `
+// Streaming Handler
+import renderToString from "preact-render-to-string";
+`;
+    }
+    if (enabled.includes("auth")) {
+      code += `
+// Auth Handler
+// (to be implemented in future release)
+`;
+    }
+    return code;
+  }
+  /**
+   * Generates summary report of feature configuration.
+   */
+  generateReport() {
+    const enabled = getEnabledFeatures(this.resolved);
+    const disabled = Object.entries(this.resolved)
+      .filter(([, e]) => !e)
+      .map(([name]) => name);
+    return `
+Feature Configuration Report
+=============================
+
+Build Time: ${this.metadata.buildTime}
+
+Enabled (${enabled.length}):
+${enabled.length > 0 ? enabled.map((f) => `  ✓ ${f}`).join("\n") : "  (none - core only)"}
+
+Disabled (${disabled.length}):
+${disabled.length > 0 ? disabled.map((f) => `  ✗ ${f}`).join("\n") : "  (all features enabled)"}
+
+Bundle Impact:
+  Core modules: Always included
+  Enabled features: Included in bundle
+  Disabled features: Completely removed (tree-shaken)
+`;
+  }
+}

package/templates/static/lib/build/feature-gate.js

@@ -0,0 +1,257 @@
+import { resolveFeatures, getEnabledFeatures } from "../core/features.js";
+/**
+ * Feature gate compiler that generates optimized request handlers based on enabled features.
+ * Statically analyzes feature configuration at build time and generates only the necessary code.
+ *
+ * This approach ensures:
+ * 1. Unused features are completely tree-shaken from the bundle
+ * 2. No runtime feature detection overhead
+ * 3. Type-safe access to enabled features
+ * 4. Build-time validation of feature compatibility
+ */
+export class FeatureGateCompiler {
+  resolved;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.resolved = resolveFeatures(config.features);
+  }
+  /**
+   * Generates a TypeScript handler file that includes only enabled features.
+   * This file is generated at build time and imported by the request handler.
+   *
+   * @returns Generated TypeScript code as string
+   */
+  generateHandlerCode() {
+    const enabled = getEnabledFeatures(this.resolved);
+    const imports = this.generateImports(enabled);
+    const middleware = this.generateMiddlewareChain(enabled);
+    const handlers = this.generateHandlers(enabled);
+    return `
+/*
+ * AUTO-GENERATED: This file is generated at build time based on enabled features.
+ * DO NOT EDIT MANUALLY - your changes will be overwritten on next build.
+ * 
+ * Enabled features: ${enabled.join(", ") || "none (core only)"}
+ */
+
+${imports}
+
+/**
+ * Build-time compiled request handler with only enabled features.
+ * Each feature is statically included or excluded based on configuration.
+ */
+export async function handleRequest(req: any, res: any, context: any) {
+  ${middleware}
+  ${handlers}
+}
+
+/**
+ * Feature flags for runtime checks (constant-folded at build time).
+ * TypeScript will eliminate dead code paths for disabled features.
+ */
+export const FEATURES = {
+  ${enabled.map((f) => `${f}: true`).join(",\n  ")},
+  ${Object.entries(this.resolved)
+    .filter(([, enabled]) => !enabled)
+    .map(([name]) => `${name}: false`)
+    .join(",\n  ")},
+} as const;
+`;
+  }
+  /**
+   * Generates import statements only for enabled features.
+   *
+   * @param enabled List of enabled feature names
+   * @returns Import statement code
+   */
+  generateImports(enabled) {
+    const imports = [];
+    if (enabled.includes("api")) {
+      imports.push(
+        'import { handleApiRoutes } from "../features/api/handler.js";',
+      );
+    }
+    if (enabled.includes("middleware")) {
+      imports.push(
+        'import { compiledMiddlewareChain } from "../features/middleware/compiled.js";',
+      );
+    }
+    if (enabled.includes("cache")) {
+      imports.push(
+        'import { getCachedResponse, setCachedResponse } from "../features/cache/handler.js";',
+      );
+    }
+    if (enabled.includes("streaming")) {
+      imports.push(
+        'import { StreamingRenderer } from "../features/streaming/renderer.js";',
+      );
+    }
+    if (enabled.includes("auth")) {
+      imports.push(
+        'import { authMiddleware } from "../features/auth/middleware.js";',
+      );
+    }
+    // Always import core
+    imports.unshift('import type { RouteHandler } from "../core/types.js";');
+    return imports.join("\n");
+  }
+  /**
+   * Generates middleware chain initialization code.
+   *
+   * @param enabled List of enabled feature names
+   * @returns Middleware setup code
+   */
+  generateMiddlewareChain(enabled) {
+    if (!enabled.includes("middleware")) {
+      return "// Middleware disabled";
+    }
+    return `
+    // Apply compiled middleware chain (pre-resolved at build time)
+    const middlewareResult = await compiledMiddlewareChain(req, res, context);
+    if (middlewareResult.handled) return;
+    context.middleware = middlewareResult.data;
+    `;
+  }
+  /**
+   * Generates request handler logic for enabled features.
+   *
+   * @param enabled List of enabled feature names
+   * @returns Handler code
+   */
+  generateHandlers(enabled) {
+    const handlers = [];
+    // Always handle core routing
+    handlers.push(`
+    // Core routing
+    const route = context.routes.get(req.url);
+    if (!route) {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    `);
+    // API routes
+    if (enabled.includes("api")) {
+      handlers.push(`
+    // Try API routes first
+    const apiResult = await handleApiRoutes(req, res, route, context);
+    if (apiResult.handled) return;
+    `);
+    }
+    // Caching
+    if (enabled.includes("cache")) {
+      handlers.push(`
+    // Check response cache
+    const cached = await getCachedResponse(route, context);
+    if (cached) {
+      res.setHeader("X-Cache", "HIT");
+      res.end(cached);
+      return;
+    }
+    `);
+    }
+    // SSR rendering
+    handlers.push(`
+    // Render route
+    const component = await import(route.moduleId);
+    const data = await component.loader?.(context) ?? {};
+    const html = await renderToString(component.default, { data });
+    `);
+    // Cache response
+    if (enabled.includes("cache")) {
+      handlers.push(`
+    await setCachedResponse(route, html, context);
+    `);
+    }
+    // Stream or buffered response
+    if (enabled.includes("streaming")) {
+      handlers.push(`
+    // Stream response
+    const renderer = new StreamingRenderer(res);
+    await renderer.sendHead(route.head);
+    await renderer.sendBody(html);
+    await renderer.sendFooter();
+    `);
+    } else {
+      handlers.push(`
+    // Send buffered response
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(html);
+    `);
+    }
+    return handlers.join("\n");
+  }
+  /**
+   * Generates type definitions for enabled features.
+   * Ensures TypeScript knows about enabled/disabled features.
+   *
+   * @returns TypeScript type definition code
+   */
+  generateTypeDefinitions() {
+    const enabled = getEnabledFeatures(this.resolved);
+    return `
+// Auto-generated feature type definitions
+declare global {
+  interface FeatureContext {
+    api: ${enabled.includes("api") ? "ApiFeature" : "never"};
+    middleware: ${enabled.includes("middleware") ? "MiddlewareFeature" : "never"};
+    cache: ${enabled.includes("cache") ? "CacheFeature" : "never"};
+    streaming: ${enabled.includes("streaming") ? "StreamingFeature" : "never"};
+    auth: ${enabled.includes("auth") ? "AuthFeature" : "never"};
+  }
+}
+
+export {};
+`;
+  }
+  /**
+   * Generates build metadata for debugging and introspection.
+   *
+   * @returns Metadata as JSON string
+   */
+  generateMetadata() {
+    return JSON.stringify(
+      {
+        buildTime: new Date().toISOString(),
+        enabledFeatures: getEnabledFeatures(this.resolved),
+        disabledFeatures: Object.entries(this.resolved)
+          .filter(([, enabled]) => !enabled)
+          .map(([name]) => name),
+        config: this.config.features,
+      },
+      null,
+      2,
+    );
+  }
+}
+/**
+ * Creates an esbuild plugin that generates feature-gated code during build.
+ *
+ * @param config Framework configuration
+ * @returns esbuild plugin object
+ */
+export function featureGatePlugin(config) {
+  const compiler = new FeatureGateCompiler(config);
+  return {
+    name: "feature-gate",
+    resolveId(id) {
+      if (id === "virtual-feature-handler") {
+        return id;
+      }
+      if (id === "virtual-feature-metadata") {
+        return id;
+      }
+      return null;
+    },
+    load(id) {
+      if (id === "virtual-feature-handler") {
+        return compiler.generateHandlerCode();
+      }
+      if (id === "virtual-feature-metadata") {
+        return `export default ${compiler.generateMetadata()}`;
+      }
+      return null;
+    },
+  };
+}