webspresso 0.0.101 → 0.0.103

package/src/discovery/route-manifest.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * Webspresso - Ahead-Of-Time (AOT) Route Manifest
+ * Generates and loads portable, pre-compiled route manifests to eliminate filesystem
+ * scanning and speed up cold starts in production and containerized environments.
+ * @module src/discovery/route-manifest
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { scanRoutes } = require('./scan-routes');
+const { isApiRouteFile } = require('./file-route-parser');
+const { filePathToRoute, extractMethodFromFilename } = require('../file-router');
+
+const DEFAULT_MANIFEST_REL_PATH = path.join('.webspresso', 'routes.manifest.json');
+
+/**
+ * Generates an Ahead-Of-Time (AOT) route manifest and writes it to disk.
+ *
+ * @param {Object} [options={}]
+ * @param {string} [options.rootDir=process.cwd()] - Project root directory
+ * @param {string|Object} [options.pages] - Pages directory configuration or path
+ * @param {string|Object} [options.api] - API directory configuration or path
+ * @param {string|Object} [options.modules] - Modules directory configuration or path
+ * @param {string} [options.outDir] - Directory where manifest will be saved
+ * @param {string} [options.outFile] - Custom output file path for the manifest
+ * @param {boolean} [options.silent=false] - Suppress console output
+ * @returns {{ manifest: Object, manifestPath: string, routeCount: number, scannedFilesCount: number }}
+ */
+function generateRouteManifest(options = {}) {
+  const rootDir = options.rootDir ? path.resolve(options.rootDir) : process.cwd();
+  const pagesDir = options.pagesDir
+    ? path.resolve(options.pagesDir)
+    : (typeof options.pages === 'string' ? path.resolve(options.pages) : path.join(rootDir, 'pages'));
+
+  const descriptors = scanRoutes({
+    rootDir,
+    pages: options.pages !== undefined ? options.pages : (fs.existsSync(pagesDir) ? { dir: path.relative(rootDir, pagesDir) || 'pages' } : true),
+    api: options.api,
+    modules: options.modules,
+  });
+
+  const routes = [];
+  const routeKeySet = new Set();
+
+  // 1. Discovered routes from scanRoutes (src/pages, src/api, modules/*)
+  for (const d of descriptors) {
+    const method = (d.method || 'GET').toUpperCase();
+    const key = `${method}:${d.path}`;
+    routeKeySet.add(key);
+    routes.push({
+      type: d.type,
+      method,
+      path: d.path,
+      source: d.source || (d.file ? path.relative(rootDir, d.file).split(path.sep).join('/') : ''),
+      module: d.module || null,
+      moduleConfig: d.moduleConfig ? { name: d.moduleConfig.name } : null,
+      target: 'discovered',
+    });
+  }
+
+  // 2. File-based routes from pagesDir (pages/api/**/*.js and pages/**/*.njk)
+  const pagesRel = path.relative(rootDir, pagesDir).split(path.sep).join('/') || 'pages';
+  const scannedPagesFiles = descriptors.scannedPagesFiles || [];
+
+  for (const relFile of scannedPagesFiles) {
+    const ext = path.extname(relFile);
+    if (isApiRouteFile(relFile) && ext === '.js') {
+      const { method: rawMethod, baseName } = extractMethodFromFilename(path.basename(relFile));
+      const method = (rawMethod || 'get').toUpperCase();
+      const dirPart = path.dirname(relFile);
+      const rawRoutePath = dirPart === '.'
+        ? `/${baseName}`
+        : `/${dirPart}/${baseName}`.split(path.sep).join('/');
+      const routePath = filePathToRoute(rawRoutePath, '');
+      const key = `${method}:${routePath}`;
+      if (!routeKeySet.has(key)) {
+        routeKeySet.add(key);
+        routes.push({
+          type: 'api',
+          method,
+          path: routePath,
+          source: path.join(pagesRel, relFile).split(path.sep).join('/'),
+          module: null,
+          moduleConfig: null,
+          target: 'pages',
+        });
+      }
+    } else if (ext === '.njk') {
+      const routePath = filePathToRoute(relFile, '.njk');
+      const key = `GET:${routePath}`;
+      if (!routeKeySet.has(key)) {
+        routeKeySet.add(key);
+        routes.push({
+          type: 'page',
+          method: 'GET',
+          path: routePath,
+          source: path.join(pagesRel, relFile).split(path.sep).join('/'),
+          module: null,
+          moduleConfig: null,
+          target: 'pages',
+        });
+      }
+    }
+  }
+
+  const manifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    pagesDirRel: pagesRel,
+    scannedPagesFiles,
+    routes,
+  };
+
+  const outFile = options.outFile
+    ? path.resolve(options.outFile)
+    : (options.outDir
+        ? path.join(path.resolve(options.outDir), 'routes.manifest.json')
+        : path.join(rootDir, DEFAULT_MANIFEST_REL_PATH));
+
+  const outDir = path.dirname(outFile);
+  if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outFile, JSON.stringify(manifest, null, 2), 'utf8');
+
+  return {
+    manifest,
+    manifestPath: outFile,
+    routeCount: routes.length,
+    scannedFilesCount: scannedPagesFiles.length,
+  };
+}
+
+/**
+ * Loads an existing AOT route manifest from disk and reconstructs runtime descriptors.
+ *
+ * @param {Object} [options={}]
+ * @param {string} [options.rootDir=process.cwd()] - Project root directory
+ * @param {string} [options.manifestPath] - Explicit path to the manifest file
+ * @returns {{ manifest: Object, descriptors: Array<Object> }|null}
+ */
+function loadRouteManifest(options = {}) {
+  const opts = typeof options === 'string' ? { manifestPath: options } : options;
+  const rootDir = opts.rootDir ? path.resolve(opts.rootDir) : process.cwd();
+  const manifestPath = opts.manifestPath
+    ? path.resolve(opts.manifestPath)
+    : path.join(rootDir, DEFAULT_MANIFEST_REL_PATH);
+
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+
+    if (!manifest || !Array.isArray(manifest.routes)) {
+      return null;
+    }
+
+    const descriptors = [];
+    for (const r of manifest.routes) {
+      if (r.target === 'discovered') {
+        const absFile = path.resolve(rootDir, r.source);
+        descriptors.push({
+          type: r.type,
+          method: r.method,
+          path: r.path,
+          file: absFile,
+          source: r.source,
+          module: r.module || undefined,
+          moduleConfig: r.moduleConfig || undefined,
+        });
+      }
+    }
+
+    const pagesDirRel = manifest.pagesDirRel || 'pages';
+    descriptors.scannedPagesDir = path.resolve(rootDir, pagesDirRel);
+    descriptors.scannedPagesFiles = Array.isArray(manifest.scannedPagesFiles) ? manifest.scannedPagesFiles : [];
+
+    return {
+      manifest,
+      descriptors,
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
+module.exports = {
+  DEFAULT_MANIFEST_REL_PATH,
+  generateRouteManifest,
+  loadRouteManifest,
+};

package/src/discovery/scan-routes.js

@@ -13,28 +13,46 @@ const { discoverModuleDetails } = require('../modules/module-discovery');
 
 const SUPPORTED_EXTENSIONS = new Set(['.js', '.njk']);
 
+function getGenericSegment(name) {
+  if (name.startsWith('[') && name.endsWith(']')) {
+    const inner = name.slice(1, -1);
+    if (inner.startsWith('...')) return '*';
+    return ':param';
+  }
+  return name;
+}
+
 /**
  * Safely scans a directory recursively for route files
  * @param {string} dirPath - Absolute directory path
  * @param {string} [baseDir=dirPath] - Base directory for computing relative paths
+ * @param {boolean} [checkWarnings=false] - Whether to perform route collision & case-sensitivity checks
  * @returns {Array<{ absolutePath: string, relativePath: string }>}
  */
-function scanDirSafely(dirPath, baseDir = dirPath) {
+function scanDirSafely(dirPath, baseDir = dirPath, checkWarnings = false) {
   const results = [];
   if (!fs.existsSync(dirPath)) return results;
 
   try {
     const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    const kept = checkWarnings ? [] : null;
 
     for (const entry of entries) {
       const name = entry.name;
-      if (isPrivateOrIgnored(name)) continue;
+      if (name === 'locales' || isPrivateOrIgnored(name)) continue;
 
       const fullPath = path.join(dirPath, name);
       const relPath = path.relative(baseDir, fullPath);
 
+      if (checkWarnings && name !== name.toLowerCase()) {
+        console.warn(`[webspresso] WARNING: Path "pages/${relPath.split(path.sep).join('/')}" contains uppercase letters. Use lowercase to avoid routing issues on case-sensitive filesystems.`);
+      }
+
       if (entry.isDirectory()) {
-        results.push(...scanDirSafely(fullPath, baseDir));
+        results.push(...scanDirSafely(fullPath, baseDir, checkWarnings));
+        if (checkWarnings && !relPath.startsWith('api') && relPath !== 'api') {
+          kept.push({ name, isDir: true, original: name });
+        }
       } else if (entry.isFile()) {
         const ext = path.extname(name);
         if (SUPPORTED_EXTENSIONS.has(ext)) {
@@ -42,6 +60,30 @@ function scanDirSafely(dirPath, baseDir = dirPath) {
             absolutePath: fullPath,
             relativePath: relPath,
           });
+          if (checkWarnings) {
+            const base = path.basename(name, ext);
+            kept.push({ name: base, isDir: false, original: name });
+          }
+        }
+      }
+    }
+
+    if (checkWarnings && kept && kept.length > 1) {
+      const groups = new Map();
+      for (const item of kept) {
+        const normalized = getGenericSegment(item.name);
+        if (!groups.has(normalized)) {
+          groups.set(normalized, []);
+        }
+        groups.get(normalized).push(item);
+      }
+
+      for (const [norm, items] of groups.entries()) {
+        if (items.length > 1) {
+          const namesList = items.map((item) => `"${item.original}"`).join(' and ');
+          const relDir = path.relative(baseDir, dirPath);
+          const dirLabel = relDir ? `pages/${relDir.split(path.sep).join('/')}` : 'pages';
+          console.warn(`[webspresso] WARNING: Dynamic route collision in "${dirLabel}": ${namesList} resolve to the same segment "${norm}" and will conflict at runtime.`);
         }
       }
     }
@@ -52,6 +94,19 @@ function scanDirSafely(dirPath, baseDir = dirPath) {
   return results;
 }
 
+let isWebspressoPackageCache = null;
+function checkIsWebspressoPackage() {
+  if (isWebspressoPackageCache === null) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+      isWebspressoPackageCache = Boolean(pkg && pkg.name === 'webspresso');
+    } catch (_) {
+      isWebspressoPackageCache = false;
+    }
+  }
+  return isWebspressoPackageCache;
+}
+
 /**
  * Scans configured pages, api, and module directories
  * @param {Object} options
@@ -64,10 +119,7 @@ function scanDirSafely(dirPath, baseDir = dirPath) {
 function scanRoutes(options = {}) {
   const rootDir = options.rootDir || (() => {
     if (process.env.NODE_ENV === 'test') {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
-        if (pkg.name === 'webspresso') return process.cwd();
-      } catch (_) {}
+      if (checkIsWebspressoPackage()) return process.cwd();
       return path.resolve(__dirname, '../..');
     }
     return process.cwd();
@@ -93,9 +145,12 @@ function scanRoutes(options = {}) {
       : resolveDirCandidate(['src/pages', 'pages']);
 
     if (pagesDir && fs.existsSync(pagesDir)) {
-      const files = scanDirSafely(pagesDir);
+      const files = scanDirSafely(pagesDir, pagesDir, true);
       const filesSet = new Set(files.map((f) => f.absolutePath));
 
+      descriptors.scannedPagesDir = path.resolve(pagesDir);
+      descriptors.scannedPagesFiles = files.map((f) => f.relativePath);
+
       for (const { absolutePath, relativePath } of files) {
         // Skip .njk templates (handled by classic Nunjucks mountPages)
         if (relativePath.endsWith('.njk')) {
@@ -268,7 +323,28 @@ function scanRoutes(options = {}) {
   return descriptors;
 }
 
+/**
+ * Unified discovery of application routes (pages, api, modules) and compilation into a RouteTable
+ * @param {Object} options
+ * @returns {{ descriptors: Array<Object>, routeTable: import('../routing/route-table').RouteTable, scannedPagesFiles: Array<string>, scannedPagesDir: string|null }}
+ */
+function discoverAppRoutes(options = {}) {
+  const { compileRouteTable } = require('../routing/route-table');
+  const descriptors = scanRoutes(options);
+  const routeTable = compileRouteTable(descriptors, {
+    explicitRoutes: options.routes || [],
+    isDev: options.isDev,
+  });
+  return {
+    descriptors,
+    routeTable,
+    scannedPagesFiles: descriptors.scannedPagesFiles || [],
+    scannedPagesDir: descriptors.scannedPagesDir || null,
+  };
+}
+
 module.exports = {
   scanRoutes,
   scanDirSafely,
+  discoverAppRoutes,
 };