ts-procedures 8.5.0 → 9.0.0

package/src/codegen/__goldens__/ts-shared-models-module--models/index.ts

@@ -0,0 +1,48 @@
+// Auto-generated by ts-procedures-codegen (v8.6.0) — do not edit
+// Source hash: cb5f789247045d83e6eb2611821116bb
+import { createClient } from './_client'
+import type { ClientInstance, CreateClientConfig } from './_types'
+import * as _orders from './orders'
+import * as _billing from './billing'
+import * as _billingReports from './billing-reports'
+import * as _errorsModule from './_errors'
+
+export namespace Api {
+  export import Orders = _orders.Orders
+  export import Billing = _billing.Billing
+  export import BillingReports = _billingReports.BillingReports
+  export import Errors = _errorsModule.ApiErrors
+}
+
+export function createApiBindings(client: ClientInstance) {
+  return {
+    orders: _orders.Orders.bindScope(client),
+    billing: _billing.Billing.bindScope(client),
+    billingReports: _billingReports.BillingReports.bindScope(client),
+  }
+}
+
+/** Full typed client surface — every scope of `Api`. */
+export type ApiClient = ReturnType<typeof createApiBindings>
+/** Narrow port for the `orders` scope — inject as a DI seam without casting the aggregate client. */
+export type OrdersClient = ApiClient['orders']
+/** Narrow port for the `billing` scope — inject as a DI seam without casting the aggregate client. */
+export type BillingClient = ApiClient['billing']
+/** Narrow port for the `billingReports` scope — inject as a DI seam without casting the aggregate client. */
+export type BillingReportsClient = ApiClient['billingReports']
+
+/**
+ * Creates a typed client for this service with the generated error
+ * registry pre-configured. Non-2xx responses whose body `name` matches
+ * a registered error are thrown as typed class instances instead of
+ * generic `ClientHttpError`s.
+ */
+export function createApiClient(
+  config: Omit<CreateClientConfig<ReturnType<typeof createApiBindings>>, 'scopes' | 'errorRegistry'>
+) {
+  return createClient({
+    ...config,
+    errorRegistry: _errorsModule.ApiErrors.ApiErrorRegistry,
+    scopes: (client) => createApiBindings(client),
+  })
+}

package/src/codegen/__goldens__/ts-shared-models-module--models/orders.ts

@@ -0,0 +1,80 @@
+// Auto-generated by ts-procedures-codegen (v8.6.0) — do not edit
+// Source hash: cb5f789247045d83e6eb2611821116bb
+import type { ClientInstance, ProcedureCallOptions, TypedStream } from './_types'
+import type { ApiErrors } from './_errors'
+import type { Customer, Money, OrderEvent } from './_models'
+
+export namespace Orders {
+  export namespace GetOrder {
+    export type Params = { orderId: string; }
+    export type Response = Customer
+    export type Errors = ApiErrors.OrderRejected
+  }
+
+  export namespace SubmitOrder {
+    export type Params = { orderId: string; total: Money; }
+    export type Response = { ok: boolean; }
+    export type Errors = ApiErrors.OrderRejected
+  }
+
+  export namespace WatchOrders {
+    export type Params = { orderId: string; }
+    export type Yield = OrderEvent
+    export type Return = { total: number; }
+  }
+
+  /** Binds every callable in this scope to a configured client. */
+  export function bindScope(client: ClientInstance) {
+    return {
+      /**
+       * POST /orders/get-order/1
+       *
+       * @param options Optional per-call {@link ProcedureCallOptions} —
+       *   `signal` (cancel on dispose), `timeout`, `headers`, `basePath`.
+       * @throws Declared typed errors: {@link Orders.GetOrder.Errors}. Narrow with
+       *   `instanceof` on the throwing path, or call `.safe()` for a `Result`.
+       */
+      GetOrder: client.bindCallableTyped<Orders.GetOrder.Params, Orders.GetOrder.Response, Orders.GetOrder.Errors>({
+        name: 'GetOrder',
+        scope: 'orders',
+        path: '/orders/get-order/1',
+        method: 'post',
+        kind: 'rpc',
+      }),
+
+      /**
+       * POST /orders/submit-order/1
+       *
+       * @param options Optional per-call {@link ProcedureCallOptions} —
+       *   `signal` (cancel on dispose), `timeout`, `headers`, `basePath`.
+       * @throws Declared typed errors: {@link Orders.SubmitOrder.Errors}. Narrow with
+       *   `instanceof` on the throwing path, or call `.safe()` for a `Result`.
+       */
+      SubmitOrder: client.bindCallableTyped<Orders.SubmitOrder.Params, Orders.SubmitOrder.Response, Orders.SubmitOrder.Errors>({
+        name: 'SubmitOrder',
+        scope: 'orders',
+        path: '/orders/submit-order/1',
+        method: 'post',
+        kind: 'rpc',
+      }),
+
+      /**
+       * POST|GET /orders/watch-orders/1
+       *
+       * @param options Optional per-call {@link ProcedureCallOptions} —
+       *   `signal` (cancel on dispose), `timeout`, `headers`, `basePath`.
+       */
+      WatchOrders(params: Orders.WatchOrders.Params, options?: ProcedureCallOptions): TypedStream<Orders.WatchOrders.Yield, Orders.WatchOrders.Return> {
+        return client.stream<Orders.WatchOrders.Yield, Orders.WatchOrders.Return>({
+          name: 'WatchOrders',
+          scope: 'orders',
+          path: '/orders/watch-orders/1',
+          method: 'post',
+          kind: 'stream',
+          streamMode: 'sse',
+          params,
+        }, options)
+      },
+    }
+  }
+}

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

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { vi } from 'vitest'
-import { parseArgs, loadConfigFile, extractConfigPath, printPostRunHints, warnIfKotlinNoOpFlags, shouldShowHelp, type CodegenConfig } from './cli.js'
-import { formatHelp } from './flag-specs.js'
+import { parseArgs, loadConfigFile, extractConfigPath, printPostRunHints, warnIfKotlinNoOpFlags, shouldShowHelp, PARSE_HANDLED_FLAGS, type CodegenConfig } from './cli.js'
+import { KNOWN_FLAGS, formatHelp } from './flag-specs.js'
 
 describe('parseArgs', () => {
   it('parses --url and --out', () => {
@@ -433,6 +433,17 @@ describe('cli — unsupported-unions flag', () => {
   })
 })
 
+describe('flag catalog ↔ parser parity', () => {
+  // FLAG_SPECS is the single source of truth: a flag that parseArgs can
+  // dispatch but that isn't cataloged would be invisible in --help and
+  // did-you-mean; a cataloged flag with no handler would hit parseArgs'
+  // internal-error throw. Pinning the two sets equal makes both drifts
+  // impossible to land.
+  it('every flag handled by parseArgs is cataloged in FLAG_SPECS and vice versa', () => {
+    expect([...PARSE_HANDLED_FLAGS].sort()).toEqual([...KNOWN_FLAGS].sort())
+  })
+})
+
 describe('--help handling', () => {
   it('shouldShowHelp true for --help, -h, and bare (no args)', () => {
     expect(shouldShowHelp(['--help'])).toBe(true)

package/src/codegen/bin/cli.ts

@@ -5,7 +5,7 @@ import { createHash } from 'node:crypto'
 import { generateClient, type GenerateClientOptions } from '../index.js'
 import type { AjscOptions } from '../emit-types.js'
 import type { SharedTypesImportMap } from '../collect-models.js'
-import { KNOWN_FLAGS, formatHelp } from './flag-specs.js'
+import { KNOWN_FLAGS, FLAG_SPEC_BY_NAME, formatHelp } from './flag-specs.js'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -146,6 +146,120 @@ function closestKnownFlag(unknown: string): string | undefined {
 // parseArgs
 // ---------------------------------------------------------------------------
 
+/**
+ * Mutable accumulator threaded through the per-flag handlers. Seeded from the
+ * config file (when present); CLI flags then override field by field.
+ */
+interface ParseState {
+  url: string | undefined
+  file: string | undefined
+  outDir: string | undefined
+  watch: boolean
+  interval: number
+  ajsc: AjscOptions
+  clientImportPath: string | undefined
+  dryRun: boolean
+  namespaceTypes: boolean
+  selfContained: boolean
+  serviceName: string | undefined
+  cleanOutDir: boolean
+  target: 'ts' | 'kotlin' | 'swift' | undefined
+  kotlinPackage: string | undefined
+  kotlinSerializer: 'kotlinx' | 'none' | undefined
+  swiftSerializer: 'codable' | 'none' | undefined
+  swiftAccessLevel: 'public' | 'internal' | undefined
+  unsupportedUnions: 'throw' | 'fallback' | undefined
+  shareModels: boolean
+  sharedModelsModule: string | undefined
+  strictSharedModels: boolean
+  configPath: string | undefined
+}
+
+/**
+ * Applies one flag to the parse state. `value` is the consumed argv token for
+ * flags whose spec has `takesValue: true`, and always `undefined` otherwise.
+ */
+type FlagHandler = (state: ParseState, value: string | undefined) => void
+
+/** Renders an allowed-values list the way the CLI errors phrase it: `'a' or 'b'` / `'a', 'b', or 'c'`. */
+function humanizeAllowed(allowed: readonly string[]): string {
+  const quoted = allowed.map((v) => `'${v}'`)
+  if (quoted.length === 2) return `${quoted[0]} or ${quoted[1]}`
+  return `${quoted.slice(0, -1).join(', ')}, or ${quoted[quoted.length - 1]}`
+}
+
+/** Builds a handler for a value flag restricted to a closed set; invalid/missing values throw. */
+function enumValueFlag<T extends string>(
+  flag: string,
+  allowed: readonly T[],
+  assign: (state: ParseState, value: T) => void,
+): FlagHandler {
+  return (state, value) => {
+    if (value !== undefined && (allowed as readonly string[]).includes(value)) {
+      assign(state, value as T)
+    } else {
+      throw new Error(`Invalid ${flag} value: ${value ?? '(missing)'} (expected ${humanizeAllowed(allowed)})`)
+    }
+  }
+}
+
+/**
+ * Per-flag parse behavior, keyed by flag name. Arity (does the flag consume a
+ * value token?) comes from FLAG_SPECS.takesValue — this table only says what to
+ * do with the flag once recognized. Every key here MUST have a FLAG_SPECS entry
+ * and vice versa; parseArgs refuses to dispatch a flag missing from either
+ * side, and a test pins the two sets equal.
+ */
+const FLAG_HANDLERS: Record<string, FlagHandler> = {
+  '--url': (s, v) => { s.url = v },
+  '--file': (s, v) => { s.file = v },
+  '--out': (s, v) => { s.outDir = v },
+  '--watch': (s) => { s.watch = true },
+  '--interval': (s, v) => { s.interval = parseInt(v ?? '3000', 10) },
+  // Invalid --enum-style values are silently ignored (legacy lenience), unlike
+  // the enumValueFlag flags below which throw.
+  '--enum-style': (s, v) => {
+    if (v === 'union' || v === 'enum') {
+      s.ajsc.enumStyle = v
+    }
+  },
+  '--depluralize': (s) => { s.ajsc.depluralize = true },
+  '--array-item-naming': (s, v) => { s.ajsc.arrayItemNaming = v === 'false' ? false : v },
+  '--uncountable-words': (s, v) => {
+    s.ajsc.uncountableWords = (v ?? '').split(',').map((w) => w.trim()).filter(Boolean)
+  },
+  '--jsdoc': (s) => { s.ajsc.jsdoc = true },
+  '--no-jsdoc': (s) => { s.ajsc.jsdoc = false },
+  '--client-import-path': (s, v) => { s.clientImportPath = v },
+  '--dry-run': (s) => { s.dryRun = true },
+  '--namespace-types': (s) => { s.namespaceTypes = true },
+  '--no-namespace-types': (s) => { s.namespaceTypes = false },
+  '--self-contained': (s) => { s.selfContained = true },
+  '--no-self-contained': (s) => { s.selfContained = false },
+  '--service-name': (s, v) => { s.serviceName = v },
+  '--clean-out-dir': (s) => { s.cleanOutDir = true },
+  '--no-clean-out-dir': (s) => { s.cleanOutDir = false },
+  '--target': enumValueFlag('--target', ['ts', 'kotlin', 'swift'], (s, v) => { s.target = v }),
+  '--kotlin-package': (s, v) => { s.kotlinPackage = v },
+  '--kotlin-serializer': enumValueFlag('--kotlin-serializer', ['kotlinx', 'none'], (s, v) => { s.kotlinSerializer = v }),
+  '--swift-serializer': enumValueFlag('--swift-serializer', ['codable', 'none'], (s, v) => { s.swiftSerializer = v }),
+  '--swift-access-level': enumValueFlag('--swift-access-level', ['public', 'internal'], (s, v) => { s.swiftAccessLevel = v }),
+  '--unsupported-unions': enumValueFlag('--unsupported-unions', ['throw', 'fallback'], (s, v) => { s.unsupportedUnions = v }),
+  '--share-models': (s) => { s.shareModels = true },
+  '--no-share-models': (s) => { s.shareModels = false },
+  '--shared-models-module': (s, v) => { s.sharedModelsModule = v },
+  '--strict-shared-models': (s) => { s.strictSharedModels = true },
+  // configPath is consumed by the caller (main) before parseArgs is called with the loaded config.
+  // When called from main, config is already loaded. When called directly (tests), configPath is ignored.
+  '--config': (s, v) => { s.configPath = v },
+}
+
+/**
+ * The set of flags parseArgs can dispatch — exported so a test can pin it
+ * equal to KNOWN_FLAGS (i.e. FLAG_SPECS), keeping catalog and parser in sync.
+ */
+export const PARSE_HANDLED_FLAGS: readonly string[] = Object.keys(FLAG_HANDLERS)
+
 /**
  * Parses CLI argv (pass process.argv.slice(2)).
  * Throws with a descriptive message on validation errors.
@@ -154,125 +268,41 @@ function closestKnownFlag(unknown: string): string | undefined {
  * and CLI flags override them.
  */
 export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
-  let url: string | undefined = config?.url
-  let file: string | undefined = config?.file
-  let outDir: string | undefined = config?.outDir
-  let watch = config?.watch ?? false
-  let interval = config?.interval ?? 3000
-  const ajsc: AjscOptions = { jsdoc: true, ...config?.ajsc }
-  let clientImportPath: string | undefined = config?.clientImportPath
-  let dryRun = config?.dryRun ?? false
-  let namespaceTypes = config?.namespaceTypes ?? true
-  let selfContained = config?.selfContained ?? true
-  let serviceName: string | undefined = config?.serviceName
-  let cleanOutDir = config?.cleanOutDir ?? true
-  let target: 'ts' | 'kotlin' | 'swift' | undefined = config?.target
-  let kotlinPackage: string | undefined = config?.kotlin?.package
-  let kotlinSerializer: 'kotlinx' | 'none' | undefined = config?.kotlin?.serializer
-  let swiftSerializer: 'codable' | 'none' | undefined = config?.swift?.serializer
-  let swiftAccessLevel: 'public' | 'internal' | undefined = config?.swift?.accessLevel
-  let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
-  let shareModels = config?.shareModels ?? true
+  const state: ParseState = {
+    url: config?.url,
+    file: config?.file,
+    outDir: config?.outDir,
+    watch: config?.watch ?? false,
+    interval: config?.interval ?? 3000,
+    ajsc: { jsdoc: true, ...config?.ajsc },
+    clientImportPath: config?.clientImportPath,
+    dryRun: config?.dryRun ?? false,
+    namespaceTypes: config?.namespaceTypes ?? true,
+    selfContained: config?.selfContained ?? true,
+    serviceName: config?.serviceName,
+    cleanOutDir: config?.cleanOutDir ?? true,
+    target: config?.target,
+    kotlinPackage: config?.kotlin?.package,
+    kotlinSerializer: config?.kotlin?.serializer,
+    swiftSerializer: config?.swift?.serializer,
+    swiftAccessLevel: config?.swift?.accessLevel,
+    unsupportedUnions: config?.unsupportedUnions,
+    shareModels: config?.shareModels ?? true,
+    sharedModelsModule: config?.sharedModelsModule,
+    strictSharedModels: config?.strictSharedModels ?? false,
+    configPath: undefined,
+  }
   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++) {
     const arg = argv[i]
+    // Non-flag tokens (positionals) are silently ignored, matching the
+    // historical behavior. Value tokens never reach this check — they are
+    // consumed via ++i by the flag that owns them.
+    if (arg === undefined || !arg.startsWith('--')) continue
 
-    if (arg === '--url') {
-      url = argv[++i]
-    } else if (arg === '--file') {
-      file = argv[++i]
-    } else if (arg === '--out') {
-      outDir = argv[++i]
-    } else if (arg === '--watch') {
-      watch = true
-    } else if (arg === '--interval') {
-      interval = parseInt(argv[++i] ?? '3000', 10)
-    } else if (arg === '--enum-style') {
-      const val = argv[++i]
-      if (val === 'union' || val === 'enum') {
-        ajsc.enumStyle = val
-      }
-    } else if (arg === '--depluralize') {
-      ajsc.depluralize = true
-    } else if (arg === '--array-item-naming') {
-      const val = argv[++i]
-      ajsc.arrayItemNaming = val === 'false' ? false : val
-    } else if (arg === '--uncountable-words') {
-      ajsc.uncountableWords = (argv[++i] ?? '').split(',').map((w) => w.trim()).filter(Boolean)
-    } else if (arg === '--jsdoc') {
-      ajsc.jsdoc = true
-    } else if (arg === '--no-jsdoc') {
-      ajsc.jsdoc = false
-    } else if (arg === '--client-import-path') {
-      clientImportPath = argv[++i]
-    } else if (arg === '--dry-run') {
-      dryRun = true
-    } else if (arg === '--namespace-types') {
-      namespaceTypes = true
-    } else if (arg === '--no-namespace-types') {
-      namespaceTypes = false
-    } else if (arg === '--self-contained') {
-      selfContained = true
-    } else if (arg === '--no-self-contained') {
-      selfContained = false
-    } else if (arg === '--service-name') {
-      serviceName = argv[++i]
-    } else if (arg === '--clean-out-dir') {
-      cleanOutDir = true
-    } else if (arg === '--no-clean-out-dir') {
-      cleanOutDir = false
-    } else if (arg === '--target') {
-      const val = argv[++i]
-      if (val === 'ts' || val === 'kotlin' || val === 'swift') {
-        target = val
-      } else {
-        throw new Error(`Invalid --target value: ${val ?? '(missing)'} (expected 'ts', 'kotlin', or 'swift')`)
-      }
-    } else if (arg === '--kotlin-package') {
-      kotlinPackage = argv[++i]
-    } else if (arg === '--kotlin-serializer') {
-      const val = argv[++i]
-      if (val === 'kotlinx' || val === 'none') {
-        kotlinSerializer = val
-      } else {
-        throw new Error(`Invalid --kotlin-serializer value: ${val ?? '(missing)'} (expected 'kotlinx' or 'none')`)
-      }
-    } else if (arg === '--swift-serializer') {
-      const val = argv[++i]
-      if (val === 'codable' || val === 'none') {
-        swiftSerializer = val
-      } else {
-        throw new Error(`Invalid --swift-serializer value: ${val ?? '(missing)'} (expected 'codable' or 'none')`)
-      }
-    } else if (arg === '--swift-access-level') {
-      const val = argv[++i]
-      if (val === 'public' || val === 'internal') {
-        swiftAccessLevel = val
-      } else {
-        throw new Error(`Invalid --swift-access-level value: ${val ?? '(missing)'} (expected 'public' or 'internal')`)
-      }
-    } else if (arg === '--unsupported-unions') {
-      const val = argv[++i]
-      if (val === 'throw' || val === 'fallback') {
-        unsupportedUnions = val
-      } else {
-        throw new Error(`Invalid --unsupported-unions value: ${val ?? '(missing)'} (expected 'throw' or 'fallback')`)
-      }
-    } else if (arg === '--share-models') {
-      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('--')) {
+    const spec = FLAG_SPEC_BY_NAME.get(arg)
+    if (spec === undefined) {
       // Reject unknown flags loudly. Silently ignoring them led to a downstream
       // bug where a misspelled `--targt` produced an empty envelope with no
       // user-visible cause. Suggest the closest known flag when the typo is
@@ -283,10 +313,17 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
         : ' See the README for the supported flag set.'
       throw new Error(`[ts-procedures-codegen] Unknown CLI flag: ${arg}.${tail}`)
     }
-  }
 
-  // configPath is consumed by the caller (main) before parseArgs is called with the loaded config.
-  // When called from main, config is already loaded. When called directly (tests), configPath is ignored.
+    const handler = FLAG_HANDLERS[arg]
+    if (handler === undefined) {
+      // Drift guard: the flag is cataloged (so --help and did-you-mean know it)
+      // but nobody taught parseArgs what it does. The parity test catches this
+      // in CI; this throw catches it if the test is skipped.
+      throw new Error(`[ts-procedures-codegen] Internal error: ${arg} is cataloged in FLAG_SPECS but has no parseArgs handler.`)
+    }
+
+    handler(state, spec.takesValue ? argv[++i] : undefined)
+  }
 
   // ---------------------------------------------------------------------------
   // Validation — fails fast on user-controllable errors before envelope resolve.
@@ -296,16 +333,16 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   // see flag-shape errors from this block, not pipeline-internal throws.
   // ---------------------------------------------------------------------------
 
-  if (outDir === undefined) {
+  if (state.outDir === undefined) {
     throw new Error('Missing required argument: --out <dir>')
   }
 
-  if (url === undefined && file === undefined) {
+  if (state.url === undefined && state.file === undefined) {
     throw new Error('Missing required input source: provide --url <url> or --file <path>')
   }
 
   // Kotlin target requires a package; surface this before any I/O happens.
-  if (target === 'kotlin' && (kotlinPackage === undefined || kotlinPackage === '')) {
+  if (state.target === 'kotlin' && (state.kotlinPackage === undefined || state.kotlinPackage === '')) {
     throw new Error('Missing required argument: --kotlin-package <pkg> (required when --target kotlin)')
   }
 
@@ -314,40 +351,40 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   // from parseArgs; runtime/emitter wiring errors fire from pipeline.ts).
 
   return {
-    url,
-    file,
-    outDir,
-    watch,
-    interval,
-    ajsc,
-    ...(clientImportPath !== undefined ? { clientImportPath } : {}),
-    dryRun,
-    namespaceTypes,
-    selfContained,
-    ...(serviceName !== undefined ? { serviceName } : {}),
-    cleanOutDir,
-    ...(target !== undefined ? { target } : {}),
-    ...(kotlinPackage !== undefined
+    url: state.url,
+    file: state.file,
+    outDir: state.outDir,
+    watch: state.watch,
+    interval: state.interval,
+    ajsc: state.ajsc,
+    ...(state.clientImportPath !== undefined ? { clientImportPath: state.clientImportPath } : {}),
+    dryRun: state.dryRun,
+    namespaceTypes: state.namespaceTypes,
+    selfContained: state.selfContained,
+    ...(state.serviceName !== undefined ? { serviceName: state.serviceName } : {}),
+    cleanOutDir: state.cleanOutDir,
+    ...(state.target !== undefined ? { target: state.target } : {}),
+    ...(state.kotlinPackage !== undefined
       ? {
           kotlin: {
-            package: kotlinPackage,
-            ...(kotlinSerializer !== undefined ? { serializer: kotlinSerializer } : {}),
+            package: state.kotlinPackage,
+            ...(state.kotlinSerializer !== undefined ? { serializer: state.kotlinSerializer } : {}),
           },
         }
       : {}),
-    ...(swiftSerializer !== undefined || swiftAccessLevel !== undefined
+    ...(state.swiftSerializer !== undefined || state.swiftAccessLevel !== undefined
       ? {
           swift: {
-            ...(swiftSerializer !== undefined ? { serializer: swiftSerializer } : {}),
-            ...(swiftAccessLevel !== undefined ? { accessLevel: swiftAccessLevel } : {}),
+            ...(state.swiftSerializer !== undefined ? { serializer: state.swiftSerializer } : {}),
+            ...(state.swiftAccessLevel !== undefined ? { accessLevel: state.swiftAccessLevel } : {}),
           },
         }
       : {}),
-    ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
-    shareModels,
+    ...(state.unsupportedUnions !== undefined ? { unsupportedUnions: state.unsupportedUnions } : {}),
+    shareModels: state.shareModels,
     ...(sharedTypesImport !== undefined ? { sharedTypesImport } : {}),
-    ...(sharedModelsModule !== undefined ? { sharedModelsModule } : {}),
-    strictSharedModels,
+    ...(state.sharedModelsModule !== undefined ? { sharedModelsModule: state.sharedModelsModule } : {}),
+    strictSharedModels: state.strictSharedModels,
   }
 }
 

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { FLAG_SPECS, KNOWN_FLAGS, formatHelp } from './flag-specs.js'
+import { FLAG_SPECS, FLAG_SPEC_BY_NAME, KNOWN_FLAGS, formatHelp } from './flag-specs.js'
 
 describe('flag-specs', () => {
   it('derives KNOWN_FLAGS from the spec table', () => {
@@ -35,4 +35,19 @@ describe('flag-specs', () => {
     expect(help).toContain('--shared-models-module')
     expect(help).toContain('--strict-shared-models')
   })
+
+  it('keeps takesValue (parse arity) consistent with arg (help placeholder)', () => {
+    // `takesValue` drives parsing; `arg` drives help rendering. They describe
+    // the same fact, so a spec where they disagree is a bug in the catalog.
+    for (const spec of FLAG_SPECS) {
+      expect(spec.takesValue, `${spec.name}: takesValue must match presence of arg`).toBe(spec.arg !== undefined)
+    }
+  })
+
+  it('FLAG_SPEC_BY_NAME indexes every spec exactly once', () => {
+    expect(FLAG_SPEC_BY_NAME.size).toBe(FLAG_SPECS.length)
+    for (const spec of FLAG_SPECS) {
+      expect(FLAG_SPEC_BY_NAME.get(spec.name)).toBe(spec)
+    }
+  })
 })