ts-procedures 8.3.0 → 8.5.0

package/docs/handoffs/shared-models-auto-resolve-response.md

@@ -0,0 +1,181 @@
+# Response: shared-models auto-resolve (re: `--shared-types-from` request)
+
+> **STATUS: SHIPPED (v8.5.0).** Three targeted improvements shipped in place of source-file scanning. See below for what landed and why the requested mechanism was declined.
+
+**To:** downstream developer
+**From:** ts-procedures codegen maintainers
+**Date:** 2026-06-06
+**Reference:** feedback on `sharedTypesImport` DX — pain points 1–3
+
+---
+
+## TL;DR
+
+The goal — "define it once, no second table, no silent drift" — was right. We shipped three targeted fixes that deliver those ergonomics from the DocEnvelope side rather than by scanning TypeScript source files, which would introduce a worse class of silent failure. The per-`$id` `sharedTypesImport` map is unchanged and remains available as a precision escape hatch.
+
+---
+
+## What shipped
+
+### 1. `sharedModelsModule` — one line replaces the entire map
+
+A single module path tells codegen: *"re-export every `$id` model from this module under its derived name."*
+
+```jsonc
+// ts-procedures-codegen.config.json
+{ "sharedModelsModule": "@app/schemas" }
+```
+
+```bash
+# CLI
+npx ts-procedures-codegen --url http://localhost:3000/doc --out ./generated --shared-models-module @app/schemas
+```
+
+```ts
+// generateClient() API
+await generateClient({ url, outDir, sharedModelsModule: '@app/schemas' })
+```
+
+Convention: the derived name is the model's `$id`/`title` (PascalCase), which is the same identifier your schema file already exports. If the names align — they usually do — the entire `sharedTypesImport` map collapses to this single value.
+
+Precedence: explicit `sharedTypesImport[$id]` entry → `sharedModelsModule` convention → generate locally. The map remains available to override individual entries (rename, different package, multi-consumer split).
+
+### 2. Summary log (CLI)
+
+Every CLI run that finds `$id`-bearing models now prints:
+
+```
+[ts-procedures-codegen] Shared models: 15 total — 15 re-exported, 0 generated locally.
+```
+
+This makes silent generated-twin drift visible without requiring any additional flags or contract tests. (Calling `generateClient` programmatically is silent by default — pass `logger: console.log` to opt in — so the summary never leaks into your own build-script output.)
+
+### 3. `--strict-shared-models` — hard-fail on local twins
+
+Fails the run and lists every `$id` that would be generated as a local structural twin instead of re-exported:
+
+```bash
+npx ts-procedures-codegen ... --strict-shared-models
+```
+
+```jsonc
+{ "strictSharedModels": true }
+```
+
+```ts
+await generateClient({ url, outDir, sharedModelsModule: '@app/schemas', strictSharedModels: true })
+```
+
+This is a **CI flag, not a development default** — run it in your pipeline and codegen becomes the drift gate. It replaces a hand-written `toEqualTypeOf` contract test.
+
+---
+
+## How this maps to your three pain points
+
+### Pain 1: Two places to keep in lockstep (`$id` and the map entry)
+
+`sharedModelsModule` derives the import from the model's own `$id`/`title` — you define the convention once and it applies to every model. There is no second table to maintain.
+
+### Pain 2: Silent fallback — a generated structural twin that typechecks but isn't the real type
+
+Two layers now make this visible:
+
+- The CLI summary log surfaces the "generated locally" count on every codegen run.
+- `--strict-shared-models` promotes that to a hard failure, listing the specific `$id`s. Add it to your CI pipeline and the generated-twin state becomes impossible to ship.
+
+This replaces your hand-written `toEqualTypeOf` contract test with a single flag — the codegen itself owns the invariant.
+
+### Pain 3: The map is redundant — `module` is "where the schema lives" and `name` is usually the `$id`
+
+`sharedModelsModule` makes that redundancy disappear. `name` is derived from the model's `$id`/`title`; `module` is supplied once for all models. The 15-entry map becomes one line.
+
+---
+
+## Why `--shared-types-from <dir|glob>` was declined
+
+The goal was right. The mechanism is what we changed.
+
+ts-procedures codegen has one explicit input contract: a **DocEnvelope** obtained via `--url`, `--file`, or a passed object. The envelope is a self-contained JSON document — it contains schemas, routes, and error shapes. Codegen never reads the consumer's TypeScript source tree. That decoupling is what makes codegen work against a live remote server, a serialized offline file, or a published package with no local source.
+
+Source-file scanning would break that contract in four concrete ways:
+
+**(a) Silent desync in `--url` / offline `--file` cases.** The live server's envelope and the local source tree can disagree at any point in time — a schema field renamed in the server but not yet deployed, an `$id` changed in source but not rebuilt. Source scanning would produce a "shared" reference that names a type the server actually never returns. The result typechecks and the single-source-of-truth claim is restored, but the types are silently WRONG — a worse outcome than today's duplicate-but-correct structural twin.
+
+**(b) Fails for published-package consumers.** If `@app/schemas` lives in `node_modules`, there is no TypeScript source tree to scan — only compiled `.d.ts` files (if any) or nothing. The scan would silently skip models that are genuinely shared from a published package and generate local twins for them anyway, with no signal.
+
+**(c) Requires a TS parser, glob runner, and export-resolution heuristics in codegen.** This is a substantial dependency and surface area. It introduces failure modes (barrel re-exports, `export * from`, conditional exports, `.d.ts` vs. `.ts`) whose edge cases are hard to exhaustively enumerate and maintain. The DocEnvelope contract specifically exists to avoid this category of tooling dependency.
+
+**(d) Does not solve module-path correctness.** A file path discovered by glob scanning (`src/schemas/message.ts`) is not a valid TypeScript import specifier for a consumer who imports `@app/schemas`. Path-to-module-alias resolution requires TypeScript's full compiler configuration. Without it, any path the scan produces must be corrected by hand — which brings back a second table.
+
+The `sharedModelsModule` convention solves the same "define once, no second table" problem. The module specifier (`@app/schemas`) is typed once; names are derived from the model's own `$id`/`title`. It works in all deployment topologies: live server, offline file, published package.
+
+---
+
+## Escape hatch: `sharedTypesImport` unchanged
+
+The per-`$id` map is unchanged and remains available for cases where `sharedModelsModule` is not enough:
+
+- A model whose TypeScript name differs from its `$id` (rename case).
+- Different models imported from different packages (`@app/schemas` and `@app/internal-schemas`).
+- Multi-consumer split where a subset of models come from a shared package and others are generated locally.
+
+```jsonc
+{
+  "sharedModelsModule": "@app/schemas",
+  "sharedTypesImport": {
+    "urn:internal-msg": { "module": "@app/internal-schemas", "name": "InternalMessage" }
+  }
+}
+```
+
+`sharedTypesImport` entries take precedence over `sharedModelsModule`, so you can cover the general case with the convention and override individual outliers explicitly.
+
+---
+
+## Migration example
+
+**Before (v8.3 and earlier) — 15-entry hand-maintained map + contract test:**
+
+```jsonc
+// ts-procedures-codegen.config.json
+{
+  "shareModels": true,
+  "sharedTypesImport": {
+    "urn:message":      { "module": "@app/schemas", "name": "Message" },
+    "urn:user":         { "module": "@app/schemas", "name": "User" },
+    "urn:thread":       { "module": "@app/schemas", "name": "Thread" },
+    "urn:attachment":   { "module": "@app/schemas", "name": "Attachment" },
+    "urn:reaction":     { "module": "@app/schemas", "name": "Reaction" },
+    "urn:channel":      { "module": "@app/schemas", "name": "Channel" },
+    "urn:workspace":    { "module": "@app/schemas", "name": "Workspace" },
+    "urn:notification": { "module": "@app/schemas", "name": "Notification" },
+    "urn:role":         { "module": "@app/schemas", "name": "Role" },
+    "urn:permission":   { "module": "@app/schemas", "name": "Permission" },
+    "urn:bot":          { "module": "@app/schemas", "name": "Bot" },
+    "urn:webhook":      { "module": "@app/schemas", "name": "Webhook" },
+    "urn:app":          { "module": "@app/schemas", "name": "App" },
+    "urn:token":        { "module": "@app/schemas", "name": "Token" },
+    "urn:audit-log":    { "module": "@app/schemas", "name": "AuditLog" }
+  }
+}
+```
+
+```ts
+// contract test to catch silent twins
+expect(generatedMessage).toEqualTypeOf<Message>()
+expect(generatedUser).toEqualTypeOf<User>()
+// ... × 15
+```
+
+**After (v8.5.0) — one config line + one CI flag:**
+
+```jsonc
+// ts-procedures-codegen.config.json
+{
+  "shareModels": true,
+  "sharedModelsModule": "@app/schemas",
+  "strictSharedModels": true
+}
+```
+
+No map. No contract tests. `--strict-shared-models` (or `"strictSharedModels": true`) in CI is the drift gate: codegen fails and names the offender if any `$id` model would silently generate as a local twin.