@junejs/server 1.0.0-dev.36 → 1.0.0-dev.45

package/src/route-scan.ts

@@ -8,6 +8,8 @@ import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
 
+import { parseSegment } from "./route-rank";
+
 // The segment layout CHAIN root→leaf: every directory level (route groups
 // included) may contribute a layout.* that wraps routes below it.
 export type RouteEntry = {
@@ -15,6 +17,7 @@ export type RouteEntry = {
   file: string;
   dynamic: boolean;
   resource?: boolean; // a route.* resource route (raw-Response handler), not a page
+  generated?: boolean; // scanned from .june/routes/ — ranks after every app/ route, as in dev
   layouts: string[];
   loading?: string; // nearest loading.tsx up the tree → streaming Suspense fallback
 };
@@ -77,8 +80,82 @@ export async function scanAppRoutes(appRoot: string): Promise<RouteEntry[]> {
   const juneRoutesDir = join(appRoot, ".june", "routes");
   const appRoutes = await scanRoutes(appDir);
   const frameworkRoutes = existsSync(juneRoutesDir) ? await scanRoutes(juneRoutesDir) : [];
+  const problems = routeProblems([appRoutes, frameworkRoutes], appRoot);
+  if (problems) throw new Error(problems);
   const appPaths = new Set(appRoutes.map((r) => r.path));
-  return [...appRoutes, ...frameworkRoutes.filter((r) => !appPaths.has(r.path))].sort((a, b) =>
+  const generated = frameworkRoutes
+    .filter((r) => !appPaths.has(r.path))
+    .map((r) => ({ ...r, generated: true }));
+  return [...appRoutes, ...generated].sort((a, b) =>
     a.path.localeCompare(b.path),
   );
 }
+
+// Two route files in ONE tree that resolve to the same URL: `(a)/about/page.tsx`
+// and `(b)/about/page.tsx` (groups vanish from the URL), or `page.tsx` next to
+// `index.tsx`. Pages and resource routes are counted apart — a page and a
+// route.ts at the same path are allowed, in one dir or across groups (the page
+// wins). No winner is defined for the rest: dev
+// would pick by group order and the worker by scan order, so the build refuses
+// them and dev reports them (#316).
+export function routeConflicts(routes: RouteEntry[]): Array<{ path: string; files: string[] }> {
+  const byKey = new Map<string, { path: string; files: string[] }>();
+  for (const r of routes) {
+    const key = `${r.resource ? "route" : "page"} ${r.path}`;
+    const hit = byKey.get(key);
+    if (hit) hit.files.push(r.file);
+    else byKey.set(key, { path: r.path, files: [r.file] });
+  }
+  return [...byKey.values()]
+    .filter((c) => c.files.length > 1)
+    .map((c) => ({ path: c.path, files: c.files.sort() }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// An optional or catch-all segment ([[x]], [...x], [[...x]]) must END the route
+// path (#315, the Next.js rule, opinionated). Mid-path there is no behavior to
+// keep: dev never matched past a catch-all nor skipped a mid-path [[x]], while
+// the worker's regex did both. A (group) after it is not a URL segment, so it's
+// fine. Returns the offending routes, path-sorted.
+const ENDS_PATH = new Set(["optional", "catchAll", "optionalCatchAll"]);
+const beforeLast = (path: string) => path.split("/").filter(Boolean).slice(0, -1).map((s) => parseSegment(s).kind);
+
+export function misplacedSegments(routes: RouteEntry[]): RouteEntry[] {
+  return routes
+    .filter((r) => beforeLast(r.path).some((k) => ENDS_PATH.has(k)))
+    .sort((a, b) => a.path.localeCompare(b.path) || a.file.localeCompare(b.file));
+}
+
+// Every route-table problem the build refuses and dev reports, as one message
+// (null when there are none). Each tree (app/, .june/routes/) is checked on its
+// own: the same path in both is not a conflict — app/ wins.
+export function routeProblems(trees: RouteEntry[][], appRoot: string): string | null {
+  const rel = (f: string) => relative(appRoot, f).split(sep).join("/");
+  const sections: string[] = [];
+
+  const conflicts = trees.flatMap(routeConflicts);
+  if (conflicts.length) {
+    sections.push(
+      "[june] more than one route file resolves to the same path — keep one per path:\n" +
+        conflicts.map((c) => `  ${c.path}: ${c.files.map(rel).join(", ")}`).join("\n"),
+    );
+  }
+
+  const misplaced = trees.flatMap(misplacedSegments);
+  if (misplaced.length) {
+    const lines = misplaced.map((r) => `  ${r.path}: ${rel(r.file)}`);
+    // Developers (and models) read [[x]] the SvelteKit way, skippable anywhere;
+    // say so when a single optional is the culprit, and point at the real tool.
+    if (misplaced.some((r) => beforeLast(r.path).includes("optional"))) {
+      lines.push(
+        "  Unlike SvelteKit, June does not skip a [[param]] mid-path. For a locale prefix, set i18n.locales in june.config.ts instead of a [[lang]] directory.",
+      );
+    }
+    sections.push(
+      "[june] an optional or catch-all segment must be the last segment of a route path — nothing may follow it:\n" +
+        lines.join("\n"),
+    );
+  }
+
+  return sections.length ? sections.join("\n") : null;
+}

package/src/router.ts

@@ -6,6 +6,8 @@ import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 
+import { compareSegments, parseSegment } from "./route-rank";
+
 export type RouteMatch = {
   file: string;
   params: Record<string, string>;
@@ -87,13 +89,13 @@ function isSpecialFile(file: string) {
 }
 
 const isRouteGroup = (name: string) => /^\(.+\)$/.test(name);
-const isParamDir = (name: string) => /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
+const isParamDir = (name: string) => parseSegment(name).kind === "param";
 // [[slug]] / [[...slug]] — match like their required forms, and ALSO match the
 // segment being absent (the param is then simply missing from ctx.params).
-const isOptionalDir = (name: string) => /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isOptionalCatchAllDir = (name: string) => /^\[\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]\]$/.test(name);
-const isCatchAllDir = (name: string) => /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/.test(name);
-const paramName = (name: string) => name.replace(/^\[+(\.\.\.)?|\]+$/g, "");
+const isOptionalDir = (name: string) => parseSegment(name).kind === "optional";
+const isOptionalCatchAllDir = (name: string) => parseSegment(name).kind === "optionalCatchAll";
+const isCatchAllDir = (name: string) => parseSegment(name).kind === "catchAll";
+const paramName = (name: string) => parseSegment(name).name!;
 
 type DirEntry = { name: string; dir: boolean };
 
@@ -147,8 +149,12 @@ function routePath(appDir: string, file: string) {
 }
 
 // Recursive-descent matcher over the app directory. Priority at every level:
-// exact static segment > [param] > [...catchAll]; route groups `(name)` descend
-// without consuming a URL segment; `_`-prefixed entries never participate.
+// exact static segment > [param] > [...catchAll], required before optional, ties
+// by name (route-rank.ts — the built worker sorts its route table by the same
+// ranking); `_`-prefixed entries never participate. Route groups `(name)` are
+// invisible in the URL, so they are invisible to ranking too: a group's children
+// compete as siblings of the level the group sits in (a grouped `[slug]` never
+// shadows a static sibling), while the group still contributes its layout.
 // Returns the page file, accumulated params (catch-all joins with "/"), and the
 // chain of segments (with their special files) from the app root to the page.
 export async function matchRouteTree(
@@ -158,85 +164,96 @@ export async function matchRouteTree(
 ): Promise<RouteTreeMatch | null> {
   const urlSegments = pathname.split("/").filter(Boolean).map(decodeURIComponent);
 
+  // One URL level = this dir plus every route group under it (groups nest), each
+  // with the segment chain down to it: the dir first, then groups in name order.
+  type Level = { dir: string; entries: DirEntry[]; segments: SegmentMatch[] };
+  async function levelAt(dir: string, chain: SegmentMatch[]): Promise<Level[]> {
+    // Ranked, not readdir order, so the pick is the same on every filesystem.
+    const entries = (await listDir(dir)).sort((a, b) => compareSegments(a.name, b.name));
+    const segments = [...chain, segmentAt(dir, entries)];
+    const levels: Level[] = [{ dir, entries, segments }];
+    for (const e of entries) {
+      if (e.dir && isRouteGroup(e.name)) levels.push(...(await levelAt(join(dir, e.name), segments)));
+    }
+    return levels;
+  }
+
+  // A URL level can span several real dirs: `(a)/blog` and `(b)/blog` are both
+  // `/blog`, so they descend TOGETHER — otherwise (a)/blog/[slug] would answer
+  // /blog/about before (b)/blog/about was ever seen.
+  type Node = { dir: string; chain: SegmentMatch[] };
+
   async function descend(
-    dir: string,
+    nodes: Node[],
     rest: string[],
     params: Record<string, string>,
-    chain: SegmentMatch[],
   ): Promise<RouteTreeMatch | null> {
-    const entries = await listDir(dir);
-    const segments = [...chain, segmentAt(dir, entries)];
+    const levels = (await Promise.all(nodes.map((n) => levelAt(n.dir, n.chain)))).flat();
 
-    // Terminal: URL consumed → find the page (or resource route) in this dir.
+    // Terminal: URL consumed → find the page at this level, groups included,
+    // and only then a resource route: a page beats a route.ts at the same path
+    // even when the two sit in different groups (the worker ranks them so).
     if (rest.length === 0) {
-      const page =
-        fileFor(entries, dir, "page") ??
-        fileFor(entries, dir, "index") ??
-        fileFor(entries, dir, "route");
-      if (page) return { file: page, params, segments };
-    } else if (!options.pageConvention) {
+      for (const base of [["page", "index"], ["route"]]) {
+        for (const { dir: d, entries, segments } of levels) {
+          const file = base.map((b) => fileFor(entries, d, b)).find(Boolean);
+          if (file) return { file, params, segments };
+        }
+      }
+    } else if (!options.pageConvention && rest.length === 1) {
       // Legacy flat convention: a non-special leaf FILE names the final segment
       // (examples/rsc: about.tsx → /about). Only valid for the last segment.
-      if (rest.length === 1) {
-        const leaf = fileFor(entries, dir, rest[0]!);
-        if (leaf && !isSpecialFile(leaf) && !isPageFile(leaf)) {
-          return { file: leaf, params, segments };
-        }
+      for (const { dir: d, entries, segments } of levels) {
+        const leaf = fileFor(entries, d, rest[0]!);
+        if (leaf && !isSpecialFile(leaf) && !isPageFile(leaf)) return { file: leaf, params, segments };
       }
     }
 
-    // Route groups: try descending into every (group) without consuming URL.
-    for (const e of entries) {
-      if (!e.dir || !isRouteGroup(e.name)) continue;
-      const hit = await descend(join(dir, e.name), rest, params, segments);
-      if (hit) return hit;
+    // Every child dir at this level, groups flattened and same names merged, in
+    // rank order.
+    const children = new Map<string, Node[]>();
+    for (const lv of levels) {
+      for (const e of lv.entries) {
+        if (!e.dir || isRouteGroup(e.name)) continue;
+        const node = { dir: join(lv.dir, e.name), chain: lv.segments };
+        const same = children.get(e.name);
+        if (same) same.push(node);
+        else children.set(e.name, [node]);
+      }
     }
+    const names = [...children.keys()].sort(compareSegments);
 
     if (rest.length === 0) {
       // Optional segments match ABSENCE too: descend without consuming and
       // without setting the param.
-      for (const e of entries) {
-        if (!e.dir || !(isOptionalDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
-        const hit = await descend(join(dir, e.name), [], params, segments);
+      for (const name of names) {
+        if (!(isOptionalDir(name) || isOptionalCatchAllDir(name))) continue;
+        const hit = await descend(children.get(name)!, [], params);
         if (hit) return hit;
       }
       return null;
     }
     const [head, ...tail] = rest as [string, ...string[]];
 
-    // 1) exact static dir
-    const exact = entries.find((e) => e.dir && e.name === head);
-    if (exact) {
-      const hit = await descend(join(dir, head), tail, params, segments);
-      if (hit) return hit;
-    }
-    // 2) [param] and [[param]] dirs consume one segment
-    for (const e of entries) {
-      if (!e.dir || !(isParamDir(e.name) || isOptionalDir(e.name))) continue;
-      const hit = await descend(
-        join(dir, e.name),
-        tail,
-        { ...params, [paramName(e.name)]: head },
-        segments,
-      );
-      if (hit) return hit;
-    }
-    // 3) [...catchAll] and [[...catchAll]] dirs consume everything remaining
-    for (const e of entries) {
-      if (!e.dir || !(isCatchAllDir(e.name) || isOptionalCatchAllDir(e.name))) continue;
-      const hit = await descend(
-        join(dir, e.name),
-        [],
-        { ...params, [paramName(e.name)]: rest.join("/") },
-        segments,
-      );
+    for (const name of names) {
+      const into = children.get(name)!;
+      let hit: RouteTreeMatch | null = null;
+      if (isParamDir(name) || isOptionalDir(name)) {
+        // [param] and [[param]] consume one segment
+        hit = await descend(into, tail, { ...params, [paramName(name)]: head });
+      } else if (isCatchAllDir(name) || isOptionalCatchAllDir(name)) {
+        // [...catchAll] and [[...catchAll]] consume everything remaining
+        hit = await descend(into, [], { ...params, [paramName(name)]: rest.join("/") });
+      } else if (name === head) {
+        hit = await descend(into, tail, params); // exact static dir
+      }
       if (hit) return hit;
     }
 
     return null;
   }
 
-  return descend(appDir, urlSegments, {}, []);
+  return descend([{ dir: appDir, chain: [] }], urlSegments, {});
 }
 
 // 404 path: walk the longest matchable STATIC prefix of the URL collecting

package/src/worker.ts

@@ -22,6 +22,7 @@ import type { Channel, ChannelFactory } from "@junejs/core/agent-config";
 import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
 import { durableAgentSurface, durableChannelSurface, type DurableObjectNamespace } from "./agent-durable";
 import { acceptTarget } from "./negotiate";
+import { compareRoutePatterns, parseSegment } from "./route-rank";
 import { contentTypeFor, RESERVED_PREFIX, safeRelativePath } from "./static-files";
 
 // The slice of workerd's ExecutionContext the worker threads through: webhook
@@ -37,8 +38,13 @@ export type WorkerManifest = {
   // Dynamic patterns in file-route syntax ("/posts/[slug]", "/docs/[...path]").
   dynamicRoutes?: Array<{ pattern: string; def: BrandedRoute }>;
   // Resource routes (app/**/route.*): a raw-Response handler keyed by its pattern
-  // (static or dynamic). Matched after pages, so a page never gets shadowed.
+  // (static or dynamic). Ranked with the pages by segment shape (route-rank.ts),
+  // exactly as `june dev` resolves; a page wins only at the SAME pattern.
   resourceRoutes?: Array<{ pattern: string; handler: ResourceHandler }>;
+  // Patterns scanned from .june/routes/ (framework-generated, e.g. Kura). Dev
+  // consults app/ first and falls back to .june/routes/, so every one of these
+  // ranks after every app/ route. Absent → all routes are app/ routes.
+  generatedRoutes?: string[];
   // Layout chains (root→leaf) keyed by route path / dynamic pattern. The build
   // freezes the same chain the dev server loads from app/layout.* files.
   layoutChains?: Record<string, LayoutComponent[]>;
@@ -83,7 +89,13 @@ export type WorkerManifest = {
   services?: (env?: unknown) => unknown;
 };
 
-type Compiled = { regex: RegExp; names: string[]; def: BrandedRoute; pattern: string };
+// One row of the worker's route table: a page (def) or a resource route (handler).
+type Compiled = {
+  regex: RegExp;
+  names: string[];
+  pattern: string;
+  generated: boolean;
+} & ({ def: BrandedRoute; handler?: undefined } | { def?: undefined; handler: ResourceHandler });
 
 // "/posts/[slug]" | "/docs/[...path]" | "/notes/[[tag]]" → matcher. Optional
 // segments ([[x]], [[...x]]) wrap slash + capture together so absence matches;
@@ -93,34 +105,19 @@ function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
   let source = "";
   let allOptional = true;
   for (const seg of pattern.split("/").filter(Boolean)) {
-    const oca = seg.match(/^\[\[\.\.\.(\w+)\]\]$/);
-    if (oca) {
-      names.push(oca[1]!);
-      source += "(?:/(.+))?";
-      continue;
-    }
-    const ca = seg.match(/^\[\.\.\.(\w+)\]$/);
-    if (ca) {
-      names.push(ca[1]!);
-      source += "/(.+)";
+    // Same grammar as the dev matcher (route-rank.ts parseSegment).
+    const { kind, name } = parseSegment(seg);
+    if (name) names.push(name);
+    if (kind === "optionalCatchAll") source += "(?:/(.+))?";
+    else if (kind === "optional") source += "(?:/([^/]+))?";
+    else {
+      if (kind === "catchAll") source += "/(.+)";
+      else if (kind === "param") source += "/([^/]+)";
+      // A static segment matches literally: escape every RegExp metacharacter,
+      // brackets included (`docs[v2`, `[slug].png` are static names).
+      else source += "/" + seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
       allOptional = false;
-      continue;
-    }
-    const op = seg.match(/^\[\[(\w+)\]\]$/);
-    if (op) {
-      names.push(op[1]!);
-      source += "(?:/([^/]+))?";
-      continue;
     }
-    const p = seg.match(/^\[(\w+)\]$/);
-    if (p) {
-      names.push(p[1]!);
-      source += "/([^/]+)";
-      allOptional = false;
-      continue;
-    }
-    source += "/" + seg.replace(/[.*+?^${}()|\\]/g, "\\$&");
-    allOptional = false;
   }
   if (source === "") return { regex: /^\/$/, names };
   return { regex: new RegExp(allOptional ? `^(?:${source}|/)$` : `^${source}$`), names };
@@ -132,16 +129,23 @@ export function createWorker(
   manifest: WorkerManifest,
   opts: { staticBuild?: boolean } = {},
 ): { fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response> } {
-  const dynamic: Compiled[] = (manifest.dynamicRoutes ?? []).map((d) => ({
-    ...compilePattern(d.pattern),
-    def: d.def,
-    pattern: d.pattern,
-  }));
-  const resources = (manifest.resourceRoutes ?? []).map((r) => ({
-    ...compilePattern(r.pattern),
-    handler: r.handler,
-    pattern: r.pattern,
-  }));
+  // Pages and resource routes in ONE table, ordered the way `june dev` resolves
+  // (#312): app/ before .june/routes/, then segment shape (static > [param] >
+  // [...catchAll], required before optional), then a page before a resource
+  // route at the same pattern. The kind of route never outranks the shape.
+  const generated = new Set(manifest.generatedRoutes ?? []);
+  const row = (pattern: string) => ({ ...compilePattern(pattern), pattern, generated: generated.has(pattern) });
+  const table: Compiled[] = [
+    ...Object.entries(manifest.routes).map(([pattern, def]) => ({ ...row(pattern), def })),
+    ...(manifest.dynamicRoutes ?? []).map((d) => ({ ...row(d.pattern), def: d.def })),
+    ...(manifest.resourceRoutes ?? []).map((r) => ({ ...row(r.pattern), handler: r.handler })),
+  ];
+  table.sort(
+    (a, b) =>
+      Number(a.generated) - Number(b.generated) ||
+      compareRoutePatterns(a.pattern, b.pattern) ||
+      Number(!!a.handler) - Number(!!b.handler),
+  );
   const routeList = [
     ...Object.keys(manifest.routes),
     ...(manifest.dynamicRoutes ?? []).map((d) => d.pattern),
@@ -151,6 +155,17 @@ export function createWorker(
   const loadingFor = (key: string): LoadingComponent | undefined => manifest.loadings?.[key];
   const boundaryFor = (key: string): { index: number; key: string } | null =>
     manifest.layoutBoundaries?.[key] ?? null;
+  const resolvedPage = (def: BrandedRoute, key: string, params: Record<string, string>): Resolved => {
+    const b = boundaryFor(key);
+    return {
+      def,
+      params,
+      chain: chainFor(key),
+      boundaryIndex: b?.index ?? null,
+      boundaryKey: b?.key ?? null,
+      loading: loadingFor(key),
+    };
+  };
 
   // The worker's env (D1/KV/R2 bindings) arrives per fetch and is stable across
   // requests in an isolate; we capture the latest and hand it to the env-aware
@@ -224,52 +239,21 @@ export function createWorker(
     resources: provider ? () => provider(currentEnv) : undefined,
     services: servicesProvider ? () => (servicesCache ??= { v: servicesProvider(currentEnv) }).v : undefined,
     resolve: async (pathname): Promise<Resolved | ResolvedResource | null> => {
+      // Fast path: an app/ static page outranks every other route for its path.
       const staticDef = manifest.routes[pathname];
-      if (staticDef) {
-        const b = boundaryFor(pathname);
-        return {
-          def: staticDef,
-          params: {},
-          chain: chainFor(pathname),
-          boundaryIndex: b?.index ?? null,
-          boundaryKey: b?.key ?? null,
-          loading: loadingFor(pathname),
-        };
-      }
-      for (const d of dynamic) {
-        const m = pathname.match(d.regex);
-        if (m) {
-          // Optional segments leave their capture undefined — the param is
-          // then absent, matching the dev matcher's semantics.
-          const params = Object.fromEntries(
-            d.names.flatMap((n, i) => {
-              const v = m[i + 1];
-              return v === undefined ? [] : [[n, decodeURIComponent(v)]];
-            }),
-          );
-          const b = boundaryFor(d.pattern);
-          return {
-            def: d.def,
-            params,
-            chain: chainFor(d.pattern),
-            boundaryIndex: b?.index ?? null,
-            boundaryKey: b?.key ?? null,
-            loading: loadingFor(d.pattern),
-          };
-        }
-      }
-      // Resource routes after pages (so a page is never shadowed by one).
-      for (const r of resources) {
+      if (staticDef && !generated.has(pathname)) return resolvedPage(staticDef, pathname, {});
+      for (const r of table) {
         const m = pathname.match(r.regex);
-        if (m) {
-          const params = Object.fromEntries(
-            r.names.flatMap((n, i) => {
-              const v = m[i + 1];
-              return v === undefined ? [] : [[n, decodeURIComponent(v)]];
-            }),
-          );
-          return { handler: r.handler, params };
-        }
+        if (!m) continue;
+        // Optional segments leave their capture undefined — the param is
+        // then absent, matching the dev matcher's semantics.
+        const params = Object.fromEntries(
+          r.names.flatMap((n, i) => {
+            const v = m[i + 1];
+            return v === undefined ? [] : [[n, decodeURIComponent(v)]];
+          }),
+        );
+        return r.handler ? { handler: r.handler, params } : resolvedPage(r.def, r.pattern, params);
       }
       return null;
     },

package/dist/route-scan-DMlwoESy.d.ts

@@ -1,13 +0,0 @@
-//#region src/route-scan.d.ts
-type RouteEntry = {
-  path: string;
-  file: string;
-  dynamic: boolean;
-  resource?: boolean;
-  layouts: string[];
-  loading?: string;
-};
-declare function scanRoutes(appDir: string, dir?: string, layouts?: string[], out?: RouteEntry[], loading?: string): Promise<RouteEntry[]>;
-declare function scanAppRoutes(appRoot: string): Promise<RouteEntry[]>;
-//#endregion
-export { scanAppRoutes as n, scanRoutes as r, RouteEntry as t };