@spfn/core 0.3.0-beta.11 → 0.3.0-beta.13

package/dist/codegen/index.js

@@ -1,9 +1,10 @@
 import { watch } from 'chokidar';
-import { join, relative, sep, dirname, resolve } from 'path';
+import { join, relative, sep, dirname, resolve, isAbsolute } from 'path';
 import mm from 'micromatch';
 import { logger } from '@spfn/core/logger';
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, readdirSync } from 'fs';
 import { createJiti } from 'jiti';
+import { createRequire } from 'module';
 import { collectContractDocument, writeCurrentDocument, checkContract, formatViolations } from '@spfn/core/contract';
 
 // src/codegen/core/orchestrator.ts
@@ -334,70 +335,454 @@ async function createGeneratorsFromConfig(config, cwd) {
   }
   return generators2;
 }
-var genLogger = logger.child("@spfn/core:route-map-generator");
-function parseRouteFile(filePath) {
-  const routes = [];
-  try {
-    const content = readFileSync(filePath, "utf-8");
-    const routePattern = /export\s+const\s+(\w+)\s*=\s*route\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/gi;
-    let match;
-    while ((match = routePattern.exec(content)) !== null) {
-      const [, name, method, path] = match;
-      routes.push({
-        name,
-        method: method.toUpperCase(),
-        path,
-        file: filePath
-      });
+var compiler;
+function typescript() {
+  compiler ??= createRequire(import.meta.url)("typescript");
+  return compiler;
+}
+
+// src/codegen/generators/contract-guard.ts
+var ConditionalRegistrationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConditionalRegistrationError";
+  }
+};
+function assertUnconditionalRegistration(scan) {
+  const compiler2 = typescript();
+  const file = compiler2.createSourceFile(
+    scan.routerPath,
+    scan.source,
+    compiler2.ScriptTarget.Latest,
+    /* setParentNodes */
+    false
+  );
+  const declarations = topLevelInitialisers(compiler2, file);
+  const routes = routesLiteral(compiler2, declarations.get(scan.exportName), declarations, /* @__PURE__ */ new Set());
+  if (routes) {
+    assertLiteral(compiler2, file, routes, declarations, /* @__PURE__ */ new Set(), scan);
+  }
+}
+function topLevelInitialisers(compiler2, file) {
+  const found = /* @__PURE__ */ new Map();
+  for (const statement of file.statements) {
+    if (compiler2.isExportAssignment(statement) && !statement.isExportEquals) {
+      found.set("default", statement.expression);
     }
-  } catch (error) {
-    genLogger.warn(`Failed to parse route file: ${filePath}`, error);
+    if (compiler2.isVariableStatement(statement)) {
+      collectDeclarations(compiler2, statement, found);
+    }
+  }
+  for (const statement of file.statements) {
+    collectRenamedExports(compiler2, statement, found);
+  }
+  return found;
+}
+function collectDeclarations(compiler2, statement, found) {
+  for (const declaration of statement.declarationList.declarations) {
+    if (compiler2.isIdentifier(declaration.name) && declaration.initializer) {
+      found.set(declaration.name.text, declaration.initializer);
+    }
+  }
+}
+function collectRenamedExports(compiler2, statement, found) {
+  if (!compiler2.isExportDeclaration(statement) || !statement.exportClause || !compiler2.isNamedExports(statement.exportClause)) {
+    return;
+  }
+  for (const specifier of statement.exportClause.elements) {
+    if (specifier.propertyName && !found.has(specifier.name.text)) {
+      found.set(specifier.name.text, specifier.propertyName);
+    }
+  }
+}
+function unwrap(compiler2, expression) {
+  if (!expression) {
+    return void 0;
+  }
+  if (compiler2.isParenthesizedExpression(expression) || compiler2.isAsExpression(expression) || compiler2.isSatisfiesExpression(expression) || compiler2.isNonNullExpression(expression) || compiler2.isTypeAssertionExpression(expression)) {
+    return unwrap(compiler2, expression.expression);
+  }
+  return expression;
+}
+function routesLiteral(compiler2, expression, declarations, seen) {
+  const node = unwrap(compiler2, expression);
+  if (!node) {
+    return void 0;
+  }
+  if (compiler2.isIdentifier(node)) {
+    if (seen.has(node.text)) {
+      return void 0;
+    }
+    seen.add(node.text);
+    return routesLiteral(compiler2, declarations.get(node.text), declarations, seen);
+  }
+  if (!compiler2.isCallExpression(node)) {
+    return void 0;
+  }
+  const callee = unwrap(compiler2, node.expression);
+  if (callee && compiler2.isIdentifier(callee) && callee.text === "defineRouter") {
+    const routes = unwrap(compiler2, node.arguments[0]);
+    return routes && compiler2.isObjectLiteralExpression(routes) ? routes : void 0;
+  }
+  return callee && compiler2.isPropertyAccessExpression(callee) ? routesLiteral(compiler2, callee.expression, declarations, seen) : void 0;
+}
+function assertLiteral(compiler2, file, literal, declarations, seen, scan) {
+  for (const property of literal.properties) {
+    if (compiler2.isSpreadAssignment(property)) {
+      assertUnconditionalSpread(compiler2, file, property.expression, scan);
+      continue;
+    }
+    const nested = routesLiteral(compiler2, mountedRouter(compiler2, property), declarations, seen);
+    if (nested) {
+      assertLiteral(compiler2, file, nested, declarations, seen, scan);
+    }
+  }
+}
+function mountedRouter(compiler2, property) {
+  if (compiler2.isPropertyAssignment(property)) {
+    return property.initializer;
+  }
+  return compiler2.isShorthandPropertyAssignment(property) ? property.name : void 0;
+}
+function assertUnconditionalSpread(compiler2, file, expression, scan) {
+  const condition = conditionKind(compiler2, expression);
+  if (!condition) {
+    return;
+  }
+  throw new ConditionalRegistrationError(
+    `${scan.routerPath} registers routes conditionally: "...${spreadText(file, expression)}" (${condition}).
+
+The ${scan.subject} is generated from the router as it loads, so a route set that depends on a flag or an environment describes whichever way the generator happened to run: a route production registers is left out, and the client that addresses it by name gets a 404.
+Register the route unconditionally and gate its behaviour inside the handler instead.`
+  );
+}
+function conditionKind(compiler2, expression) {
+  const node = unwrap(compiler2, expression);
+  if (!node) {
+    return void 0;
   }
-  return routes;
+  if (compiler2.isConditionalExpression(node)) {
+    return "a ternary";
+  }
+  if (!compiler2.isBinaryExpression(node)) {
+    return void 0;
+  }
+  switch (node.operatorToken.kind) {
+    case compiler2.SyntaxKind.AmpersandAmpersandToken:
+      return "&&";
+    case compiler2.SyntaxKind.BarBarToken:
+      return "||";
+    case compiler2.SyntaxKind.QuestionQuestionToken:
+      return "??";
+    default:
+      return void 0;
+  }
+}
+function spreadText(file, expression) {
+  return expression.getText(file).replace(/\s+/g, " ");
+}
+var loadLogger = logger.child("@spfn/core:codegen");
+function pinNodeEnv() {
+  if (process.env.NODE_ENV) {
+    return;
+  }
+  process.env.NODE_ENV = "production";
+  loadLogger.info('NODE_ENV was unset; pinned to "production" so generated output does not depend on the shell');
+}
+function parseHost(compiler2) {
+  return {
+    useCaseSensitiveFileNames: compiler2.sys.useCaseSensitiveFileNames,
+    readDirectory: () => [],
+    fileExists: compiler2.sys.fileExists,
+    readFile: compiler2.sys.readFile
+  };
+}
+var NO_INPUTS = 18003;
+function targetPath(target, base) {
+  return resolve(base, target.endsWith("/*") ? target.slice(0, -2) : target);
+}
+var UNREADABLE_CODES = /* @__PURE__ */ new Set(["EACCES", "EPERM"]);
+function isUnreadable(error) {
+  return UNREADABLE_CODES.has(error?.code ?? "");
 }
-function parseRouterFile(routerPath) {
-  const importPaths = [];
-  const routeNames = [];
+function targetResolves(target, base) {
+  const path = targetPath(target, base);
+  if (!target.endsWith("/*")) {
+    return existsSync(path);
+  }
   try {
-    const content = readFileSync(routerPath, "utf-8");
-    const importPattern = /import\s+\{[^}]+\}\s+from\s+['"`](\.[^'"`]+)['"`]/g;
-    let match;
-    while ((match = importPattern.exec(content)) !== null) {
-      const importPath = match[1];
-      if (importPath.startsWith(".")) {
-        importPaths.push(importPath);
-      }
+    const stats = statSync(path, { throwIfNoEntry: false });
+    return stats?.isDirectory() === true && readdirSync(path).length > 0;
+  } catch (error) {
+    if (!isUnreadable(error)) {
+      throw error;
     }
-    const defineRouterStart = content.indexOf("defineRouter(");
-    if (defineRouterStart !== -1) {
-      const braceStart = content.indexOf("{", defineRouterStart);
-      if (braceStart !== -1) {
-        let depth = 1;
-        let braceEnd = braceStart + 1;
-        while (depth > 0 && braceEnd < content.length) {
-          if (content[braceEnd] === "{") depth++;
-          else if (content[braceEnd] === "}") depth--;
-          braceEnd++;
-        }
-        const routerContent = content.slice(braceStart + 1, braceEnd - 1);
-        const withoutComments = routerContent.replace(/\/\/[^\n]*/g, "");
-        const namePattern = /^\s*(\w+)\s*[,\n]/gm;
-        while ((match = namePattern.exec(withoutComments)) !== null) {
-          routeNames.push(match[1]);
-        }
-      }
+    return false;
+  }
+}
+function chooseTarget(pattern, targets, base) {
+  const present = targets.filter((target2) => targetResolves(target2, base));
+  const [target] = present.length > 0 ? present : targets;
+  if (!target) {
+    return void 0;
+  }
+  if (present.length > 1) {
+    loadLogger.warn(
+      `tsconfig "paths" maps ${pattern} to ${present.length} targets that could each resolve a module; while the router loads, only the first (${target}) does`
+    );
+  }
+  if (present.length === 0 && targets.length > 1) {
+    loadLogger.warn(
+      `tsconfig "paths" maps ${pattern} to ${targets.length} targets and none of them exists with anything in it; ${target} is used, and an import through it will name itself as unresolved`
+    );
+  }
+  return { target, others: targets.filter((candidate) => candidate !== target) };
+}
+function toAlias(pattern, targets, base) {
+  const choice = chooseTarget(pattern, targets, base);
+  if (!choice) {
+    return void 0;
+  }
+  const { target, others } = choice;
+  if (!pattern.includes("*")) {
+    return { from: pattern, to: resolve(base, target), pattern, target, others };
+  }
+  if (!pattern.endsWith("/*") || !target.endsWith("/*")) {
+    loadLogger.warn(
+      `tsconfig "paths" maps ${pattern} to ${target}, which is not a directory prefix mapping; it will not resolve while the router loads`
+    );
+    return void 0;
+  }
+  return { from: pattern.slice(0, -1), to: resolve(base, target.slice(0, -2)), pattern, target, others };
+}
+function readCompilerOptions(configPath, cwd) {
+  if (!existsSync(configPath)) {
+    return void 0;
+  }
+  const compiler2 = typescript();
+  const { config, error } = compiler2.readConfigFile(configPath, compiler2.sys.readFile);
+  if (error || !config) {
+    loadLogger.warn(`Could not read ${relative(cwd, configPath)}; its path aliases will not resolve`);
+    return void 0;
+  }
+  const parsed = compiler2.parseJsonConfigFileContent(config, parseHost(compiler2), dirname(configPath));
+  for (const diagnostic of parsed.errors) {
+    if (diagnostic.code !== NO_INPUTS) {
+      loadLogger.warn(
+        `${relative(cwd, configPath)}: ${compiler2.flattenDiagnosticMessageText(diagnostic.messageText, " ")} \u2014 path aliases it should have declared may be missing while the router loads`
+      );
     }
+  }
+  return parsed.options;
+}
+function isWithin(root, directory) {
+  const step = relative(root, directory);
+  return step === "" || !step.startsWith("..") && !isAbsolute(step);
+}
+function searchDirectories(cwd, startDir) {
+  const root = resolve(cwd);
+  const directories = [];
+  for (let directory = resolve(startDir); isWithin(root, directory); directory = dirname(directory)) {
+    directories.push(directory);
+    if (directory === root) {
+      return directories;
+    }
+  }
+  return [root];
+}
+function aliasesOf(paths, base) {
+  const aliases = /* @__PURE__ */ new Map();
+  for (const [pattern, targets] of Object.entries(paths)) {
+    const alias = toAlias(pattern, targets, base);
+    if (alias && !aliases.has(alias.from)) {
+      aliases.set(alias.from, alias);
+    }
+  }
+  return [...aliases.values()];
+}
+function projectAliases(cwd, startDir) {
+  for (const directory of searchDirectories(cwd, startDir)) {
+    const options = readCompilerOptions(join(directory, "tsconfig.json"), cwd);
+    if (options?.paths) {
+      const declaredIn = options.pathsBasePath;
+      return aliasesOf(options.paths, options.baseUrl ?? declaredIn ?? directory);
+    }
+  }
+  return [];
+}
+function describeFailure(error, subject, aliases) {
+  const message = error instanceof Error ? error.message : String(error);
+  const unresolved = /Cannot find module '([^']+)'/.exec(message);
+  if (!unresolved) {
+    return `${message}
+
+The ${subject} is read from the loaded router, so a route module must be importable without side effects. Check that nothing at module scope opens a connection or reads a missing environment value.`;
+  }
+  return `${message.split("\n")[0]}
+
+"${unresolved[1]}" did not resolve while the router was being imported. Imports resolve through Node and through the "paths" of the nearest tsconfig.json that declares them, searching from the router file up to the project root. Check that the specifier is mapped in one of those, and that what it points at exists: a workspace package resolves to a dist/ that has to have been built.` + describePassedOverTargets(unresolved[1], aliases);
+}
+function describePassedOverTargets(specifier, aliases) {
+  const alias = aliases.find((entry) => specifier.startsWith(entry.from) || specifier.startsWith(entry.to));
+  if (!alias || alias.others.length === 0) {
+    return "";
+  }
+  return `
+
+It was resolved through "${alias.target}", the first target of the "paths" entry "${alias.pattern}" that names a directory holding anything. That entry also lists ${alias.others.map((other) => `"${other}"`).join(", ")}, which the router load never tried: one alias per key is all the loader can express, so the whole load goes through a single target.`;
+}
+function loadRouterModule(load) {
+  const { cwd, absoluteRouterPath, subject, fail } = load;
+  const aliases = projectAliases(cwd, dirname(absoluteRouterPath));
+  const jiti = createJiti(cwd, {
+    interopDefault: true,
+    moduleCache: false,
+    alias: Object.fromEntries(aliases.map((alias) => [alias.from, alias.to]))
+  });
+  try {
+    return jiti(absoluteRouterPath);
   } catch (error) {
-    genLogger.warn(`Failed to parse router file: ${routerPath}`, error);
+    throw fail(
+      `Failed to load ${relative(cwd, absoluteRouterPath)}: ${describeFailure(error, subject, aliases)}`
+    );
+  }
+}
+function isRouter(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function resolveRouterExport(module, candidates) {
+  for (const exportName of candidates) {
+    const candidate = module[exportName];
+    if (isRouter(candidate)) {
+      return { router: candidate, exportName };
+    }
+  }
+  return void 0;
+}
+
+// src/codegen/generators/route-map.ts
+var genLogger = logger.child("@spfn/core:route-map-generator");
+var RouteMapGeneratorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RouteMapGeneratorError";
+  }
+};
+function isRouteDef(value) {
+  return value !== null && typeof value === "object" && "handler" in value;
+}
+var ROUTER_EXPORTS = ["appRouter", "default", "router"];
+function loadRouter(cwd, absoluteRouterPath) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath,
+    subject: "route map",
+    fail: (message) => new RouteMapGeneratorError(message)
+  });
+  const resolved = resolveRouterExport(module, ROUTER_EXPORTS);
+  if (resolved) {
+    return resolved;
+  }
+  throw new RouteMapGeneratorError(
+    `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${ROUTER_EXPORTS.join(", ")}. Export the defineRouter() result under one of those names.`
+  );
+}
+var HTTP_METHODS = { GET: true, POST: true, PUT: true, PATCH: true, DELETE: true };
+function addRoute(name, routeDef, trail, found) {
+  const where = trail.join(".");
+  if (!routeDef.method || !routeDef.path) {
+    genLogger.warn(
+      `Route "${where}" has no method or path and is left out of the map. The RPC client resolves a name to a method and a path, so both are required. A route reaches this state by being registered before .handler() was called \u2014 the server skips it too.`
+    );
+    return;
+  }
+  if (!Object.hasOwn(HTTP_METHODS, routeDef.method)) {
+    throw new RouteMapGeneratorError(
+      `Route "${where}" declares the method "${routeDef.method}", which is not an HttpMethod (${Object.keys(HTTP_METHODS).join(", ")}). The generated map is typed HttpMethod, so naming it would write a file that does not compile.`
+    );
+  }
+  const existing = found.get(name);
+  if (existing) {
+    throw new RouteMapGeneratorError(
+      `Two routes are both named "${name}" (${existing.trail} and ${where}). The RPC client addresses a route by its name alone, and a nested route registers under its own key, so a name must be unique across the whole router.`
+    );
+  }
+  found.set(name, { method: routeDef.method, path: routeDef.path, trail: where });
+}
+function collectPackageNames(router, trail, names) {
+  if (router._publishesRouteMap === false) {
+    return;
+  }
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      collectPackageNames(entry, [...trail, name], names);
+    } else if (isRouteDef(entry) && !names.has(name)) {
+      names.set(name, [...trail, name].join("."));
+    }
+  }
+  for (const [index, packageRouter] of (router._packageRouters ?? []).entries()) {
+    collectPackageNames(packageRouter, [...trail, `packages[${index}]`], names);
+  }
+}
+function collectRoutes(router, trail, found, packageNames) {
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      collectRoutes(entry, [...trail, name], found, packageNames);
+      continue;
+    }
+    if (!isRouteDef(entry)) {
+      genLogger.warn(
+        `Router entry "${[...trail, name].join(".")}" is neither a route nor a router (got ${typeof entry}) and is left out of the map. \`registerRoutes\` skips it too, so no name the client can call goes unanswered.`
+      );
+      continue;
+    }
+    addRoute(name, entry, [...trail, name], found);
+  }
+  for (const [index, packageRouter] of (router._packageRouters ?? []).entries()) {
+    collectPackageNames(packageRouter, [...trail, `packages[${index}]`], packageNames);
+  }
+}
+function assertNoPackageCollision(found, packageNames) {
+  for (const [name, where] of packageNames) {
+    const route = found.get(name);
+    if (!route) {
+      continue;
+    }
+    throw new RouteMapGeneratorError(
+      `The app route "${name}" (${route.trail}) is also registered by a package router (${where}). The app merges the two maps as { ...routeMap, ...packageRouteMap }, so the package entry wins the name at runtime while the generated types still describe the app's route \u2014 every call would go to the package's path. Rename the app route.`
+    );
   }
-  return { importPaths, routeNames };
 }
-function generateRouteMapContent(routes) {
+function collectRouteMap(router) {
+  const found = /* @__PURE__ */ new Map();
+  const packageNames = /* @__PURE__ */ new Map();
+  collectRoutes(router, ["router"], found, packageNames);
+  assertNoPackageCollision(found, packageNames);
+  return found;
+}
+function toObjectKey(name) {
+  if (name === "__proto__") {
+    return `[${JSON.stringify(name)}]`;
+  }
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+var SINGLE_QUOTABLE = /^[\x20-\x26\x28-\x5B\x5D-\x7E]*$/;
+function toStringLiteral(value) {
+  if (SINGLE_QUOTABLE.test(value)) {
+    return `'${value}'`;
+  }
+  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function generateRouteMapContent(routes, nodeEnv) {
   const lines = [
     "/**",
     " * Route Map (Auto-generated)",
     " *",
     " * DO NOT EDIT - This file is generated by @spfn/core:route-map generator",
+    " *",
+    ` * Generated with NODE_ENV=${nodeEnv}. A route registered only under one environment is`,
+    " * named here only when the generator ran under it, so this line changing is that",
+    " * difference rather than an edit.",
     " */",
     "",
     "import type { HttpMethod } from '@spfn/core/route';",
@@ -410,8 +795,8 @@ function generateRouteMapContent(routes) {
     "",
     "export const routeMap: Record<string, RouteInfo> = {"
   ];
-  for (const route of routes) {
-    lines.push(`    ${route.name}: { method: '${route.method}', path: '${route.path}' },`);
+  for (const [name, route] of routes) {
+    lines.push(`    ${toObjectKey(name)}: { method: '${route.method}', path: ${toStringLiteral(route.path)} },`);
   }
   lines.push("};");
   lines.push("");
@@ -440,9 +825,11 @@ Usage:
   }
   return {
     name: "@spfn/core:route-map",
+    // Unchanged, including the deprecated dirs: what the map is *built* from
+    // moved to the loaded router, but what a rebuild should be *triggered* by
+    // is still every file a route can live in.
     watchPatterns: [
       routerPath,
-      // Watch route directories derived from router imports
       "src/server/routes/**/*.ts",
       ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
     ],
@@ -456,97 +843,30 @@ Usage:
         return;
       }
       if (debug) {
-        genLogger.info("Parsing router file", { path: absoluteRouterPath });
-      }
-      const { importPaths, routeNames } = parseRouterFile(absoluteRouterPath);
-      if (debug) {
-        genLogger.info("Found route imports", { count: importPaths.length, names: routeNames });
-      }
-      const routerDir = dirname(absoluteRouterPath);
-      const allRoutes = [];
-      for (const importPath of importPaths) {
-        let resolvedPath = resolve(routerDir, importPath);
-        if (!resolvedPath.endsWith(".ts")) {
-          const withTs = resolvedPath + ".ts";
-          if (existsSync(withTs)) {
-            resolvedPath = withTs;
-          } else {
-            const indexPath = join(resolvedPath, "index.ts");
-            if (existsSync(indexPath)) {
-              resolvedPath = indexPath;
-            } else {
-              resolvedPath = withTs;
-            }
-          }
-        }
-        if (existsSync(resolvedPath)) {
-          const routes = parseRouteFile(resolvedPath);
-          allRoutes.push(...routes);
-          if (debug) {
-            genLogger.info(`Parsed ${routes.length} routes from ${relative(cwd, resolvedPath)}`);
-          }
-        }
+        genLogger.info("Loading router", { path: absoluteRouterPath });
       }
-      const exportedRoutes = allRoutes.filter((r) => routeNames.includes(r.name));
+      pinNodeEnv();
+      const { router, exportName } = loadRouter(cwd, absoluteRouterPath);
+      assertUnconditionalRegistration({
+        routerPath,
+        source: readFileSync(absoluteRouterPath, "utf-8"),
+        exportName,
+        subject: "route map"
+      });
+      const routes = collectRouteMap(router);
       if (debug) {
-        genLogger.info(`Found ${exportedRoutes.length} exported routes`);
+        genLogger.info(`Found ${routes.size} routes`, { names: [...routes.keys()] });
       }
-      const content = generateRouteMapContent(exportedRoutes);
       const outputDir = dirname(absoluteOutputPath);
       if (!existsSync(outputDir)) {
         mkdirSync(outputDir, { recursive: true });
       }
-      writeFileSync(absoluteOutputPath, content, "utf-8");
-      genLogger.info(`Generated route map: ${relative(cwd, absoluteOutputPath)} (${exportedRoutes.length} routes)`);
+      const nodeEnv = process.env.NODE_ENV ?? "unset";
+      writeFileSync(absoluteOutputPath, generateRouteMapContent(routes, nodeEnv), "utf-8");
+      genLogger.info(`Generated route map: ${relative(cwd, absoluteOutputPath)} (${routes.size} routes)`);
     }
   };
 }
-
-// src/codegen/generators/contract-guard.ts
-var ConditionalRegistrationError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConditionalRegistrationError";
-  }
-};
-function defineRouterBlock(source) {
-  const start = source.indexOf("defineRouter(");
-  if (start === -1) {
-    return void 0;
-  }
-  const open = source.indexOf("{", start);
-  if (open === -1) {
-    return void 0;
-  }
-  let depth = 1;
-  let cursor = open + 1;
-  while (depth > 0 && cursor < source.length) {
-    if (source[cursor] === "{") depth++;
-    else if (source[cursor] === "}") depth--;
-    cursor++;
-  }
-  return source.slice(open + 1, cursor - 1).replace(/\/\/[^\n]*/g, "");
-}
-var PLAIN_REFERENCE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*\s*$/;
-function assertUnconditionalRegistration(routerPath, source) {
-  const block = defineRouterBlock(source);
-  if (!block) {
-    return;
-  }
-  for (const [, expression] of block.matchAll(/\.\.\.\s*([^,\n]+)/g)) {
-    if (PLAIN_REFERENCE.test(expression)) {
-      continue;
-    }
-    throw new ConditionalRegistrationError(
-      `${routerPath} registers routes conditionally: "...${expression.trim()}".
-
-A contract has to describe what production serves. When the route set depends on a flag or an environment, the generated contract describes whichever way the generator happened to run.
-Register contracted routes unconditionally, and gate behaviour inside the handler instead.`
-    );
-  }
-}
-
-// src/codegen/generators/contract.ts
 var genLogger2 = logger.child("@spfn/core:contract-generator");
 var ContractGeneratorError = class extends Error {
   constructor(message) {
@@ -554,39 +874,22 @@ var ContractGeneratorError = class extends Error {
     this.name = "ContractGeneratorError";
   }
 };
-function isRouter(value) {
-  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
-}
-function loadRouter(cwd, absoluteRouterPath, routerExport) {
-  let module;
-  try {
-    const jiti = createJiti(cwd, { interopDefault: true, moduleCache: false });
-    module = jiti(absoluteRouterPath);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new ContractGeneratorError(
-      `Failed to load ${relative(cwd, absoluteRouterPath)}: ${message}
-
-The contract is read from the loaded router, so a route module must be importable without side effects. Check that nothing at module scope opens a connection or reads a missing environment value.`
-    );
-  }
+function loadRouter2(cwd, absoluteRouterPath, routerExport) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath,
+    subject: "contract",
+    fail: (message) => new ContractGeneratorError(message)
+  });
   const candidates = routerExport ? [routerExport] : ["appRouter", "default", "router"];
-  for (const name of candidates) {
-    const candidate = module[name];
-    if (isRouter(candidate)) {
-      return candidate;
-    }
+  const resolved = resolveRouterExport(module, candidates);
+  if (resolved) {
+    return resolved;
   }
   throw new ContractGeneratorError(
     `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${candidates.join(", ")}. Set "routerExport" to the export holding the defineRouter() result.`
   );
 }
-function pinNodeEnv() {
-  if (!process.env.NODE_ENV) {
-    process.env.NODE_ENV = "production";
-    genLogger2.info('NODE_ENV was unset; pinned to "production" so the contract does not depend on the shell');
-  }
-}
 function createContractGenerator(config) {
   const {
     routerPath,
@@ -623,8 +926,13 @@ Usage:
         );
       }
       pinNodeEnv();
-      assertUnconditionalRegistration(routerPath, readFileSync(absoluteRouterPath, "utf-8"));
-      const router = loadRouter(cwd, absoluteRouterPath, routerExport);
+      const { router, exportName } = loadRouter2(cwd, absoluteRouterPath, routerExport);
+      assertUnconditionalRegistration({
+        routerPath,
+        source: readFileSync(absoluteRouterPath, "utf-8"),
+        exportName,
+        subject: "contract"
+      });
       const document = collectContractDocument(router);
       const changed = writeCurrentDocument(contractsDir, document);
       genLogger2.info(
@@ -660,6 +968,6 @@ var generators = {
   contract: createContractGenerator
 };
 
-export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, RouteMapGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map