@jay-framework/stack-route-scanner 0.14.0 → 0.15.0

package/dist/index.d.mts

@@ -14,9 +14,9 @@ type JayRoute = {
     jayHtmlPath: string;
     compPath: string;
     /**
-     * For static override routes, inferred params from sibling dynamic routes.
-     * e.g., /products/ceramic-flower-vase has inferredParams: { slug: 'ceramic-flower-vase' }
-     * when /products/[slug] exists as a sibling.
+     * Explicit params declared via <script type="application/jay-params"> in the jay-html.
+     * Used by static override routes to provide param values.
+     * e.g., /products/ceramic-flower-vase declares { slug: 'ceramic-flower-vase' }.
      */
     inferredParams?: Record<string, string>;
 };
@@ -30,33 +30,8 @@ interface ScanFilesOptions {
  * Static routes come before dynamic routes at the same position.
  */
 declare function sortRoutesByPriority(routes: JayRoutes): JayRoutes;
-/**
- * Result of param inference for logging/debugging.
- */
-interface ParamInferenceResult {
-    staticRoute: string;
-    dynamicRoute: string;
-    inferredParams: Record<string, string>;
-}
-/**
- * Infer params for static routes based on sibling dynamic routes.
- *
- * For each fully-static route, find a sibling dynamic route and map
- * the static segment values to the param names from the dynamic route.
- *
- * Example:
- *   /products/ceramic-flower-vase (static)
- *   /products/[slug] (dynamic sibling)
- *   → inferredParams: { slug: 'ceramic-flower-vase' }
- *
- * Returns the routes with inferred params added, plus an inference log.
- */
-declare function inferParamsForStaticRoutes(routes: JayRoutes): {
-    routes: JayRoutes;
-    inferenceLog: ParamInferenceResult[];
-};
 declare function scanRoutes(baseDir: string, options: ScanFilesOptions): Promise<JayRoutes>;
 
 declare function routeToExpressRoute(route: JayRoute): string;
 
-export { type JayRoute, type JayRouteParam, JayRouteParamType, type JayRouteSegment, type JayRoutes, type ParamInferenceResult, type ScanFilesOptions, inferParamsForStaticRoutes, routeToExpressRoute, scanRoutes, sortRoutesByPriority };
+export { type JayRoute, type JayRouteParam, JayRouteParamType, type JayRouteSegment, type JayRoutes, type ScanFilesOptions, routeToExpressRoute, scanRoutes, sortRoutesByPriority };

package/dist/index.mjs

@@ -1,5 +1,7 @@
 import { promises } from "fs";
 import path from "path";
+import { parse } from "node-html-parser";
+import YAML from "yaml";
 import { getLogger } from "@jay-framework/logger";
 var JayRouteParamType = /* @__PURE__ */ ((JayRouteParamType2) => {
   JayRouteParamType2[JayRouteParamType2["single"] = 0] = "single";
@@ -35,6 +37,15 @@ async function scanDirectory(BASE_DIR, directory, options) {
       routes = [...routes, ...await scanDirectory(BASE_DIR, fullPath, options)];
     } else if (item.name === options.jayHtmlFilename) {
       const route = convertToRoutePath(BASE_DIR, fullPath, options);
+      const { params, validations } = await parseJayParams(fullPath);
+      if (params) {
+        route.inferredParams = params;
+      }
+      if (validations.length > 0) {
+        for (const v of validations) {
+          getLogger().warn(`[route-scanner] ${route.rawRoute}: ${v}`);
+        }
+      }
       routes.push(route);
     }
   }
@@ -76,73 +87,60 @@ function compareRoutes(a, b) {
 function sortRoutesByPriority(routes) {
   return [...routes].sort(compareRoutes);
 }
-function hasDynamicSegments(route) {
-  return route.segments.some((seg) => typeof seg !== "string");
+function dedentYaml(text) {
+  const lines = text.split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length === 0)
+    return "";
+  const minIndent = Math.min(...lines.map((l) => l.match(/^\s*/)?.[0].length ?? 0));
+  return lines.map((l) => l.slice(minIndent)).join("\n");
 }
-function isFullyStaticRoute(route) {
-  return route.segments.every((seg) => typeof seg === "string");
-}
-function dynamicRouteCouldMatch(staticRoute, dynamicRoute) {
-  if (staticRoute.segments.length !== dynamicRoute.segments.length)
-    return false;
-  if (staticRoute.segments.length === 0)
-    return false;
-  for (let i = 0; i < staticRoute.segments.length; i++) {
-    const staticSeg = staticRoute.segments[i];
-    const dynSeg = dynamicRoute.segments[i];
-    if (typeof staticSeg !== "string")
-      return false;
-    if (typeof dynSeg === "string") {
-      if (staticSeg !== dynSeg)
-        return false;
-    }
+async function parseJayParams(jayHtmlPath) {
+  let content;
+  try {
+    content = await promises.readFile(jayHtmlPath, "utf-8");
+  } catch {
+    return { params: void 0, validations: [] };
   }
-  return true;
-}
-function inferParamsForStaticRoutes(routes) {
-  const inferenceLog = [];
-  const dynamicRoutes = routes.filter(hasDynamicSegments);
-  const enrichedRoutes = routes.map((route) => {
-    if (!isFullyStaticRoute(route))
-      return route;
-    if (route.segments.length === 0)
-      return route;
-    const dynamicSibling = dynamicRoutes.find((dyn) => dynamicRouteCouldMatch(route, dyn));
-    if (!dynamicSibling)
-      return route;
-    const inferredParams = {};
-    for (let i = 0; i < route.segments.length; i++) {
-      const staticSeg = route.segments[i];
-      const dynSeg = dynamicSibling.segments[i];
-      if (typeof staticSeg === "string" && typeof dynSeg !== "string") {
-        inferredParams[dynSeg.name] = staticSeg;
-      }
-    }
-    if (Object.keys(inferredParams).length === 0)
-      return route;
-    inferenceLog.push({
-      staticRoute: route.rawRoute,
-      dynamicRoute: dynamicSibling.rawRoute,
-      inferredParams
-    });
-    return { ...route, inferredParams };
+  const root = parse(content, {
+    comment: true,
+    blockTextElements: { script: true, style: true }
   });
-  return { routes: enrichedRoutes, inferenceLog };
+  const head = root.querySelector("head");
+  const paramScripts = (head ?? root).querySelectorAll('script[type="application/jay-params"]');
+  if (paramScripts.length === 0)
+    return { params: void 0, validations: [] };
+  if (paramScripts.length > 1) {
+    return {
+      params: void 0,
+      validations: [
+        'Multiple <script type="application/jay-params"> tags found — expected at most one'
+      ]
+    };
+  }
+  const body = dedentYaml(paramScripts[0].textContent ?? "");
+  if (!body)
+    return { params: void 0, validations: [] };
+  try {
+    return { params: YAML.parse(body), validations: [] };
+  } catch (e) {
+    return {
+      params: void 0,
+      validations: [`Failed to parse jay-params YAML: ${e.message}`]
+    };
+  }
 }
 async function scanRoutes(baseDir, options) {
   const BASE_DIR = path.resolve(baseDir);
   const routes = await scanDirectory(BASE_DIR, BASE_DIR, options);
   const sortedRoutes = sortRoutesByPriority(routes);
-  const { routes: enrichedRoutes, inferenceLog } = inferParamsForStaticRoutes(sortedRoutes);
-  if (inferenceLog.length > 0) {
-    getLogger().info("[route-scanner] Inferred params for static override routes:");
-    for (const entry of inferenceLog) {
-      getLogger().info(
-        `  ${entry.staticRoute} → params from ${entry.dynamicRoute}: ${JSON.stringify(entry.inferredParams)}`
-      );
+  const routesWithParams = sortedRoutes.filter((r) => r.inferredParams);
+  if (routesWithParams.length > 0) {
+    getLogger().info("[route-scanner] Routes with explicit params (jay-params):");
+    for (const route of routesWithParams) {
+      getLogger().info(`  ${route.rawRoute} → ${JSON.stringify(route.inferredParams)}`);
     }
   }
-  return enrichedRoutes;
+  return sortedRoutes;
 }
 function routeToExpressRoute(route) {
   return "/" + route.segments.map((segment) => {
@@ -160,7 +158,6 @@ function routeToExpressRoute(route) {
 }
 export {
   JayRouteParamType,
-  inferParamsForStaticRoutes,
   routeToExpressRoute,
   scanRoutes,
   sortRoutesByPriority

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-route-scanner",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "Apache-2.0",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -9,7 +9,9 @@
     "readme.md"
   ],
   "dependencies": {
-    "@jay-framework/logger": "^0.14.0"
+    "@jay-framework/logger": "^0.15.0",
+    "node-html-parser": "^6.1.12",
+    "yaml": "^2.3.4"
   },
   "scripts": {
     "build": "npm run build:js && npm run build:types",
@@ -23,7 +25,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.14.0",
+    "@jay-framework/dev-environment": "^0.15.0",
     "@types/node": "^20.11.5",
     "nodemon": "^3.0.3",
     "replace-in-file": "^7.1.0",