ts-procedures 9.1.0 → 9.3.0

package/build/stack-utils.js

@@ -0,0 +1,95 @@
+/**
+ * Internal ts-procedures files that should be skipped when finding user code.
+ * Only skip the core library files, not test files or user code.
+ */
+const INTERNAL_FILES = [
+    '/index.ts',
+    '/index.js',
+    '/errors.ts',
+    '/errors.js',
+    '/stack-utils.ts',
+    '/stack-utils.js',
+    '/compute-schema.ts',
+    '/compute-schema.js',
+    '/parser.ts',
+    '/parser.js',
+];
+/**
+ * Captures the stack trace at the call site and extracts the definition location.
+ * Finds the first stack frame outside of ts-procedures internal files.
+ */
+export function captureDefinitionInfo() {
+    const err = new Error();
+    const stack = err.stack;
+    if (!stack) {
+        return {};
+    }
+    const lines = stack.split('\n');
+    // Find the first frame that's not from ts-procedures internals
+    // Skip the first line (Error message) and frames from this module
+    let userFrame;
+    for (let i = 1; i < lines.length; i++) {
+        const rawLine = lines[i];
+        if (!rawLine)
+            continue;
+        const line = rawLine.trim();
+        // Skip empty or invalid frames
+        if (!line.startsWith('at ')) {
+            continue;
+        }
+        // Skip frames from ts-procedures internal source files
+        const isInternalFile = INTERNAL_FILES.some(file => line.includes(file));
+        if (isInternalFile) {
+            continue;
+        }
+        // Skip frames from ts-procedures in node_modules (when used as a dependency)
+        if (line.includes('/node_modules/ts-procedures/') || line.includes('\\node_modules\\ts-procedures\\')) {
+            continue;
+        }
+        // Skip internal node frames
+        if (line.includes('node:') || line.startsWith('at Module.') || line.startsWith('at Object.<anonymous> (node:')) {
+            continue;
+        }
+        userFrame = line;
+        break;
+    }
+    if (!userFrame) {
+        return { definitionStack: stack };
+    }
+    const definedAt = parseStackFrame(userFrame);
+    return {
+        definedAt,
+        definitionStack: stack,
+    };
+}
+/**
+ * Parses a V8 stack frame line to extract file, line, and column info.
+ * Handles formats like:
+ * - "at Object.<anonymous> (/path/to/file.ts:10:5)"
+ * - "at functionName (/path/to/file.ts:10:5)"
+ * - "at /path/to/file.ts:10:5"
+ */
+function parseStackFrame(frame) {
+    // Match patterns like "(path:line:column)" or just "path:line:column"
+    const match = frame.match(/\(([^)]+):(\d+):(\d+)\)$/) || frame.match(/at ([^:]+):(\d+):(\d+)$/);
+    if (match && match[1] && match[2] && match[3]) {
+        return {
+            file: match[1],
+            line: parseInt(match[2], 10),
+            column: parseInt(match[3], 10),
+            raw: frame,
+        };
+    }
+    return undefined;
+}
+/**
+ * Formats definition info for appending to error stacks.
+ */
+export function formatDefinitionInfo(info, procedureName) {
+    if (!info.definedAt) {
+        return undefined;
+    }
+    const { file, line, column } = info.definedAt;
+    return `\n--- Procedure "${procedureName}" defined at ---\n    at ${file}:${line}:${column}`;
+}
+//# sourceMappingURL=stack-utils.js.map

package/build/stack-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-utils.js","sourceRoot":"","sources":["../src/stack-utils.ts"],"names":[],"mappings":"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"}

package/build/stack-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/stack-utils.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'vitest';
+import { captureDefinitionInfo, formatDefinitionInfo } from './stack-utils.js';
+describe('Stack Utils', () => {
+    describe('captureDefinitionInfo', () => {
+        test('returns definition info with definedAt', () => {
+            const info = captureDefinitionInfo();
+            // Should capture the call site in this test file
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+            expect(typeof info.definitionStack).toBe('string');
+        });
+        test('definedAt contains file, line, column when available', () => {
+            const info = captureDefinitionInfo();
+            // The definedAt should be present since we're calling from user code (test file)
+            if (info.definedAt) {
+                expect(info.definedAt.file).toBeDefined();
+                expect(typeof info.definedAt.file).toBe('string');
+                expect(info.definedAt.line).toBeDefined();
+                expect(typeof info.definedAt.line).toBe('number');
+                expect(info.definedAt.line).toBeGreaterThan(0);
+                expect(info.definedAt.column).toBeDefined();
+                expect(typeof info.definedAt.column).toBe('number');
+                expect(info.definedAt.column).toBeGreaterThan(0);
+                expect(info.definedAt.raw).toBeDefined();
+                expect(typeof info.definedAt.raw).toBe('string');
+            }
+        });
+        test('definitionStack contains Error stack trace', () => {
+            const info = captureDefinitionInfo();
+            expect(info.definitionStack).toContain('Error');
+            expect(info.definitionStack).toContain('at ');
+        });
+    });
+    describe('formatDefinitionInfo', () => {
+        test('returns undefined when definedAt is not present', () => {
+            const info = {};
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeUndefined();
+        });
+        test('returns formatted string when definedAt is present', () => {
+            const info = {
+                definedAt: {
+                    file: '/app/procedures/test.ts',
+                    line: 42,
+                    column: 5,
+                    raw: 'at Object.<anonymous> (/app/procedures/test.ts:42:5)',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeDefined();
+            expect(result).toContain('--- Procedure "TestProcedure" defined at ---');
+            expect(result).toContain('/app/procedures/test.ts:42:5');
+        });
+        test('includes procedure name in formatted output', () => {
+            const info = {
+                definedAt: {
+                    file: '/path/to/file.ts',
+                    line: 10,
+                    column: 3,
+                    raw: 'at /path/to/file.ts:10:3',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'MyCustomProcedure');
+            expect(result).toContain('"MyCustomProcedure"');
+        });
+    });
+    describe('integration with procedure creation', () => {
+        test('captures location from calling code', () => {
+            // Helper to simulate what happens in Create()
+            function simulateCreate() {
+                return captureDefinitionInfo();
+            }
+            const info = simulateCreate();
+            // Should have captured the location of the simulateCreate() call
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+        });
+    });
+});
+//# sourceMappingURL=stack-utils.test.js.map

package/build/stack-utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-utils.test.js","sourceRoot":"","sources":["../src/stack-utils.test.ts"],"names":[],"mappings":"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"}

package/docs/client-and-codegen.md

@@ -141,11 +141,21 @@ generated/
 | `--share-models` / `--no-share-models` | Collect `$id`-bearing subschemas into a shared `_models.ts` hub; scopes import from there instead of inlining types. | **On** |
 | `--shared-models-module <module>` | Convention form: re-export every `$id` model (with no explicit `sharedTypesImport` entry) from this single module. E.g. `--shared-models-module @app/schemas`. | Off |
 | `--strict-shared-models` | Fail the build if any `$id` model would be generated locally as a structural twin (i.e., not covered by `sharedTypesImport` or `sharedModelsModule`). CI guard. | Off |
+| `--check` | Self-validate the emitted output and **exit non-zero** if it won't compile — turns a silently-broken client into a loud generation failure. CI guard. | Off |
+| `--check-mode <scan\|tsc>` | How `--check` validates. `scan`: a dependency-free, in-memory scan for duplicate identifiers and dangling type references. `tsc`: a full `tsc --noEmit` type-check via the optional `typescript` peer (falls back to `scan` with a warning if `typescript` isn't installed). Implies `--check`. | `scan` |
 
 > **Note:** ajsc formatting options (`--enum-style`, `--depluralize`, `--array-item-naming`, `--uncountable-words`) only take effect in namespace mode (the default). With `--no-namespace-types`, all types are inlined and these options have no effect.
 >
 > You can also use a `ts-procedures-codegen.config.json` file in your project root instead of CLI flags. CLI flags override config values.
 
+### Generation-time safety
+
+Codegen fails fast (non-zero exit) rather than emitting a client that won't compile:
+
+- **Route-name collisions.** Two routes in the same scope whose names PascalCase to the same identifier (e.g. `get-task` and `getTask`, or `Foo` at version 2 and a literal `FooV2`) would emit a merged namespace with duplicate types and a duplicated callable key. Codegen throws naming both routes — rename one.
+- **`--service-name` vs scope collisions.** A scope whose PascalCase name equals `--service-name` (e.g. scope `godmode` with `--service-name Godmode`) would emit two `GodmodeClient` declarations. Codegen throws — rename the scope or change `--service-name`.
+- **`--check` self-validation.** Opt in to validate the *whole* emitted output before trusting it (see the flag table above). Use it in CI so a generator regression can never silently overwrite a working client with a broken one.
+
 ## Adapter Interface
 
 The client requires an adapter that handles the actual HTTP transport. A built-in fetch adapter is included, and you can implement your own for any HTTP library:
@@ -531,9 +541,16 @@ await generateClient({
     arrayItemNaming: 'Item',
     uncountableWords: ['criteria'],
   },
+  validate: true,         // optional — self-check the output and THROW if it won't compile
+                          // (the peer of the CLI's --check). Pass { mode: 'tsc' } for a full
+                          // type-check via the optional `typescript` peer; defaults to the
+                          // dependency-free dangling-reference scan. Runs on the in-memory
+                          // output, so it works under dryRun too.
 })
 ```
 
+When `validate` fails, `generateClient` throws an `Error` whose message lists every problem (`file:line — message`) — the same report the CLI prints to stderr. Use it in a build script to fail the build the moment the generator would emit a client that doesn't compile.
+
 ## Shared Model Types (`_models.ts`)
 
 When `shareModels` is on (the default), the codegen pre-pass collects every subschema with a `$id` field, deduplicates them, and emits a single `_models.ts` hub. Every scope that references one of those types imports from `./_models` instead of inlining it — so the type is defined once and shared across scopes.

package/docs/core.md

@@ -74,6 +74,7 @@ const { UpdateUser } = CreateHttp(
 **Rules:**
 - `schema.req` and `schema.params` are **mutually exclusive** — `schema.params` belongs to RPC procedures (`Create`/`CreateStream`), `schema.req` to HTTP procedures. Using `schema.params` on `CreateHttp` throws `ProcedureRegistrationError`.
 - Valid channels are `pathParams`, `query`, `body`, and `headers`; each is validated independently with per-channel error messages.
+- The channel names are provided by `THttpReqInput` (and its alias `APIInput` from `ts-procedures/http`) so that IDEs offer autocomplete when writing `schema: { req: { ... } }`. Use `satisfies APIInput` for additional typo protection on the keys.
 - `schema.res.body` documents the response body (drives codegen); omit `schema.res` entirely for 204-style no-content routes.
 - Factory-level `http.pathPrefix` / `http.scope` defaults apply; per-route config wins.
 - For HTTP streaming routes, use `CreateHttpStream` — same `schema.req` channels plus `schema.yield`.

package/docs/migration-v8-to-v9.md

@@ -8,10 +8,18 @@ with v9 produces the same files — nothing to migrate on the consumer side.
 The flip side of that guarantee: known v8 codegen issues carried over into
 9.0.0 unchanged — output couldn't change, so neither could the bugs. Fixes
 resume in 9.x releases when they can land without breaking parity for output
-that compiles today. First such fix: routes that declare `errors` but no
-req/res schema now emit a namespace housing their `Errors` union instead of a
-dangling type reference (the old output never typechecked, so no working
-consumer's bytes change).
+that compiles today. Each is parity-safe because the affected output never
+typechecked, so no working consumer's bytes change:
+
+- **9.1.0** — routes that declare `errors` but no req/res schema now emit a
+  namespace housing their `Errors` union instead of a dangling type reference.
+- **9.2.0** — namespace mode no longer emits a dangling `export type … = Root`
+  for a root-level `anyOf`/`oneOf` body (it inlines the union, as flat mode
+  already did). Plus two new fail-fast guards: a scope with two routes whose
+  names PascalCase to the same identifier, and a scope name colliding with
+  `--service-name`, now error at generation time instead of emitting a
+  non-compiling client. Codegen also gains an opt-in `--check` self-validation
+  (see the [client/codegen guide](client-and-codegen.md#cli-reference)).
 
 Server-side and tooling APIs have breaking changes, listed exhaustively below.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "9.1.0",
+  "version": "9.3.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

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

@@ -593,3 +593,31 @@ describe('--shared-models-module and --strict-shared-models', () => {
     expect(parsed.strictSharedModels).toBe(true)
   })
 })
+
+describe('--check / --check-mode', () => {
+  it('defaults check to false', () => {
+    expect(parseArgs(['--out', 'gen', '--file', 'e.json']).check).toBe(false)
+  })
+
+  it('parses --check as a boolean', () => {
+    expect(parseArgs(['--out', 'gen', '--file', 'e.json', '--check']).check).toBe(true)
+  })
+
+  it('--check-mode sets the mode and implies --check', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json', '--check-mode', 'tsc'])
+    expect(parsed.check).toBe(true)
+    expect(parsed.checkMode).toBe('tsc')
+  })
+
+  it('rejects an invalid --check-mode value', () => {
+    expect(() => parseArgs(['--out', 'gen', '--file', 'e.json', '--check-mode', 'nope'])).toThrow(
+      /Invalid --check-mode/,
+    )
+  })
+
+  it('seeds check/checkMode from config when the flags are absent', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json'], { check: true, checkMode: 'tsc' })
+    expect(parsed.check).toBe(true)
+    expect(parsed.checkMode).toBe('tsc')
+  })
+})

package/src/codegen/bin/cli.ts

@@ -32,6 +32,8 @@ export interface CodegenConfig {
   sharedTypesImport?: SharedTypesImportMap
   sharedModelsModule?: string
   strictSharedModels?: boolean
+  check?: boolean
+  checkMode?: 'scan' | 'tsc'
 }
 
 export interface ParsedArgs {
@@ -55,6 +57,8 @@ export interface ParsedArgs {
   sharedTypesImport?: SharedTypesImportMap
   sharedModelsModule?: string
   strictSharedModels: boolean
+  check: boolean
+  checkMode?: 'scan' | 'tsc'
 }
 
 // ---------------------------------------------------------------------------
@@ -172,6 +176,8 @@ interface ParseState {
   shareModels: boolean
   sharedModelsModule: string | undefined
   strictSharedModels: boolean
+  check: boolean
+  checkMode: 'scan' | 'tsc' | undefined
   configPath: string | undefined
 }
 
@@ -249,6 +255,9 @@ const FLAG_HANDLERS: Record<string, FlagHandler> = {
   '--no-share-models': (s) => { s.shareModels = false },
   '--shared-models-module': (s, v) => { s.sharedModelsModule = v },
   '--strict-shared-models': (s) => { s.strictSharedModels = true },
+  '--check': (s) => { s.check = true },
+  // Selecting a mode implies --check, so `--check-mode tsc` alone enables it.
+  '--check-mode': enumValueFlag('--check-mode', ['scan', 'tsc'], (s, v) => { s.checkMode = v; s.check = 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 },
@@ -290,6 +299,8 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     shareModels: config?.shareModels ?? true,
     sharedModelsModule: config?.sharedModelsModule,
     strictSharedModels: config?.strictSharedModels ?? false,
+    check: config?.check ?? false,
+    checkMode: config?.checkMode,
     configPath: undefined,
   }
   const sharedTypesImport = config?.sharedTypesImport
@@ -385,6 +396,8 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     ...(sharedTypesImport !== undefined ? { sharedTypesImport } : {}),
     ...(state.sharedModelsModule !== undefined ? { sharedModelsModule: state.sharedModelsModule } : {}),
     strictSharedModels: state.strictSharedModels,
+    check: state.check,
+    ...(state.checkMode !== undefined ? { checkMode: state.checkMode } : {}),
   }
 }
 
@@ -619,6 +632,19 @@ async function main(): Promise<void> {
       console.log(`[ts-procedures-codegen] Generated ${result.length} files → ${parsed.outDir}`)
       printPostRunHints(parsed)
     }
+
+    if (parsed.check) {
+      const { checkGeneratedFiles, formatCheckResult } = await import('../check-output.js')
+      const check = await checkGeneratedFiles(result, {
+        mode: parsed.checkMode ?? 'scan',
+        logger: (message: string) => { console.warn(message) },
+      })
+      if (!check.ok) {
+        console.error(formatCheckResult(check))
+        throw new Error(`Generated output failed the ${check.mode} self-check. The client may not compile.`)
+      }
+      console.log(`[ts-procedures-codegen] Self-check (${check.mode}) passed — no problems found.`)
+    }
   }
 }
 

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

@@ -49,6 +49,9 @@ export const FLAG_SPECS: readonly FlagSpec[] = [
   { name: '--swift-serializer', arg: '<codable|none>', takesValue: true, description: 'Swift Codable conformance', group: 'Targets', default: 'codable' },
   { name: '--swift-access-level', arg: '<public|internal>', takesValue: true, description: 'Swift access level', group: 'Targets', default: 'public' },
   { name: '--unsupported-unions', arg: '<throw|fallback>', takesValue: true, description: 'Behaviour for untagged oneOf schemas', group: 'Targets', default: 'throw' },
+  // Misc
+  { name: '--check', takesValue: false, description: 'Self-validate the generated output; exit non-zero on problems', group: 'Misc' },
+  { name: '--check-mode', arg: '<scan|tsc>', takesValue: true, description: 'How --check validates: scan (dependency-free) or tsc (type-check; needs typescript, falls back to scan). Implies --check', group: 'Misc', default: 'scan' },
 ]
 
 export const KNOWN_FLAGS: readonly string[] = FLAG_SPECS.map((s) => s.name)

package/src/codegen/check-output.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from 'vitest'
+import { scanGeneratedFiles, checkGeneratedFiles, formatCheckResult } from './check-output.js'
+import { runPipeline } from './pipeline.js'
+import { generateClient } from './index.js'
+import { makeRpcRoute, makeEnvelope } from './__fixtures__/make-envelope.js'
+import type { GeneratedFile } from './targets/_shared/write-files.js'
+
+const file = (path: string, code: string): GeneratedFile => ({ path, code })
+
+const validEnvelope = makeEnvelope([
+  makeRpcRoute({
+    name: 'GetUser',
+    scope: 'users',
+    jsonSchema: {
+      body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+      response: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    },
+  }),
+])
+
+describe('check-output scan', () => {
+  it('does not flag same-named types in different namespaces (no false positive)', () => {
+    const code = [
+      'export namespace Tasks {',
+      '  export namespace A {',
+      '    export type Ref = { a: string }',
+      '  }',
+      '  export namespace B {',
+      '    export type Ref = { b: number }',
+      '  }',
+      '}',
+      '',
+    ].join('\n')
+    expect(scanGeneratedFiles([file('/out/tasks.ts', code)])).toEqual([])
+  })
+
+  it('flags a dangling bare type-alias reference (the namespace-mode Root bug)', () => {
+    const code = [
+      'export namespace Tasks {',
+      '  export namespace SetLink {',
+      '    export type Params = Root',
+      '  }',
+      '}',
+      '',
+    ].join('\n')
+    const issues = scanGeneratedFiles([file('/out/tasks.ts', code)])
+    expect(issues).toHaveLength(1)
+    expect(issues[0]!.message).toContain('dangling reference')
+    expect(issues[0]!.message).toContain('Root')
+  })
+
+  it('does not flag a bare alias that resolves to an import', () => {
+    const code = ["import type { Message } from './_models'", 'export type Params = Message', ''].join('\n')
+    expect(scanGeneratedFiles([file('/out/a.ts', code)])).toEqual([])
+  })
+
+  it('does not flag a bare alias that resolves to a built-in', () => {
+    expect(scanGeneratedFiles([file('/out/a.ts', 'export type Params = string\n')])).toEqual([])
+  })
+
+  it('does not flag a bare alias that resolves to a type declared in the same file', () => {
+    const code = ['export type Inner = { a: string }', 'export type Params = Inner', ''].join('\n')
+    expect(scanGeneratedFiles([file('/out/a.ts', code)])).toEqual([])
+  })
+})
+
+describe('checkGeneratedFiles orchestration', () => {
+  it('returns ok for clean scan', async () => {
+    const r = await checkGeneratedFiles([file('/out/a.ts', 'export type X = string\n')], { mode: 'scan' })
+    expect(r).toEqual({ ok: true, mode: 'scan', issues: [] })
+  })
+
+  it('returns not-ok with issues for broken scan', async () => {
+    const r = await checkGeneratedFiles([file('/out/a.ts', 'export type X = Nope\n')], { mode: 'scan' })
+    expect(r.ok).toBe(false)
+    expect(r.mode).toBe('scan')
+    expect(r.issues).toHaveLength(1)
+  })
+
+  it('tsc mode type-checks in-memory and passes clean self-resolving output', async () => {
+    const r = await checkGeneratedFiles([file('/out/a.ts', 'export type X = string\nexport const y: X = "z"\n')], {
+      mode: 'tsc',
+    })
+    // typescript is a devDependency here, so tsc mode actually runs.
+    expect(r.mode).toBe('tsc')
+    expect(r.ok).toBe(true)
+  })
+
+  it('tsc mode flags a real type error', async () => {
+    const r = await checkGeneratedFiles([file('/out/a.ts', 'export const n: number = "not a number"\n')], {
+      mode: 'tsc',
+    })
+    expect(r.mode).toBe('tsc')
+    expect(r.ok).toBe(false)
+    expect(r.issues.length).toBeGreaterThan(0)
+    expect(r.issues[0]!.message).toMatch(/^TS\d+:/)
+  })
+
+  // End-to-end: a real self-contained client (vendored ./_client + ./_types)
+  // must type-check via the in-memory host, proving relative imports resolve
+  // within the emitted set without anything written to disk.
+  it('tsc mode passes real self-contained generated output (dry-run, in-memory)', async () => {
+    const envelope = makeEnvelope([
+      makeRpcRoute({
+        name: 'GetUser',
+        scope: 'users',
+        jsonSchema: {
+          body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+          response: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+        },
+      }),
+    ])
+    const files = await runPipeline({
+      envelope,
+      outDir: '/unused-out',
+      dryRun: true,
+      selfContained: true,
+      namespaceTypes: true,
+    })
+    const r = await checkGeneratedFiles(files, { mode: 'tsc' })
+    expect(r.mode).toBe('tsc')
+    expect(r.issues).toEqual([])
+    expect(r.ok).toBe(true)
+
+    // The dependency-free scan must also pass the same real output.
+    expect(scanGeneratedFiles(files)).toEqual([])
+  })
+})
+
+describe('formatCheckResult', () => {
+  it('renders a header and one line per issue', () => {
+    const text = formatCheckResult({
+      ok: false,
+      mode: 'scan',
+      issues: [{ file: '/out/tasks.ts', line: 4, message: 'Type alias "Params" references "Root" …' }],
+    })
+    expect(text).toContain('Self-check (scan) found 1 problem(s)')
+    expect(text).toContain('/out/tasks.ts:4 — Type alias "Params" references "Root" …')
+  })
+})
+
+describe('generateClient({ validate })', () => {
+  it('returns files when valid output passes the scan', async () => {
+    const files = await generateClient({
+      envelope: validEnvelope,
+      outDir: '/unused-out',
+      dryRun: true,
+      selfContained: true,
+      namespaceTypes: true,
+      validate: true,
+    })
+    expect(files.length).toBeGreaterThan(0)
+  })
+
+  it('returns files when valid output passes the tsc check', async () => {
+    const files = await generateClient({
+      envelope: validEnvelope,
+      outDir: '/unused-out',
+      dryRun: true,
+      selfContained: true,
+      namespaceTypes: true,
+      validate: { mode: 'tsc' },
+    })
+    expect(files.length).toBeGreaterThan(0)
+  })
+
+  it('does not validate when the option is omitted', async () => {
+    const files = await generateClient({
+      envelope: validEnvelope,
+      outDir: '/unused-out',
+      dryRun: true,
+      selfContained: true,
+      namespaceTypes: true,
+    })
+    expect(files.length).toBeGreaterThan(0)
+  })
+})