npm - ts-procedures - Versions diffs - 9.1.0 → 10.0.0 - Mend

ts-procedures 9.1.0 → 10.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (71) hide show

package/CHANGELOG.md +73 -0
package/agent_config/claude-code/skills/ts-procedures/api-reference.md +4 -0
package/agent_config/copilot/copilot-instructions.md +2 -0
package/agent_config/cursor/cursorrules +2 -0
package/build/codegen/bin/cli.d.ts +4 -0
package/build/codegen/bin/cli.js +20 -1
package/build/codegen/bin/cli.js.map +1 -1
package/build/codegen/bin/cli.test.js +21 -0
package/build/codegen/bin/cli.test.js.map +1 -1
package/build/codegen/bin/flag-specs.js +3 -0
package/build/codegen/bin/flag-specs.js.map +1 -1
package/build/codegen/check-output.d.ts +28 -0
package/build/codegen/check-output.js +216 -0
package/build/codegen/check-output.js.map +1 -0
package/build/codegen/check-output.test.d.ts +1 -0
package/build/codegen/check-output.test.js +160 -0
package/build/codegen/check-output.test.js.map +1 -0
package/build/codegen/emit/api-route.js +2 -2
package/build/codegen/emit/api-route.js.map +1 -1
package/build/codegen/emit/context.d.ts +9 -0
package/build/codegen/emit/http-stream-route.js +1 -1
package/build/codegen/emit/http-stream-route.js.map +1 -1
package/build/codegen/emit/rpc-route.js +1 -1
package/build/codegen/emit/rpc-route.js.map +1 -1
package/build/codegen/emit/scope-file.js +15 -1
package/build/codegen/emit/scope-file.js.map +1 -1
package/build/codegen/emit/stream-route.js +1 -1
package/build/codegen/emit/stream-route.js.map +1 -1
package/build/codegen/emit-errors.integration.test.js +2 -2
package/build/codegen/emit-errors.integration.test.js.map +1 -1
package/build/codegen/emit-scope.test.js +55 -0
package/build/codegen/emit-scope.test.js.map +1 -1
package/build/codegen/emit-types.js +19 -0
package/build/codegen/emit-types.js.map +1 -1
package/build/codegen/emit-types.test.js +34 -0
package/build/codegen/emit-types.test.js.map +1 -1
package/build/codegen/index.d.ts +14 -0
package/build/codegen/index.js +11 -1
package/build/codegen/index.js.map +1 -1
package/build/codegen/resolve-envelope.js +1 -1
package/build/codegen/resolve-envelope.js.map +1 -1
package/build/codegen/targets/ts/name-collision.test.d.ts +1 -0
package/build/codegen/targets/ts/name-collision.test.js +30 -0
package/build/codegen/targets/ts/name-collision.test.js.map +1 -0
package/build/codegen/targets/ts/run.js +13 -0
package/build/codegen/targets/ts/run.js.map +1 -1
package/build/codegen/test-helpers/run-tsc.js +1 -1
package/build/codegen/test-helpers/run-tsc.js.map +1 -1
package/docs/client-and-codegen.md +17 -0
package/docs/migration-v8-to-v9.md +12 -4
package/package.json +8 -8
package/src/codegen/bin/cli.test.ts +28 -0
package/src/codegen/bin/cli.ts +27 -1
package/src/codegen/bin/flag-specs.ts +3 -0
package/src/codegen/check-output.test.ts +177 -0
package/src/codegen/check-output.ts +262 -0
package/src/codegen/emit/api-route.ts +2 -2
package/src/codegen/emit/context.ts +9 -0
package/src/codegen/emit/http-stream-route.ts +1 -1
package/src/codegen/emit/rpc-route.ts +1 -1
package/src/codegen/emit/scope-file.ts +19 -1
package/src/codegen/emit/stream-route.ts +1 -1
package/src/codegen/emit-errors.integration.test.ts +2 -2
package/src/codegen/emit-scope.test.ts +60 -0
package/src/codegen/emit-types.test.ts +36 -0
package/src/codegen/emit-types.ts +20 -0
package/src/codegen/index.ts +23 -1
package/src/codegen/resolve-envelope.ts +1 -1
package/src/codegen/targets/ts/name-collision.test.ts +34 -0
package/src/codegen/targets/ts/run.ts +16 -0
package/src/codegen/test-helpers/run-tsc.ts +1 -0

package/src/codegen/check-output.ts ADDED Viewed

@@ -0,0 +1,262 @@
+/**
+ * Opt-in self-validation of generated output (`--check`).
+ *
+ * Codegen is otherwise throw-to-fail: a bug that emits syntactically-written
+ * but non-compiling output (a dangling type reference, a duplicate identifier)
+ * exits 0 and silently overwrites a previously-working client. `--check` turns
+ * that into a loud, non-zero failure.
+ *
+ * Two modes:
+ *   - `'scan'` (default): a dependency-free, in-memory scan for *dangling type
+ *     references* — a type alias whose body is a bare identifier that is never
+ *     declared or imported (the exact shape of the namespace-mode root-union
+ *     bug, `export type Params = Root`). It deliberately does NOT try to detect
+ *     duplicate identifiers: that needs an accurate model of TypeScript's
+ *     declaration-merging rules to avoid false positives (a value and a type
+ *     legally share a name), the duplicate-from-name-collision case is already
+ *     caught deterministically at the source (see `emitScopeFile`), and `'tsc'`
+ *     mode catches the rest. Keeping the scan to one high-confidence check makes
+ *     it reliable and trivial to reason about.
+ *   - `'tsc'`: a real `tsc --noEmit` over the generated code via the programmatic
+ *     `typescript` API — authoritative, catches everything. `typescript` is a
+ *     dev/peer dependency that some consumers won't have installed, so it
+ *     gracefully falls back to `'scan'` (with a warning) when it can't be
+ *     resolved.
+ */
+import { dirname, resolve } from 'node:path'
+import type { GeneratedFile } from './targets/_shared/write-files.js'
+export type CheckMode = 'scan' | 'tsc'
+export interface CheckIssue {
+  /** Absolute path of the offending generated file. */
+  file: string
+  /** 1-based line number, when known. */
+  line?: number
+  message: string
+}
+export interface CheckResult {
+  ok: boolean
+  /** The mode actually run — may differ from the requested mode after a fallback. */
+  mode: CheckMode
+  issues: CheckIssue[]
+}
+// ---------------------------------------------------------------------------
+// Scan mode
+// ---------------------------------------------------------------------------
+// Any exported declaration that introduces an identifier the file can later
+// reference (so a `export type X = Foo` whose `Foo` is declared lower down
+// doesn't read as dangling).
+const DECL_RE =
+  /^\s*export\s+(?:declare\s+)?(?:type|interface|class|const|let|var|function|enum|namespace)\s+([A-Za-z_$][\w$]*)/
+// `export type X = <body>` — body captured for the bare-identifier test.
+const TYPE_ALIAS_RE = /^\s*export\s+type\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?);?\s*$/
+const IMPORT_NAMES_RE = /import\s+(?:type\s+)?(?:\*\s+as\s+\w+|(\w+)\s*,?\s*)?(?:\{([^}]*)\})?\s*from/g
+const BARE_IDENT_RE = /^[A-Za-z_$][\w$]*$/
+// TS lib globals / primitives a bare type-alias body may legitimately resolve
+// to without being declared or imported in the file.
+const BUILTIN_TYPES = new Set([
+  'string', 'number', 'boolean', 'void', 'undefined', 'null', 'unknown', 'any',
+  'never', 'object', 'symbol', 'bigint', 'this', 'true', 'false', 'Date',
+  'Array', 'ReadonlyArray', 'Record', 'Promise', 'Map', 'Set', 'Partial',
+  'Required', 'Readonly', 'Pick', 'Omit', 'Exclude', 'Extract', 'NonNullable',
+  'ReturnType', 'Parameters', 'Uint8Array', 'ArrayBuffer', 'Blob',
+])
+/**
+ * Collects every identifier the file declares or imports — the set of names a
+ * bare type-alias body is allowed to reference. Declarations at any nesting are
+ * counted: the check only asks "does this name exist in the file at all", not
+ * "is it in scope here", so it never false-positives on a valid reference.
+ */
+function collectKnownNames(code: string): Set<string> {
+  const names = new Set<string>()
+  for (const line of code.split('\n')) {
+    const decl = DECL_RE.exec(line)
+    if (decl) names.add(decl[1]!)
+  }
+  for (const m of code.matchAll(IMPORT_NAMES_RE)) {
+    if (m[1]) names.add(m[1])
+    if (m[2]) {
+      for (const part of m[2].split(',')) {
+        const name = part.split(/\s+as\s+/).pop()?.trim()
+        if (name) names.add(name)
+      }
+    }
+  }
+  return names
+}
+/**
+ * Flags `export type X = <Bare>` where `<Bare>` is a lone identifier that is
+ * neither declared nor imported in the file nor a TS built-in — the exact shape
+ * of the namespace-mode root-union bug (`export type Params = Root`). Bodies
+ * that are anything other than a single bare identifier (object literals,
+ * unions, generics, qualified names) are left alone: they're either valid or
+ * the kind of error only a real type-check can adjudicate.
+ */
+function scanFile(file: GeneratedFile, known: Set<string>): CheckIssue[] {
+  const issues: CheckIssue[] = []
+  const lines = file.code.split('\n')
+  for (let i = 0; i < lines.length; i += 1) {
+    const alias = TYPE_ALIAS_RE.exec(lines[i]!)
+    if (alias == null) continue
+    const rhs = alias[2]!.trim()
+    if (BARE_IDENT_RE.test(rhs) && !BUILTIN_TYPES.has(rhs) && !known.has(rhs)) {
+      issues.push({
+        file: file.path,
+        line: i + 1,
+        message: `Type alias "${alias[1]}" references "${rhs}", which is never declared or imported in this file (dangling reference).`,
+      })
+    }
+  }
+  return issues
+}
+export function scanGeneratedFiles(files: GeneratedFile[]): CheckIssue[] {
+  return files
+    .filter((f) => f.path.endsWith('.ts'))
+    .flatMap((f) => scanFile(f, collectKnownNames(f.code)))
+}
+// ---------------------------------------------------------------------------
+// tsc mode
+// ---------------------------------------------------------------------------
+/**
+ * Type-checks the generated files in-process with the programmatic `typescript`
+ * API. Builds a `Program` over the in-memory `code` via a `CompilerHost` that
+ * serves generated content for generated paths and delegates everything else
+ * (the default lib + `node_modules`) to the real filesystem. Files are anchored
+ * at `outDir`, so extensionless/bare imports (`./_models`, `ts-procedures/client`)
+ * resolve under Bundler resolution exactly as the consumer's tooling resolves
+ * them: self-contained output resolves entirely within the in-memory set;
+ * non-self-contained output finds the installed `ts-procedures` by walking up
+ * from `outDir` to the nearest `node_modules`. It reads no bytes it didn't emit
+ * and writes nothing, so it can't perturb the frozen codegen output. Works in
+ * dry-run too (nothing needs to be on disk). Returns `null` to signal "couldn't
+ * run, fall back to scan" when `typescript` can't be resolved.
+ *
+ * The in-memory host approach mirrors the sibling ts-channels generator's
+ * `assertGeneratedFilesCompile`, keeping the two generators' tsc checks aligned.
+ */
+async function tscCheck(files: GeneratedFile[]): Promise<CheckIssue[] | null> {
+  let ts: typeof import('typescript')
+  try {
+    const mod = await import('typescript')
+    ts = (mod as { default?: typeof import('typescript') }).default ?? mod
+  } catch {
+    return null
+  }
+  const tsFiles = files.filter((f) => f.path.endsWith('.ts'))
+  if (tsFiles.length === 0) return []
+  // ts-procedures emits extensionless relative imports (`from './_models'`),
+  // which are illegal under NodeNext — so type-check under Bundler resolution to
+  // match how that output is actually consumed (tsx / bundlers).
+  const options: import('typescript').CompilerOptions = {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    noEmit: true,
+    skipLibCheck: true,
+  }
+  const generated = new Map<string, string>()
+  const generatedDirs = new Set<string>()
+  for (const f of tsFiles) {
+    const abs = resolve(f.path)
+    generated.set(abs, f.code)
+    generatedDirs.add(dirname(abs))
+  }
+  const host = ts.createCompilerHost(options, true)
+  const baseGetSourceFile = host.getSourceFile.bind(host)
+  const baseReadFile = host.readFile.bind(host)
+  const baseFileExists = host.fileExists.bind(host)
+  const baseDirectoryExists = host.directoryExists?.bind(host)
+  host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreate) => {
+    const content = generated.get(resolve(fileName))
+    if (content !== undefined) return ts.createSourceFile(fileName, content, languageVersionOrOptions, true)
+    return baseGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate)
+  }
+  host.readFile = (fileName) => {
+    const content = generated.get(resolve(fileName))
+    return content !== undefined ? content : baseReadFile(fileName)
+  }
+  host.fileExists = (fileName) => generated.has(resolve(fileName)) || baseFileExists(fileName)
+  // Without this, Bundler resolution of `./_types` etc. bails when the virtual
+  // outDir doesn't exist on disk (e.g. --dry-run) and every relative import
+  // reports TS2307, cascading into TS7006 implicit-any noise.
+  host.directoryExists = (d) => generatedDirs.has(resolve(d)) || (baseDirectoryExists?.(d) ?? false)
+  const program = ts.createProgram([...generated.keys()], options, host)
+  const diagnostics = ts.getPreEmitDiagnostics(program).filter((d) => d.file != null && generated.has(resolve(d.file.fileName)))
+  return diagnostics.map((d) => {
+    const message = ts.flattenDiagnosticMessageText(d.messageText, '\n')
+    const issue: CheckIssue = {
+      file: d.file!.fileName,
+      message: `TS${d.code}: ${message}`,
+    }
+    if (d.start != null) {
+      issue.line = d.file!.getLineAndCharacterOfPosition(d.start).line + 1
+    }
+    return issue
+  })
+}
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+export interface CheckOptions {
+  mode: CheckMode
+  /** Surface fallback warnings to the user. */
+  logger?: (message: string) => void
+}
+export async function checkGeneratedFiles(
+  files: GeneratedFile[],
+  options: CheckOptions,
+): Promise<CheckResult> {
+  if (options.mode === 'tsc') {
+    // The in-memory type-check works from the emitted code, so it runs even in
+    // --dry-run. The only reason to fall back is a missing `typescript` peer.
+    const tscIssues = await tscCheck(files)
+    if (tscIssues != null) {
+      return { ok: tscIssues.length === 0, mode: 'tsc', issues: tscIssues }
+    }
+    options.logger?.(
+      '[ts-procedures-codegen] --check-mode tsc requested but `typescript` could not be resolved. Falling back to the scan check.',
+    )
+  }
+  const issues = scanGeneratedFiles(files)
+  return { ok: issues.length === 0, mode: 'scan', issues }
+}
+/**
+ * Renders a failed {@link CheckResult} as a multi-line, human-readable report.
+ * Shared by the CLI (stderr) and `generateClient({ validate })` (thrown error)
+ * so both surface findings identically.
+ */
+export function formatCheckResult(result: CheckResult): string {
+  const lines = [
+    `[ts-procedures-codegen] Self-check (${result.mode}) found ${result.issues.length} problem(s) in the generated output:`,
+  ]
+  for (const issue of result.issues) {
+    const loc = issue.line != null ? `:${issue.line}` : ''
+    lines.push(`  ${issue.file}${loc} — ${issue.message}`)
+  }
+  return lines.join('\n')
+}

package/src/codegen/emit/api-route.ts CHANGED Viewed

@@ -62,7 +62,7 @@ export async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext
   const declarations: string[] = []
   let paramsTypeName = 'void'
-  let returnTypeName = 'void'
+  let returnTypeName: string
   // Track reserved names across all sub-namespaces. Model names are reserved
   // so an ajsc-extracted sub-type can't silently merge with a referenced model.
@@ -180,5 +180,5 @@ export async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext
     ? injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
     : errorUnion !== null  // flat mode already emitted errors above
-  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
+  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected, routePascal: pascal }
 }

package/src/codegen/emit/context.ts CHANGED Viewed

@@ -13,6 +13,15 @@ export interface RouteChunks {
   hasStream: boolean
   /** True when this route emitted an `Errors` type (drives the `_errors` import at the top of the scope file). */
   hasErrors: boolean
+  /**
+   * The PascalCase name this route emits its types/namespace under (e.g.
+   * `GetTask`). `emitScopeFile` checks these for collisions across routes in
+   * the scope — two routes whose names pascalize to the same value (e.g.
+   * `get-task` and `getTask`, or `Foo`@v2 and `FooV2`@v1) would otherwise emit
+   * merged namespaces / duplicate `export type` declarations and a duplicated
+   * callable key, none of which compile.
+   */
+  routePascal: string
 }
 export interface EmitRouteContext {

package/src/codegen/emit/http-stream-route.ts CHANGED Viewed

@@ -158,5 +158,5 @@ export async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRo
     ctx.namespaceTypes
   )
-  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors }
+  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors, routePascal: pascal }
 }

package/src/codegen/emit/rpc-route.ts CHANGED Viewed

@@ -45,5 +45,5 @@ export async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext
   const hasErrorsInjected = injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
-  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
+  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected, routePascal: pascal }
 }

package/src/codegen/emit/scope-file.ts CHANGED Viewed

@@ -105,6 +105,13 @@ export async function emitScopeFile(
   const callables: string[] = []
   let hasStream = false
   let scopeHasErrors = false
+  // routePascal → the first route name that claimed it. Two routes whose names
+  // pascalize to the same value (e.g. `get-task`/`getTask`, or `Foo`@v2 and
+  // `FooV2`@v1) would emit merged namespaces, duplicate `export type`
+  // declarations, and a duplicated callable key — none of which compile. We
+  // fail fast with an actionable message rather than silently emit a broken
+  // scope file.
+  const pascalToName = new Map<string, string>()
   for (const route of group.routes) {
     let chunks: RouteChunks
@@ -125,10 +132,21 @@ export async function emitScopeFile(
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       throw new Error(
-        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`
+        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`,
+        { cause: err }
       )
     }
+    const prior = pascalToName.get(chunks.routePascal)
+    if (prior != null) {
+      throw new Error(
+        `[ts-procedures-codegen] Scope "${group.scopeKey}": routes "${prior}" and "${route.name}" both generate the name "${chunks.routePascal}", ` +
+          `whose generated types and callable would collide (duplicate identifier / duplicate object key). ` +
+          `Rename one of the routes so they pascalize to distinct names.`,
+      )
+    }
+    pascalToName.set(chunks.routePascal, route.name)
     allTypeDeclarations.push(...chunks.typeDeclarations)
     callables.push(chunks.callable)
     if (chunks.hasStream) hasStream = true

package/src/codegen/emit/stream-route.ts CHANGED Viewed

@@ -77,5 +77,5 @@ export async function emitStreamRoute(route: StreamHttpRouteDoc, ctx: EmitRouteC
     ctx.namespaceTypes
   )
-  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors }
+  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors, routePascal: pascal }
 }

package/src/codegen/emit-errors.integration.test.ts CHANGED Viewed

@@ -91,7 +91,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
       }
       // Dynamic import of the compiled output.
@@ -164,7 +164,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
       }
       const errorsUrl = `file://${join(outDir, 'out', '_errors.js')}`

package/src/codegen/emit-scope.test.ts CHANGED Viewed

@@ -1748,4 +1748,64 @@ describe('emitScopeFile errors-only routes (DX #6)', () => {
     expect(out).toContain('export type LogoutErrors = _errors.Unauthorized')
     expect(out).toContain('client.bindCallableTyped<void, void, LogoutErrors>')
   })
+  // Bug repro (downstream): two routes whose names pascalize to the same value
+  // (`get-task`/`getTask`) emit merged namespaces with duplicate `export type`
+  // declarations (the `Ref`/`Params` the downstream saw) AND a duplicated
+  // callable key — none of which compile. We fail fast with both route names.
+  it('throws when two routes in a scope pascalize to the same name', async () => {
+    const group: ScopeGroup = {
+      scopeKey: 'tasks',
+      camelCase: 'tasks',
+      routes: [
+        {
+          kind: 'rpc', name: 'get-task', path: '/t/1', method: 'post', scope: 'tasks', version: 1,
+          jsonSchema: { body: { type: 'object', properties: { ref: { type: 'object', properties: { a: { type: 'string' } }, required: ['a'] } }, required: ['ref'] } },
+        } satisfies RPCHttpRouteDoc,
+        {
+          kind: 'rpc', name: 'getTask', path: '/t/2', method: 'post', scope: 'tasks', version: 1,
+          jsonSchema: { body: { type: 'object', properties: { ref: { type: 'object', properties: { b: { type: 'number' } }, required: ['b'] } }, required: ['ref'] } },
+        } satisfies RPCHttpRouteDoc,
+      ],
+    }
+    await expect(emitScopeFile(group, { namespaceTypes: true })).rejects.toThrow(
+      /routes "get-task" and "getTask" both generate the name "GetTask"/,
+    )
+  })
+  // Version-suffix collision: `Foo`@v2 → `FooV2` and `FooV2`@v1 → `FooV2`.
+  it('throws when a version suffix collides with a literal route name', async () => {
+    const group: ScopeGroup = {
+      scopeKey: 'tasks',
+      camelCase: 'tasks',
+      routes: [
+        { kind: 'rpc', name: 'Foo', path: '/t/1', method: 'post', scope: 'tasks', version: 2, jsonSchema: {} } satisfies RPCHttpRouteDoc,
+        { kind: 'rpc', name: 'FooV2', path: '/t/2', method: 'post', scope: 'tasks', version: 1, jsonSchema: {} } satisfies RPCHttpRouteDoc,
+      ],
+    }
+    await expect(emitScopeFile(group, { namespaceTypes: true })).rejects.toThrow(/both generate the name "FooV2"/)
+  })
+  // Distinct pascal names — including the same name across DIFFERENT scopes and
+  // same-name-different-version within a scope — must NOT trip the guard.
+  it('allows two routes with the same property-derived sub-type in distinct route namespaces', async () => {
+    const group: ScopeGroup = {
+      scopeKey: 'tasks',
+      camelCase: 'tasks',
+      routes: [
+        {
+          kind: 'rpc', name: 'CreateTask', path: '/t/1', method: 'post', scope: 'tasks', version: 1,
+          jsonSchema: { body: { type: 'object', properties: { ref: { type: 'object', properties: { a: { type: 'string' } }, required: ['a'] } }, required: ['ref'] } },
+        } satisfies RPCHttpRouteDoc,
+        {
+          kind: 'rpc', name: 'UpdateTask', path: '/t/2', method: 'post', scope: 'tasks', version: 1,
+          jsonSchema: { body: { type: 'object', properties: { ref: { type: 'object', properties: { b: { type: 'number' } }, required: ['b'] } }, required: ['ref'] } },
+        } satisfies RPCHttpRouteDoc,
+      ],
+    }
+    const out = await emitScopeFile(group, { namespaceTypes: true })
+    // Both Refs survive, each fenced inside its own route namespace.
+    expect(out).toContain('export namespace CreateTask')
+    expect(out).toContain('export namespace UpdateTask')
+  })
 })

package/src/codegen/emit-types.test.ts CHANGED Viewed

@@ -179,6 +179,42 @@ describe('jsonSchemaToExtractedTypes', () => {
     expect(result!.body).toContain('id: string')
   })
+  // Bug repro (downstream): a ROOT-LEVEL union (anyOf/oneOf, no top-level
+  // `type`) whose arms ajsc can merge makes ajsc's inlineTypes:false path emit
+  // `export type Root = Root;` — a self-reference to a name it never declares.
+  // Stripping the prefix left `body === 'Root'`, which the namespace emitter
+  // wrapped as `export type Params = Root` → TS2304. The body must instead be
+  // inlined exactly as flat mode produces it.
+  it('inlines a root-level mergeable union instead of emitting a dangling Root self-reference', async () => {
+    const schema = {
+      anyOf: [
+        { type: 'object', properties: { a: { type: 'string' } }, required: ['a'] },
+        { type: 'object', properties: { a: { type: 'string' } }, required: ['a'] },
+      ],
+    }
+    const result = await jsonSchemaToExtractedTypes(schema)
+    expect(result).not.toBeUndefined()
+    expect(result!.body).not.toBe('Root')
+    expect(result!.declarations.some((d) => /^export\s+type\s+Root\b/.test(d))).toBe(false)
+    expect(result!.body).toContain('a: string')
+  })
+  // A genuinely distinct root union must keep working (it never produced the
+  // degenerate `Root` body — guard against the fix over-reaching).
+  it('keeps a root-level union of distinct objects inlined', async () => {
+    const schema = {
+      anyOf: [
+        { type: 'object', properties: { a: { type: 'string' } }, required: ['a'] },
+        { type: 'object', properties: { b: { type: 'number' } }, required: ['b'] },
+      ],
+    }
+    const result = await jsonSchemaToExtractedTypes(schema)
+    expect(result).not.toBeUndefined()
+    expect(result!.body).not.toBe('Root')
+    expect(result!.body).toContain('a: string')
+    expect(result!.body).toContain('b: number')
+  })
   // Bug repro (downstream): codegen emits `Cannot find name 'RootType'`.
   // ajsc with inlineTypes:false renders an array-root schema as TWO blocks:
   //   export type RootType = { ... };

package/src/codegen/emit-types.ts CHANGED Viewed

@@ -241,6 +241,26 @@ export async function jsonSchemaToExtractedTypes(
       .trim()
   }
+  // Degenerate self-reference guard. When a ROOT-LEVEL union (`anyOf`/`oneOf`
+  // with no top-level `type`) has arms ajsc can merge, ajsc's inlineTypes:false
+  // path emits `export type Root = Root;` — a self-reference to a name it never
+  // declares. Stripping the `Root =` prefix above leaves `body === 'Root'` with
+  // no `Root` declaration, so the namespace emitter would wrap it as
+  // `export type Params = Root` and the output wouldn't compile (TS2304). Flat
+  // mode never hits this because it force-inlines everything; here we do the
+  // same — recompute the body via the inline path so the union is materialised
+  // as `{ … } | { … }` exactly as flat mode produces it.
+  const hasRootDecl = declarations.some((d) => extractedDeclName(d) === 'Root')
+  if (body === 'Root' && !hasRootDecl) {
+    const inline = await resolveTypeBody(schema, options)
+    return {
+      declarations: [],
+      body: inline.body,
+      referencedNamedTypes: inline.referencedNamedTypes,
+      extractedTypeNames: [],
+    }
+  }
   return { declarations, body, referencedNamedTypes, extractedTypeNames }
 }

package/src/codegen/index.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import { resolveEnvelope, type ResolveInput } from './resolve-envelope.js'
 import { runPipeline, type GeneratedFile } from './pipeline.js'
+import { checkGeneratedFiles, formatCheckResult, type CheckMode } from './check-output.js'
 import type { AjscOptions } from './emit-types.js'
 import type { SharedTypesImportMap } from './collect-models.js'
 import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
@@ -22,6 +23,15 @@ export interface GenerateClientOptions extends ResolveInput {
   sharedModelsModule?: string
   /** Hard-fail codegen if any $id-bearing model would be generated as a local structural twin. */
   strictSharedModels?: boolean
+  /**
+   * Self-validate the generated output and throw if it won't compile, instead of
+   * silently returning a broken client (the programmatic peer of the CLI's
+   * `--check`). `true` runs the dependency-free `'scan'`; pass `{ mode: 'tsc' }`
+   * for a full type-check via the optional `typescript` peer (falls back to the
+   * scan if it isn't installed). The check runs on the in-memory output, so it
+   * works under `dryRun` too. TS target only. (default: off)
+   */
+  validate?: boolean | { mode?: CheckMode }
   /**
    * Sink for non-error progress messages (e.g. the shared-models summary).
    * Omitted by default so programmatic callers produce no console output; pass
@@ -42,7 +52,7 @@ export interface GenerateClientOptions extends ResolveInput {
 export async function generateClient(options: GenerateClientOptions): Promise<GeneratedFile[]> {
   const envelope = await resolveEnvelope(options)
-  return runPipeline({
+  const files = await runPipeline({
     envelope,
     outDir: options.outDir,
     ajsc: options.ajsc,
@@ -66,10 +76,22 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     swiftAccessLevel: options.swiftAccessLevel,
     swiftEmitter: options.swiftEmitter,
   })
+  if (options.validate) {
+    const mode: CheckMode = options.validate === true ? 'scan' : options.validate.mode ?? 'scan'
+    const result = await checkGeneratedFiles(files, { mode, logger: options.logger })
+    if (!result.ok) {
+      throw new Error(`${formatCheckResult(result)}\nThe generated client may not compile.`)
+    }
+  }
+  return files
 }
 export type { AjscOptions } from './emit-types.js'
 export type { ResolveInput } from './resolve-envelope.js'
+export { checkGeneratedFiles, scanGeneratedFiles, formatCheckResult } from './check-output.js'
+export type { CheckMode, CheckIssue, CheckResult } from './check-output.js'
 /**
  * @internal Subject to change with ajsc minor versions. Use for test injection

package/src/codegen/resolve-envelope.ts CHANGED Viewed

@@ -21,7 +21,7 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
       response = await fetch(input.url)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
-      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`)
+      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`, { cause: err })
     }
     if (!response.ok) {
       throw new Error(`[ts-procedures-codegen] ${input.url} returned HTTP ${response.status} ${response.statusText}`)

package/src/codegen/targets/ts/name-collision.test.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest'
+import { runPipeline } from '../../pipeline.js'
+import { makeRpcRoute, makeEnvelope } from '../../__fixtures__/make-envelope.js'
+// Bug repro (downstream): `--service-name Godmode` together with a scope named
+// `godmode` emitted two `export type GodmodeClient = …` declarations (the
+// aggregate client type AND the scope port type) → duplicate identifier. We now
+// fail fast at generation time with both knobs the user can turn.
+describe('ts target: --service-name vs scope-name collision', () => {
+  const envelope = makeEnvelope([
+    makeRpcRoute({
+      name: 'DoThing',
+      scope: 'godmode',
+      jsonSchema: { body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+    }),
+  ])
+  it('throws when a scope pascalizes to the same name as --service-name', async () => {
+    await expect(
+      runPipeline({ envelope, outDir: 'out', dryRun: true, serviceName: 'Godmode', namespaceTypes: true }),
+    ).rejects.toThrow(/Scope "godmode" produces client port type "GodmodeClient" which collides/)
+  })
+  it('does not throw when --service-name differs from every scope', async () => {
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      serviceName: 'GodmodeApi',
+      namespaceTypes: true,
+    })
+    expect(files.length).toBeGreaterThan(0)
+  })
+})

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

@@ -16,6 +16,7 @@ import { emitClientTypesFile } from '../../emit-client-types.js'
 import { emitClientRuntimeFile } from '../../emit-client-runtime.js'
 import { collectModels, resolveModelImports } from '../../collect-models.js'
 import { emitModelsFile } from '../../emit-models.js'
+import { toPascalCase } from '../../naming.js'
 export type TsRunInput = TargetRunInput
@@ -48,6 +49,21 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     envelope.errors.filter((e) => e.schema != null).map((e) => e.name),
   )
+  // The index emits one aggregate `${ServiceName}Client` type AND one
+  // `${ScopePascal}Client` port type per scope. When a scope's PascalCase name
+  // equals the service name's, the two declarations collide (duplicate
+  // identifier). Fail fast with both knobs the user can turn, rather than emit
+  // a non-compiling index.
+  const servicePascal = toPascalCase(serviceName)
+  for (const group of groups) {
+    if (toPascalCase(group.camelCase) === servicePascal) {
+      throw new Error(
+        `[ts-procedures-codegen] Scope "${group.scopeKey}" produces client port type "${servicePascal}Client" which collides with the aggregate client type "${servicePascal}Client" derived from --service-name "${serviceName}". ` +
+          `Rename the scope or change --service-name so they differ.`,
+      )
+    }
+  }
   if (selfContained) {
     for (const group of groups) {
       if (group.scopeKey === '_types' || group.scopeKey === '_client') {

package/src/codegen/test-helpers/run-tsc.ts CHANGED Viewed

@@ -51,6 +51,7 @@ export function runTsc(args: {
     const combined = [stdout, stderr].filter(Boolean).join('\n').trim()
     throw new Error(
       `[runTsc] tsc failed for ${tsconfigPath}:\n${combined || (e.message ?? '(no output)')}`,
+      { cause: err },
     )
   }
 }