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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spfn/core",
-    "version": "0.3.0-beta.11",
+    "version": "0.3.0-beta.12",
     "description": "Full-stack TypeScript backend for Next.js: file-based typed routes, Drizzle entities and repositories, PostgreSQL transactions and a generated end-to-end client, in one fixed vertical slice per feature",
     "type": "module",
     "exports": {

package/src/codegen/README.md

@@ -127,7 +127,7 @@ call `generators['route-map'](config)`.
 
 ## Built-in: `@spfn/core:route-map`
 
-Parses your router + route files and emits a `routeName → {method, path}` map. This map is
+Loads your router and emits a `routeName → {method, path}` map. This map is
 what the **RPC proxy** (`createRpcProxy` in `@spfn/core/nextjs/server`) uses to turn
 `api.getUser.call(...)` into an HTTP request — it needs `method` and `path` without
 importing server code into the client bundle.
@@ -139,18 +139,91 @@ importing server code into the client bundle.
 | `name` | `'@spfn/core:route-map'` | yes | — | Generator identifier (literal). |
 | `routerPath` | `string` | yes | — | Router file, relative to project root. Throws at construction if missing. |
 | `outputPath` | `string` | no | `'./src/generated/route-map.ts'` | Where the map is written (parent dirs auto-created). |
-| `additionalRouteDirs` | `string[]` | no | `[]` | Extra route dirs to watch (each becomes `${dir}/**/*.ts`). |
+| `additionalRouteDirs` | `string[]` | no | `[]` | **Deprecated and ignored** for collection; still added to `watchPatterns` as `${dir}/**/*.ts`. |
+
+### What it reads
+
+The router module is loaded with jiti (`appRouter` → `default` → `router`) and walked the
+way `registerRoutes` walks it. How the router is *written* does not matter: a one-line
+`defineRouter({ createUser })`, an aliased key `create: createUser`, and a second
+`defineRouter(` in the same file all produce the same map.
+
+- A **nested router** recurses to any depth and its routes land in the map **flat, under
+  their own keys** — the parent's key names the grouping, not the route, exactly as the
+  server registers them.
+- `method` and `path` come from the `RouteDef`, not from a pattern over the source. A
+  route not registered in the router is absent, because there is nothing registering it.
+- **`.packages()` routers are left out**, at every depth. A package publishes its own
+  route map and the app merges them (`{ ...routeMap, ...authRouteMap }`). Their *names*
+  are still read, because that merge is what a collision turns on — see below.
+- A name that is not a JS identifier (`'get-user'`) is emitted quoted, and `__proto__` is
+  emitted as a computed key, so the generated file parses and the map keeps every route as
+  an own property.
+- Imports are resolved by Node **and by the `compilerOptions.paths` of the nearest
+  `tsconfig.json` that declares them**, searched from the router file's own directory up to
+  the project root, `extends` chains included — so the `@/*` alias every spfn app has
+  resolves while the router loads, whether it lives in the root config (a Next.js app) or in
+  `src/server/tsconfig.json` (what `spfn init` scaffolds, and the config `spfn build`
+  compiles the server with). The search stops at the project root: a tsconfig above it
+  belongs to whatever contains the project. A config that declares no `paths` is passed over
+  rather than ending the search. `baseUrl` is honoured, so the scaffold's `"baseUrl": "../.."`
+  resolves against the project root as tsc resolves it. The failure names the specifier that
+  did not resolve.
+- `NODE_ENV` is pinned to `production` when the shell left it unset, so the same router
+  does not load two ways depending on how codegen was invoked. A value the shell *did* set
+  is left alone.
 
-### What it parses
+### When it refuses
 
-- **Router file** (`routerPath`): relative `import { ... } from './...'` statements, and the
-  route names listed inside the **first** `defineRouter({ ... })` call (top-level
-  identifiers, comments stripped).
-- **Route files**: only the exact pattern
-  `export const <name> = route.<get|post|put|patch|delete>('<path>')…` (single/double/back
-  quotes). The leading `route.<method>('<path>')` call is what's matched.
-- Only routes whose `name` also appears in `defineRouter({...})` end up in the output
-  (declared-but-unregistered routes are dropped).
+Unlike the old source parser, which dropped what it could not read, the generator throws
+— logged always, and fatal on the `build` trigger and on `spfn codegen run`:
+
+- The module will not load. An import that did not resolve names the specifier; anything
+  else names the cause and says a route module must be importable without side effects. It
+  never falls back to parsing.
+- No router is found under `appRouter`, `default` or `router` (the message lists all three).
+- The router file registers a route **conditionally** (`...(flag ? { admin } : {})`), which
+  would put the flag's value into the map and leave `api.admin.call()` 404ing wherever the
+  flag differs. This is the same guard `@spfn/core:contract` uses, and it reads **the router
+  the generator was pointed at** — the export the loader found it under, plus the routers
+  that export mounts by name from the same file, since a nested router's routes land in the
+  same flat map. A second `defineRouter(` the app router never reaches is not scanned: it
+  registers nothing in production. The source is read with TypeScript's parser, so a JSDoc
+  spelling `defineRouter({ ... })` in prose, a comment holding an old router and a brace
+  inside a string are not router source. Only a spread whose expression **reads a
+  condition** is refused — a ternary, `&&`, `||`, `??`. A call is allowed
+  (`...metadataRoutes(config, resource)`): loading yields exactly the routes it returns.
+  Past the guard, by construction: a conditional spread inside an imported module, a router
+  built by a factory, a condition hoisted to a variable before the spread, and a
+  `.packages()` list assembled conditionally. `NODE_ENV` pinning stands in for the guard on
+  those, but only when the shell left it unset: `spfn build` pins `production`, so what ships
+  is right, while `spfn dev` sets `development` and the watcher regenerates under it. The
+  generated header names the `NODE_ENV` the map was written under, so that difference is a
+  line in the diff rather than a route that vanishes at build.
+- Two routes reach the same name (the message names both places).
+- An **app route and a package route** reach the same name, where that package publishes a
+  route map. Both register at runtime, and the app's proxy merges
+  `{ ...routeMap, ...authRouteMap }` — so the package's route wins the name while the
+  generated types still describe the app's. Two *package* routers sharing a name is not
+  refused: which one wins is the app's merge order, which this generator neither sees nor
+  writes. Nor is a collision with a router that publishes **no** map — one declared with
+  `defineUnmappedRouter`, whose routes are reached by the URL something was handed rather
+  than by name: the ops surface (`createOpsRouter`), `@spfn/monitor`, `@spfn/cms` and the
+  tracking routes of `@spfn/notification`. Nothing of theirs merges over the app's map, so
+  an app route named after one of their routes overwrites nothing and must not fail the
+  build.
+- A route's `method` is not an `HttpMethod`. `registerRoutes` lowercases the method before
+  registering, so `method: 'get'` serves fine and would emit a map that fails `tsc`.
+
+A **missing router file** is still only a warning: the generator returns and writes nothing.
+
+**Warned about and left out, not refused**: a route with no method or path (reachable by
+registering a route before `.handler()` was called), and a router entry that is neither a
+route nor a router. `registerRoutes` warns and skips both, so a map without them still names
+every route the server answers — which is all a refusal would have been protecting.
+
+What a *package* router carries is never refused — an entry the app developer cannot fix
+is skipped, exactly as `registerRoutes` skips it.
 
 ### Generated output
 
@@ -199,10 +272,10 @@ generator's own surface.
 
 | | `route-map` | `contract` |
 |---|---|---|
-| Reads the router by | parsing the source | **loading the module** and walking `RouteDef`s |
+| Reads the router by | loading the module and walking `RouteDef`s | the same |
 | Covers | every registered route | only routes carrying `.contract()` |
 | `runOn` | `watch`, `manual`, `build` | `watch`, `build`, `manual` |
-| Can fail a build | no | **yes**, on the `build` trigger only |
+| Can fail a build | **yes** — any refusal, on every trigger the CLI fails on | **yes**; a broken contract only on the `build` trigger |
 
 Loading rather than parsing is what makes the contract correct: real routes build schemas from
 imported values (`EmailSchema`, `FileSchema()`, constants) that a source parser cannot resolve. It
@@ -216,8 +289,10 @@ costs a module import and no infrastructure — `@spfn/auth`'s 43 routes load in
 - No router export is found under the configured or default names.
 - Two contracted routes share a name, or a contracted route has no method, path, `since` or
   `response`.
-- `defineRouter({...})` contains a computed spread (`...(flag ? { route } : {})`), which would make
-  the contract describe whichever way the generator happened to run.
+- The router the generator was pointed at contains a conditional spread
+  (`...(flag ? { route } : {})`), which would make the contract describe whichever way the
+  generator happened to run. Same guard as `route-map` — see its bullet for exactly what is
+  scanned and what is allowed.
 - On the `build` trigger only: the contract breaks the newest released snapshot.
 
 `spfn dev` generates but never refuses — being unable to hold a half-finished route mid-edit would
@@ -232,7 +307,7 @@ Provided by the `spfn` CLI (`@spfn/cli`), not by `@spfn/core` itself:
 ```bash
 spfn codegen init     # scaffold a .spfnrc.ts
 spfn codegen list     # list resolved generators + their watch patterns  (alias: ls)
-spfn codegen run      # run all generators once (CodegenOrchestrator.generateAll, trigger 'manual')
+spfn codegen run      # run all generators once (CodegenOrchestrator.generateAll, trigger 'manual'; a failure exits 1)
 spfn dev              # dev server + codegen in watch mode
 spfn build            # runs codegen once before building (trigger 'build'; a failure exits 1)
 
@@ -245,6 +320,11 @@ spfn contract list       # released snapshots  (alias: ls)
 (The `spfn init` project scaffold writes a `.spfnrc.ts` preconfigured with the route-map
 generator and adds a `"codegen": "spfn codegen run"` npm script.)
 
+`spfn codegen run` **exits 1 when a generator refuses**, and stops at the one that refused
+— the run that just failed to regenerate a map must not look like the run that did. `spfn
+dev` is unaffected: watch mode logs the failure and keeps going, because being unable to
+hold a half-finished route mid-edit would make the feature unusable.
+
 ---
 
 ## Programmatic usage
@@ -405,11 +485,26 @@ regeneration when it's absent (build/manual passes don't set it).
   wrong (or no) `method`/`path`. `spfn build` runs codegen first; if you build by other
   means, run `spfn codegen run` yourself. Treat the file as generated (it's marked
   `DO NOT EDIT`).
-- **route-map only matches a specific route syntax.** Routes must be
-  `export const x = route.<method>('<literal path>')`. Dynamic paths, methods other than
-  get/post/put/patch/delete, or routes not listed in `defineRouter({...})` won't appear.
 - **A route must be in `defineRouter({...})` to be emitted.** Defining `export const foo =
-  route.get(...)` but not registering `foo` in the router drops it from the map.
+  route.get(...)` but not registering `foo` in the router drops it from the map — the
+  generator walks the router, so an unregistered route does not exist as far as it is
+  concerned. How the registration is *spelled* no longer matters.
+- **route-map loads your router, so route modules must import cleanly.** Reading a
+  required environment value at module scope now fails `spfn build` and `spfn codegen run`,
+  not just `spfn dev`. Move that read inside the handler. Top-level `await` in a route or
+  router module does not load either — jiti transforms to CJS — the same limit
+  `@spfn/core:contract` has always had.
+- **A path alias resolves only if a tsconfig between the router and the project root maps
+  it.** Both loading generators read `compilerOptions.paths` from the nearest such
+  `tsconfig.json` (following `extends`) and hand it to jiti, so `@/server/routes/users`
+  resolves from the root config or from `src/server/tsconfig.json`. A mapping that lives
+  *above* the project root — a monorepo's solution-style config — is not read; a `paths`
+  entry whose `*` is not a trailing `/*` is skipped (jiti matches a prefix, not a template);
+  and a `baseUrl` with no `paths` resolves nothing (an alias map cannot say "try this
+  directory for every bare specifier"). Several targets for one pattern are supported: the
+  first that exists on disk is used, as tsc and tsup use it. Each skip is warned about, an
+  `extends` target TypeScript could not read is warned about instead of silently dropping
+  its `paths`, and an import that then fails to resolve names the specifier.
 - **Custom generators must default-export a factory.** `createGeneratorsFromConfig` calls
   `module.default()` (a zero-arg function) for `{ path }` entries. Exporting the Generator
   object directly, or a factory that needs args, won't load.
@@ -505,12 +600,12 @@ interface RouteMapGeneratorConfig
     name: '@spfn/core:route-map';
     routerPath: string;
     outputPath?: string;               // default './src/generated/route-map.ts'
-    additionalRouteDirs?: string[];
+    additionalRouteDirs?: string[];   // deprecated: watched, never collected from
 }
 ```
 
 ## Related
 
-- [@spfn/core/route](../route/README.md) — `route.*` / `defineRouter` (the source parsed)
+- [@spfn/core/route](../route/README.md) — `route.*` / `defineRouter` (the router loaded and walked)
 - [@spfn/core/nextjs](../nextjs/README.md) — RPC proxy (`createRpcProxy`) that consumes `routeMap`
 - [@spfn/core/env](../env/README.md) — environment configuration

package/src/contract/README.md

@@ -285,7 +285,13 @@ JSON body and upload the file through its own uncontracted route.
   generator refuses a `defineRouter({...})` containing a computed spread (`...(flag ? {x} : {})`);
   a spread of a plain identifier (`...baseRoutes`) is fine.
 - **`NODE_ENV` is pinned when unset.** The generator sets it to `production` before loading, so a
-  schema that reads the environment cannot make the contract depend on the shell it ran in.
+  schema that reads the environment cannot make the contract depend on the shell it ran in. The pin
+  is process-wide and shared with `@spfn/core:route-map`, so both generators in one run read the
+  same environment whichever `.spfnrc.ts` lists first.
+- **Path aliases come from the project root's `tsconfig.json`.** `compilerOptions.paths` is read
+  (`extends` followed) and handed to jiti, so a router importing `@/server/routes/users` loads. A
+  mapping held in any other tsconfig is not read, and the failure names the specifier that did not
+  resolve.
 - **A failed build still rewrites `current.json`.** That is deliberate — the regenerated file is
   what the gate compared, so `git diff` shows exactly what broke.
 - **Constraint changes count as type changes.** Narrowing `maxLength`, an `enum` or a `format` is

package/src/route/README.md

@@ -458,6 +458,20 @@ export const appRouter = defineRouter({ getRoot, getStatus })
 
 `.packages()` also flattens any nested package routers the given routers themselves declared.
 
+**A name a package route already uses is not available to an app route.** Both register, at
+their own paths, and the app's proxy merges the two maps as `{ ...routeMap, ...authRouteMap }`
+— so the package entry wins the name while the generated types still describe the app's
+route. `spfn codegen run` refuses rather than generating that, naming both sides.
+
+A package that publishes **no** route map is the exception, and declares itself one with
+`defineUnmappedRouter`: its routes are reached by the URL something was handed rather than by
+name, so nothing merges over the app's map and an app route may share a name with one of them
+freely. `createOpsRouter` builds the ops surface that way — `spfn ops` invokes a command over
+its URL — as do `@spfn/monitor`, `@spfn/cms` and the tracking routes of `@spfn/notification`.
+`defineRouter` is the default because the obligation runs the other way: a package that does
+publish a map must not declare itself unmapped, or a collision that really would overwrite an
+app route generates silently.
+
 ### `.use([...])` — router-level global middleware
 
 Named middleware applied to **every** route in the router (and package routers), unless a