ts-procedures 8.4.0 → 8.5.0

package/src/codegen/bin/cli.test.ts

@@ -555,3 +555,30 @@ describe('--share-models', () => {
     expect(parseArgs(['--out', 'g', '--url', 'u'], cfg as CodegenConfig).sharedTypesImport).toEqual(cfg.sharedTypesImport)
   })
 })
+
+describe('--shared-models-module and --strict-shared-models', () => {
+  it('parses --shared-models-module into sharedModelsModule', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@app/schemas'])
+    expect(parsed.sharedModelsModule).toBe('@app/schemas')
+  })
+
+  it('parses --strict-shared-models as a boolean (default false)', () => {
+    expect(parseArgs(['--out', 'gen', '--file', 'e.json']).strictSharedModels).toBe(false)
+    expect(
+      parseArgs(['--out', 'gen', '--file', 'e.json', '--strict-shared-models']).strictSharedModels,
+    ).toBe(true)
+  })
+
+  it('CLI --shared-models-module overrides a config value', () => {
+    const parsed = parseArgs(
+      ['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@cli/pkg'],
+      { sharedModelsModule: '@config/pkg' },
+    )
+    expect(parsed.sharedModelsModule).toBe('@cli/pkg')
+  })
+
+  it('strictSharedModels is seeded from config when the flag is absent', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json'], { strictSharedModels: true })
+    expect(parsed.strictSharedModels).toBe(true)
+  })
+})

package/src/codegen/bin/cli.ts

@@ -30,6 +30,8 @@ export interface CodegenConfig {
   unsupportedUnions?: 'throw' | 'fallback'
   shareModels?: boolean
   sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
 }
 
 export interface ParsedArgs {
@@ -51,6 +53,8 @@ export interface ParsedArgs {
   unsupportedUnions?: 'throw' | 'fallback'
   shareModels: boolean
   sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -170,6 +174,8 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
   let shareModels = config?.shareModels ?? true
   const sharedTypesImport = config?.sharedTypesImport
+  let sharedModelsModule: string | undefined = config?.sharedModelsModule
+  let strictSharedModels = config?.strictSharedModels ?? false
   let configPath: string | undefined
 
   for (let i = 0; i < argv.length; i++) {
@@ -260,6 +266,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       shareModels = true
     } else if (arg === '--no-share-models') {
       shareModels = false
+    } else if (arg === '--shared-models-module') {
+      sharedModelsModule = argv[++i]
+    } else if (arg === '--strict-shared-models') {
+      strictSharedModels = true
     } else if (arg === '--config') {
       configPath = argv[++i]
     } else if (arg !== undefined && arg.startsWith('--')) {
@@ -336,6 +346,8 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
     shareModels,
     ...(sharedTypesImport !== undefined ? { sharedTypesImport } : {}),
+    ...(sharedModelsModule !== undefined ? { sharedModelsModule } : {}),
+    strictSharedModels,
   }
 }
 
@@ -425,6 +437,9 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
         ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
         shareModels: parsed.shareModels,
         ...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),
+        ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+        strictSharedModels: parsed.strictSharedModels,
+        logger: (message: string) => { console.log(message) },
         ...kotlinWiring,
         ...swiftWiring,
       })
@@ -555,6 +570,9 @@ async function main(): Promise<void> {
       ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
       shareModels: parsed.shareModels,
       ...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),
+      ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+      strictSharedModels: parsed.strictSharedModels,
+      logger: (message: string) => { console.log(message) },
       ...kotlinWiring,
       ...swiftWiring,
     })

package/src/codegen/bin/flag-specs.test.ts

@@ -24,4 +24,15 @@ describe('flag-specs', () => {
     expect(KNOWN_FLAGS).not.toContain('--help')
     expect(KNOWN_FLAGS).not.toContain('-h')
   })
+
+  it('catalogs the shared-models convention + strict flags', () => {
+    expect(KNOWN_FLAGS).toContain('--shared-models-module')
+    expect(KNOWN_FLAGS).toContain('--strict-shared-models')
+  })
+
+  it('documents the new flags in --help output', () => {
+    const help = formatHelp()
+    expect(help).toContain('--shared-models-module')
+    expect(help).toContain('--strict-shared-models')
+  })
 })

package/src/codegen/bin/flag-specs.ts

@@ -27,6 +27,8 @@ export const FLAG_SPECS: readonly FlagSpec[] = [
   { name: '--client-import-path', arg: '<path>', description: 'Override the client runtime import path', group: 'Codegen' },
   { name: '--share-models', description: 'Hoist $id-bearing schemas into a shared _models.ts', group: 'Codegen', default: 'on' },
   { name: '--no-share-models', description: 'Inline every type per route (legacy behaviour)', group: 'Codegen' },
+  { name: '--shared-models-module', arg: '<module>', description: 'Re-export every $id model from one module (convention; sharedTypesImport overrides)', group: 'Codegen' },
+  { name: '--strict-shared-models', description: 'Fail if any $id model would be generated as a local twin', group: 'Codegen' },
   { name: '--jsdoc', description: 'Emit JSDoc on generated types', group: 'Codegen', default: 'on' },
   { name: '--no-jsdoc', description: 'Suppress JSDoc', group: 'Codegen' },
   { name: '--enum-style', arg: '<union|enum>', description: 'How to emit enums (namespace mode)', group: 'Codegen' },

package/src/codegen/collect-models.test.ts

@@ -40,7 +40,29 @@ it('does NOT throw for ordinary schemas without the reserved prefix', () => {
 
 it('resolveModelImports tags mapped models and leaves others generated', () => {
   const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
-  const mapped = resolveModelImports(models, { 'urn:msg': { module: '@shared/schemas', name: 'Message' } })
+  const mapped = resolveModelImports(models, {
+    sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } },
+  })
   expect(mapped[0]?.import).toEqual({ module: '@shared/schemas', name: 'Message' })
-  expect(resolveModelImports(models, {})[0]?.import).toBeUndefined()
+  expect(resolveModelImports(models)[0]?.import).toBeUndefined()
+})
+
+it('resolveModelImports falls back to sharedModelsModule when no map entry matches', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const resolved = resolveModelImports(models, { sharedModelsModule: '@app/schemas' })
+  expect(resolved[0]?.import).toEqual({ module: '@app/schemas', name: 'Message' })
+})
+
+it('resolveModelImports: explicit map entry wins over the convention', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const resolved = resolveModelImports(models, {
+    sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Msg' } },
+    sharedModelsModule: '@app/schemas',
+  })
+  expect(resolved[0]?.import).toEqual({ module: '@override/pkg', name: 'Msg' })
+})
+
+it('resolveModelImports: empty-string convention is treated as unset (generated locally)', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  expect(resolveModelImports(models, { sharedModelsModule: '' })[0]?.import).toBeUndefined()
 })

package/src/codegen/collect-models.ts

@@ -93,16 +93,33 @@ export function collectModels(routes: AnyHttpRouteDoc[]): CollectedModel[] {
   })
 }
 
+/** Options controlling how collected models are resolved to external imports. */
+export interface ResolveModelImportsOptions {
+  /** Per-`$id` external import. A matching entry wins over `sharedModelsModule`. */
+  sharedTypesImport?: SharedTypesImportMap
+  /** Single module every otherwise-unmapped `$id` model re-exports from (convention). */
+  sharedModelsModule?: string
+}
+
 /**
- * Tags each collected model with its external import when its `$id` is a key in
- * the import map; models without a mapping keep `import` undefined (generated locally).
+ * Tags each collected model with its external import. Precedence:
+ *   1. an explicit `sharedTypesImport[$id]` entry (per-type override / rename),
+ *   2. otherwise, when `sharedModelsModule` is set, the convention
+ *      `{ module: sharedModelsModule, name: model.name }` — every shared model
+ *      re-exports from one module under its derived name (`$id`/`title` === export),
+ *   3. otherwise `import` stays undefined and the model is generated locally.
  */
 export function resolveModelImports(
   models: CollectedModel[],
-  map: SharedTypesImportMap = {}
+  options: ResolveModelImportsOptions = {},
 ): ResolvedModel[] {
+  const { sharedTypesImport = {}, sharedModelsModule } = options
   return models.map((model) => {
-    const mapped = map[model.id]
-    return mapped ? { ...model, import: mapped } : { ...model }
+    const mapped = sharedTypesImport[model.id]
+    if (mapped) return { ...model, import: mapped }
+    if (sharedModelsModule != null && sharedModelsModule !== '') {
+      return { ...model, import: { module: sharedModelsModule, name: model.name } }
+    }
+    return { ...model }
   })
 }

package/src/codegen/index.ts

@@ -18,6 +18,16 @@ export interface GenerateClientOptions extends ResolveInput {
   shareModels?: boolean
   /** Maps a model `$id` to an external import so a shared model is re-exported rather than generated. */
   sharedTypesImport?: SharedTypesImportMap
+  /** Single module every $id-bearing model re-exports from (convention; `sharedTypesImport` entries override). */
+  sharedModelsModule?: string
+  /** Hard-fail codegen if any $id-bearing model would be generated as a local structural twin. */
+  strictSharedModels?: boolean
+  /**
+   * Sink for non-error progress messages (e.g. the shared-models summary).
+   * Omitted by default so programmatic callers produce no console output; pass
+   * `console.log` to opt in. The CLI wires this to stdout.
+   */
+  logger?: (message: string) => void
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -44,6 +54,9 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     cleanOutDir: options.cleanOutDir,
     shareModels: options.shareModels,
     sharedTypesImport: options.sharedTypesImport,
+    sharedModelsModule: options.sharedModelsModule,
+    strictSharedModels: options.strictSharedModels,
+    logger: options.logger,
     target: options.target,
     kotlinPackage: options.kotlinPackage,
     kotlinSerializer: options.kotlinSerializer,

package/src/codegen/pipeline.ts

@@ -23,6 +23,10 @@ export interface PipelineOptions {
   cleanOutDir?: boolean
   shareModels?: boolean
   sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
+  /** Sink for non-error progress messages (shared-models summary). Defaults to silent. */
+  logger?: (message: string) => void
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -72,6 +76,9 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
     cleanOutDir,
     shareModels,
     sharedTypesImport: options.sharedTypesImport,
+    sharedModelsModule: options.sharedModelsModule,
+    strictSharedModels: options.strictSharedModels,
+    logger: options.logger,
   }
 
   switch (options.target) {

package/src/codegen/targets/_shared/target-run.ts

@@ -30,4 +30,14 @@ export interface TargetRunInput {
   shareModels?: boolean
   /** Maps a model `$id` to an external import (re-exported instead of generated). */
   sharedTypesImport?: SharedTypesImportMap
+  /** Single module every $id-bearing model re-exports from (convention; map entries override). */
+  sharedModelsModule?: string
+  /** When true, hard-fail if any $id-bearing model has no shared-type mapping (would be a local twin). */
+  strictSharedModels?: boolean
+  /**
+   * Sink for non-error progress messages (e.g. the shared-models summary).
+   * Defaults to undefined — programmatic callers stay silent; the CLI injects
+   * `console.log`. Output belongs to the caller, not the run module.
+   */
+  logger?: (message: string) => void
 }

package/src/codegen/targets/ts/run.ts

@@ -33,6 +33,9 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     selfContained = false,
     cleanOutDir = false,
     sharedTypesImport,
+    sharedModelsModule,
+    strictSharedModels = false,
+    logger,
   } = input
   const shareModels = input.shareModels ?? false
 
@@ -60,7 +63,7 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
   // covers ALL models (generated AND externally-imported) since scopes always
   // import shared types from `./_models`.
   const models = shareModels
-    ? resolveModelImports(collectModels(envelope.routes), sharedTypesImport)
+    ? resolveModelImports(collectModels(envelope.routes), { sharedTypesImport, sharedModelsModule })
     : []
   const idToModelName = new Map(models.map((m) => [m.id, m.name]))
 
@@ -74,6 +77,20 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     }
   }
 
+  if (shareModels && models.length > 0) {
+    const generated = models.filter((m) => m.import == null)
+    if (strictSharedModels && generated.length > 0) {
+      const list = generated.map((m) => `"${m.id}" (${m.name})`).join(', ')
+      throw new Error(
+        `[ts-procedures-codegen] --strict-shared-models: ${generated.length} $id-bearing schema(s) have no shared-type mapping and would be generated as local structural twins: ${list}. Add a sharedTypesImport entry, set sharedModelsModule, or drop --strict-shared-models.`,
+      )
+    }
+    const reExported = models.length - generated.length
+    logger?.(
+      `[ts-procedures-codegen] Shared models: ${models.length} total — ${reExported} re-exported, ${generated.length} generated locally.`,
+    )
+  }
+
   const files: GeneratedFile[] = []
 
   for (const group of groups) {

package/src/codegen/targets/ts/shared-models.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { runPipeline } from '../../pipeline.js'
 import type { DocEnvelope } from '../../../implementations/types.js'
 import type { GeneratedFile } from '../_shared/write-files.js'
@@ -233,6 +233,114 @@ describe('shared models (TS target, ajsc x-named-type)', () => {
     expect(messages.code).toContain("import type { Message } from './_models'")
   })
 
+  it('sharedModelsModule re-exports every $id model from the convention module', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      sharedModelsModule: '@app/schemas',
+    })
+
+    const modelsFile = findFile(files, '_models.ts')!
+    // Re-exported, not generated.
+    expect(modelsFile.code).toContain("export { Message } from '@app/schemas'")
+    expect(countMatches(modelsFile.code, /export type Message =/g)).toBe(0)
+
+    // Scopes still import the shared name from ./_models.
+    expect(findFile(files, 'messages.ts')!.code).toContain("from './_models'")
+  })
+
+  it('explicit sharedTypesImport overrides the sharedModelsModule convention per $id', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      sharedModelsModule: '@app/schemas',
+      sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Message' } },
+    })
+    expect(findFile(files, '_models.ts')!.code).toContain("export { Message } from '@override/pkg'")
+  })
+
+  it('emits a neutral summary of the re-exported / generated split via the injected logger', async () => {
+    const lines: string[] = []
+    await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      logger: (m) => lines.push(m),
+    })
+    expect(lines.join('\n')).toContain('Shared models: 1 total — 0 re-exported, 1 generated locally.')
+  })
+
+  it('does not emit a summary when there are no $id-bearing models', async () => {
+    const lines: string[] = []
+    await runPipeline({
+      envelope: noModelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      logger: (m) => lines.push(m),
+    })
+    expect(lines.join('\n')).not.toContain('Shared models:')
+  })
+
+  it('stays silent (no console output) when no logger is injected', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      await runPipeline({
+        envelope: modelEnvelope(),
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+      })
+      expect(log.mock.calls.flat().join('\n')).not.toContain('Shared models:')
+    } finally {
+      log.mockRestore()
+    }
+  })
+
+  it('strictSharedModels throws listing the offending $id and derived name', async () => {
+    await expect(
+      runPipeline({
+        envelope: modelEnvelope(),
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+        strictSharedModels: true,
+      }),
+    ).rejects.toThrow(/--strict-shared-models[\s\S]*urn:msg[\s\S]*Message/)
+  })
+
+  it('strictSharedModels passes once every model is covered by the convention', async () => {
+    await expect(
+      runPipeline({
+        envelope: modelEnvelope(),
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+        strictSharedModels: true,
+        sharedModelsModule: '@app/schemas',
+      }),
+    ).resolves.toBeDefined()
+  })
+
   it('fails loudly when a shared model name collides with a property-derived sub-type', async () => {
     // `latest` references the Message model; a sibling property literally named
     // `message` would make ajsc extract a structural sub-type ALSO named