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

package/dist/codegen/index.d.ts

@@ -293,6 +293,15 @@ interface GenerationStats {
  * Generates a route map file containing routeName → {method, path} mappings.
  * This allows RPC proxy to resolve routes without importing the full router.
  *
+ * The router is loaded and walked, not parsed from source. A source parser sees
+ * the spelling rather than the router: `defineRouter({ createUser })` written on
+ * one line, an aliased key `create: createUser`, and a nested router assembled by
+ * a second `defineRouter(` in the same file are all ordinary ways to write a
+ * router, and all of them used to leave routes out of the map. The RPC client
+ * addresses a route by name, so a dropped name is a route that typechecks and
+ * 404s. Walking the loaded router registers exactly what `registerRoutes`
+ * registers, whatever the source looks like.
+ *
  * @example
  * ```typescript
  * // .spfnrc.ts
@@ -326,10 +335,19 @@ interface RouteMapGeneratorConfig {
      */
     outputPath?: string;
     /**
-     * Additional route directories to scan (for package routers)
+     * Extra file patterns to watch, for routes outside src/server/routes
+     *
+     * @deprecated Ignored. The map is read from the loaded router, which reaches
+     * every route through its own imports wherever they live, so there is no
+     * longer a set of directories to scan. Still accepted so an existing
+     * `.spfnrc.ts` keeps working; the watch patterns it produced are unchanged.
      */
     additionalRouteDirs?: string[];
 }
+/** Thrown when the router cannot produce a route map at all. */
+declare class RouteMapGeneratorError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Contract Generator
@@ -392,27 +410,58 @@ declare class ContractGeneratorError extends Error {
 /**
  * Router registration guard
  *
- * A contract has to describe what production serves. When a route is registered
- * only under a feature flag or an environment check, the generated contract
- * describes whichever way the generator happened to run — and the gate then
- * compares a promise nobody made.
+ * A route registered only behind a feature flag or an environment check makes
+ * generated output depend on how the generator happened to run. The contract
+ * then describes a promise nobody made, and the route map leaves out a name
+ * `registerRoutes` registers in production — so `api.admin.call()` typechecks
+ * and 404s wherever the flag differs.
  *
- * Object spread is the one way a key can be conditionally present in the object
- * `defineRouter()` receives, so that is what this reads. A spread of a plain
- * identifier (`...baseRoutes`) is unconditional and passes; anything computed
- * inside the spread does not.
+ * What it reads is the router the generator was pointed at: the export the
+ * loader found the router under, and the routers that export mounts by name
+ * from the same file, since a nested router's routes land in the same flat map.
+ * A `defineRouter(` the file writes but the app router never reaches — a second
+ * router a test harness mounts, say — registers nothing in production and is
+ * not scanned.
+ *
+ * Reading is done with TypeScript's parser rather than a regular expression
+ * over the text. A spread is a syntax node there, so a JSDoc that spells
+ * `defineRouter({ ... })` in prose, a brace inside a route path, and a comment
+ * holding an old router are not router source. Only a spread whose expression
+ * reads a condition is refused — a ternary, `&&`, `||`, `??`. A call is
+ * allowed: `...metadataRoutes(config, resource)` is how `@spfn/mcp` composes
+ * its router, and loading yields exactly the routes it returns.
+ *
+ * Past it, by construction: a conditional spread inside an imported route
+ * module, a router built by a factory, a condition hoisted to a variable
+ * (`const extra = flag ? { admin } : {}` spread afterwards), and a
+ * `.packages()` list assembled conditionally. `NODE_ENV` is pinned before the
+ * router loads, which covers those only when the shell left it unset: the
+ * generator then reads the router production gets. `spfn build` pins
+ * `production` itself, so the deployed map is right. `spfn dev` sets
+ * `development` before it spawns the watcher, which inherits it — a
+ * `NODE_ENV === 'development'` condition hoisted to a variable therefore writes
+ * a dev-only route into the map the watcher regenerates, and `spfn build` takes
+ * it back out. The generated map's header names the `NODE_ENV` it was written
+ * under, so that difference shows up in the diff.
  */
-/** Thrown when the router registers contracted routes conditionally. */
+/** Thrown when the router registers routes conditionally. */
 declare class ConditionalRegistrationError extends Error {
     constructor(message: string);
 }
+interface RegistrationScan {
+    /** Path named in the error message. */
+    routerPath: string;
+    /** Contents of the router file. */
+    source: string;
+    /** The export the loader found the router under: `appRouter`, `default`, … */
+    exportName: string;
+    /** What is being generated, named in the message: `route map`, `contract`. */
+    subject: string;
+}
 /**
  * Refuse a router whose route set depends on a condition.
- *
- * @param routerPath - path named in the error message
- * @param source - contents of the router file
  */
-declare function assertUnconditionalRegistration(routerPath: string, source: string): void;
+declare function assertUnconditionalRegistration(scan: RegistrationScan): void;
 
 /**
  * Built-in Generators Export
@@ -447,4 +496,4 @@ declare function assertUnconditionalRegistration(routerPath: string, source: str
  */
 declare const generators: Record<string, unknown>;
 
-export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type RegistrationScan, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, RouteMapGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };