@contractkit/plugin-typescript 0.33.2 → 0.34.0

package/tests/codegen-plain-types.test.ts

@@ -38,13 +38,21 @@ describe('generatePlainTypes', () => {
             expect(output).not.toContain('z.infer');
         });
 
-        it('does not contain luxon imports for date fields', () => {
+        it('imports luxon for date fields, which render as DateTime', () => {
             const root = contractRoot([model('Event', [field('startDate', scalarType('date')), field('endDate', scalarType('datetime'))])]);
             const output = generatePlainTypes(root);
+            // The router parses these into Luxon objects and the SDK's revivers rehydrate them,
+            // so a `string` here was a claim neither side honoured.
+            expect(output).toContain("import { DateTime } from 'luxon';");
+            expect(output).toContain('startDate: DateTime;');
+            expect(output).toContain('endDate: DateTime;');
+        });
+
+        it('leaves interval as a string, since it transforms back to ISO on output', () => {
+            const root = contractRoot([model('Window', [field('span', scalarType('interval'))])]);
+            const output = generatePlainTypes(root);
+            expect(output).toContain('span: string;');
             expect(output).not.toContain('luxon');
-            expect(output).not.toContain('DateTime');
-            expect(output).toContain('startDate: string;');
-            expect(output).toContain('endDate: string;');
         });
     });
 
@@ -573,7 +581,7 @@ describe('generatePlainTypes', () => {
         it('includes source location in JSDoc', () => {
             const root = contractRoot([model('User', [field('name', scalarType('string'))], { loc: { file: 'user.ck', line: 5 } })]);
             const output = generatePlainTypes(root);
-            expect(output).toContain('file://./user.ck#L5');
+            expect(output).toContain('[User](./user.ck#L5)');
         });
     });
 

package/tests/codegen-sdk.test.ts

@@ -23,6 +23,7 @@ import {
     opRoute,
     opOperation,
     opParam,
+    paramRef,
     opRequest,
     opMultiRequest,
     opResponse,
@@ -134,6 +135,34 @@ describe('generateSdk', () => {
             expect(out).toContain("method: 'GET'");
             expect(out).toContain('return await parseJson<User>(result)');
         });
+
+        it('reads path params off the params argument when the route declares a model', () => {
+            const root = opRoot([
+                opRoute(
+                    '/pets/{petId}',
+                    [opOperation('get', { sdk: 'getPet', responses: [opResponse(200, 'Pet', 'application/json')] })],
+                    paramRef('PetRef'),
+                ),
+            ]);
+            const out = generateSdk(root);
+            // The signature has one argument named `params`, so a bare `petId` refers to nothing.
+            expect(out).toContain('async getPet(params: PetRef)');
+            expect(out).toContain('${encodeURIComponent(String(params.petId))}');
+            expect(out).not.toContain('encodeURIComponent(petId)');
+        });
+
+        it('brackets a hyphenated path param, which is not a property accessor', () => {
+            const root = opRoot([
+                opRoute(
+                    '/pets/{pet-id}',
+                    [opOperation('get', { sdk: 'getPet', responses: [opResponse(200, 'Pet', 'application/json')] })],
+                    paramRef('PetRef'),
+                ),
+            ]);
+            const out = generateSdk(root);
+            expect(out).toContain('${encodeURIComponent(String(params["pet-id"]))}');
+            expect(out).not.toContain('{pet-id}');
+        });
     });
 
     describe('POST with JSON body', () => {
@@ -369,7 +398,7 @@ describe('generateSdk', () => {
             const out = generateSdk(root);
             expect(out).toContain('Promise<{ data: Transfer; headers: { preferenceApplied?: string; etag: string } }>');
             expect(out).toContain("preferenceApplied: result.headers.get('preference-applied') ?? undefined");
-            expect(out).toContain("etag: result.headers.get('etag') ?? undefined");
+            expect(out).toContain("etag: result.headers.get('etag')!");
             expect(out).toContain('return { data, headers:');
         });
 
@@ -395,11 +424,74 @@ describe('generateSdk', () => {
             ]);
             const out = generateSdk(root);
             expect(out).toContain('Promise<{ headers: { xDeletedAt: string } }>');
-            expect(out).toContain("xDeletedAt: result.headers.get('x-deleted-at') ?? undefined");
+            expect(out).toContain("xDeletedAt: result.headers.get('x-deleted-at')!");
             expect(out).toContain('return { headers:');
             expect(out).not.toContain('parseJson<void>');
         });
 
+        it('coerces each header to the type the return shape declares', () => {
+            const root = opRoot([
+                opRoute('/things', [
+                    opOperation('get', {
+                        sdk: 'getThing',
+                        responses: [
+                            {
+                                statusCode: 200,
+                                hasBlock: true,
+                                bodies: [{ contentType: 'application/json', bodyType: { kind: 'ref', name: 'Thing' } }],
+                                headers: [
+                                    { name: 'x-count', optional: false, type: scalarType('int') },
+                                    { name: 'x-ratio', optional: true, type: scalarType('number') },
+                                    { name: 'x-cached', optional: false, type: scalarType('boolean') },
+                                    { name: 'x-fresh', optional: true, type: scalarType('boolean') },
+                                    { name: 'x-seq', optional: false, type: scalarType('bigint') },
+                                    { name: 'x-prev', optional: true, type: scalarType('bigint') },
+                                    { name: 'x-expires', optional: true, type: scalarType('datetime') },
+                                    { name: 'x-day', optional: false, type: scalarType('date') },
+                                ],
+                            },
+                        ],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root);
+            // Header values arrive as strings; the shape is typed from the contract, so without
+            // coercion every one of these is a TS2322 in one direction or the other.
+            expect(out).toContain('xCount: Number(result.headers.get(\'x-count\'))');
+            expect(out).toContain("xRatio: result.headers.get('x-ratio') === null ? undefined : Number(result.headers.get('x-ratio'))");
+            expect(out).toContain("xCached: result.headers.get('x-cached') === 'true'");
+            expect(out).toContain("xFresh: result.headers.get('x-fresh') === null ? undefined : result.headers.get('x-fresh') === 'true'");
+            expect(out).toContain("xSeq: BigInt(result.headers.get('x-seq')!)");
+            // Asserted in both branches: TS does not carry the null narrowing across a second
+            // `get()` call, and `BigInt` takes no null.
+            expect(out).toContain("xPrev: result.headers.get('x-prev') === null ? undefined : BigInt(result.headers.get('x-prev')!)");
+            // Temporals are Luxon objects since the SDK started reviving them, so a raw string no
+            // longer satisfies the shape `renderOutputTsType` produces.
+            expect(out).toContain("xExpires: result.headers.get('x-expires') === null ? undefined : DateTime.fromISO(result.headers.get('x-expires')!)");
+            expect(out).toContain("xDay: DateTime.fromFormat(result.headers.get('x-day')!, 'yyyy-MM-dd')");
+        });
+
+        it('rejects a header type that cannot be read from a header', () => {
+            const root = opRoot([
+                opRoute('/things', [
+                    opOperation('get', {
+                        sdk: 'getThing',
+                        responses: [
+                            {
+                                statusCode: 200,
+                                hasBlock: true,
+                                bodies: [{ contentType: 'application/json', bodyType: { kind: 'ref', name: 'Thing' } }],
+                                headers: [{ name: 'x-money', optional: false, type: scalarType('decimal') }],
+                            },
+                        ],
+                    }),
+                ]),
+            ]);
+            // Emitting code that does not compile would be worse than refusing; the CLI turns this
+            // into a plugin-scoped error naming the operation.
+            expect(() => generateSdk(root)).toThrow(/x-money.*GET \/things.*'decimal' scalar/s);
+        });
+
         it('preserves plain return type when no response headers are declared', () => {
             const root = opRoot([
                 opRoute(
@@ -415,7 +507,7 @@ describe('generateSdk', () => {
     });
 
     describe('query params', () => {
-        it('adds query parameter to method signature', () => {
+        it('requires the query argument when its fields are not optional', () => {
             const root = opRoot([
                 opRoute('/users', [
                     opOperation('get', {
@@ -426,10 +518,47 @@ describe('generateSdk', () => {
                 ]),
             ]);
             const out = generateSdk(root);
-            expect(out).toContain('query?: { page?: number; limit?: number }');
+            // The contract declares neither field with `?`, so the router demands both. Typing
+            // them optional let a caller omit a value the request would then be rejected for.
+            expect(out).toContain('query: { page: number; limit: number }');
             expect(out).toContain('URLSearchParams');
         });
 
+        it('makes the query argument optional when every field is', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        sdk: 'listUsers',
+                        query: [
+                            opParam('page', scalarType('int'), { optional: true }),
+                            // A default is equally omittable by the caller, so it counts as optional.
+                            opParam('limit', scalarType('int'), { default: 20 }),
+                        ],
+                        responses: [opResponse(200, 'array(User)', 'application/json')],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root);
+            expect(out).toContain('query?: { page?: number; limit?: number }');
+        });
+
+        it('widens an optional query argument that precedes a required one', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', {
+                        sdk: 'listUsers',
+                        query: [opParam('page', scalarType('int'), { optional: true })],
+                        headers: [opParam('x-tenant', scalarType('string'))],
+                        responses: [opResponse(200, 'array(User)', 'application/json')],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root);
+            // `async m(query?: Q, customHeaders: H)` is TS1016. Widening the earlier argument is
+            // the only fix that keeps the positional order call sites depend on.
+            expect(out).toContain("async listUsers(query: { page?: number }, customHeaders: { 'x-tenant': string })");
+        });
+
         it('appends qs directly to URL', () => {
             const root = opRoot([
                 opRoute('/users', [
@@ -501,7 +630,7 @@ describe('generateSdk', () => {
                 ]),
             ]);
             const out = generateSdk(root);
-            expect(out).toContain("customHeaders?: { 'x-api-key'?: string }");
+            expect(out).toContain("customHeaders: { 'x-api-key': string }");
         });
     });
 
@@ -1201,6 +1330,25 @@ describe('generateSdk — route-level deprecated cascade', () => {
         expect(deprecatedCount).toBe(2);
     });
 
+    it('keeps @deprecated in the same block as the description', () => {
+        const root = opRoot([
+            opRoute('/users', [
+                opOperation('get', {
+                    description: 'list the users',
+                    responses: [opResponse(200, 'User', 'application/json')],
+                    modifiers: ['deprecated'],
+                }),
+            ]),
+        ]);
+        const out = generateSdk(root);
+        // TypeScript honours only the JSDoc adjacent to the declaration, so a standalone
+        // `/** @deprecated */` above a description block is dropped by editors entirely.
+        expect(out).not.toContain('/** @deprecated */');
+        const block = out.slice(out.indexOf('    /**'), out.indexOf('async getUsers'));
+        expect(block).toContain('@description list the users');
+        expect(block).toContain('@deprecated');
+    });
+
     it('operation-level modifiers override route-level deprecated', () => {
         const root = opRoot([
             opRoute('/users', [opOperation('get', { modifiers: [], responses: [opResponse(200, 'User', 'application/json')] })], undefined, [
@@ -1260,9 +1408,15 @@ describe('renderTsType', () => {
             expect(renderTsType(scalarType('uuid'))).toBe('string');
         });
 
-        it('maps date and datetime to string', () => {
-            expect(renderTsType(scalarType('date'))).toBe('string');
-            expect(renderTsType(scalarType('datetime'))).toBe('string');
+        it('maps date and datetime to DateTime', () => {
+            expect(renderTsType(scalarType('date'))).toBe('DateTime');
+            expect(renderTsType(scalarType('datetime'))).toBe('DateTime');
+        });
+
+        it('maps duration to Duration but leaves interval a string', () => {
+            expect(renderTsType(scalarType('duration'))).toBe('Duration');
+            // `_ZodInterval` ends in a transform back to ISO, so a string is what arrives.
+            expect(renderTsType(scalarType('interval'))).toBe('string');
         });
 
         it('maps bigint to bigint', () => {
@@ -1289,8 +1443,8 @@ describe('renderTsType', () => {
             expect(renderTsType(scalarType('json'))).toBe('JsonValue');
         });
 
-        it('maps time to string', () => {
-            expect(renderTsType(scalarType('time'))).toBe('string');
+        it('maps time to DateTime', () => {
+            expect(renderTsType(scalarType('time'))).toBe('DateTime');
         });
 
         it('throws on an unmapped scalar name', () => {
@@ -1484,6 +1638,48 @@ describe('generateSdk — multipart/form-data', () => {
         expect(out).not.toContain("'Content-Type': 'application/json'");
         expect(out).not.toContain('JSON.stringify');
     });
+
+    it('does not import a model used only as a multipart body', () => {
+        const root = opRoot([
+            opRoute('/uploads', [
+                opOperation('post', {
+                    sdk: 'upload',
+                    request: opRequest('UploadForm', 'multipart/form-data'),
+                    responses: [opResponse(201, 'Upload', 'application/json')],
+                }),
+            ]),
+        ]);
+        const out = generateSdk(root, {
+            outPath: '/sdk/clients/uploads.client.ts',
+            modelOutPaths: new Map([
+                ['UploadForm', '/sdk/types/uploads.types.ts'],
+                ['Upload', '/sdk/types/uploads.types.ts'],
+            ]),
+        });
+        // The body is typed `FormData`, so UploadForm is never named in the output; importing it
+        // leaves an unused local that fails `noUnusedLocals` in the generated package.
+        expect(out).toContain('async upload(body: FormData)');
+        expect(out).not.toContain('UploadForm');
+        // Negative control: the response model is genuinely referenced and must still be imported.
+        expect(out).toContain('Upload');
+    });
+
+    it('still imports a model that is a multipart body and also a response body', () => {
+        const root = opRoot([
+            opRoute('/uploads', [
+                opOperation('post', {
+                    sdk: 'upload',
+                    request: opRequest('UploadForm', 'multipart/form-data'),
+                    responses: [opResponse(201, 'UploadForm', 'application/json')],
+                }),
+            ]),
+        ]);
+        const out = generateSdk(root, {
+            outPath: '/sdk/clients/uploads.client.ts',
+            modelOutPaths: new Map([['UploadForm', '/sdk/types/uploads.types.ts']]),
+        });
+        expect(out).toContain("import type { UploadForm } from '../types/uploads.types.js';");
+    });
 });
 
 // ─── generateMethod fetch assembly ────────────────────────────────────────
@@ -1973,3 +2169,62 @@ describe('generateSdkTsconfig', () => {
         expect(raw.endsWith('}\n')).toBe(true);
     });
 });
+
+// ─── bigint reviver gating ────────────────────────────────────────────────
+
+describe('generateSdk — bigint reviver gating', () => {
+    const withBody = (bodyType: string) =>
+        opRoot([opRoute('/things', [opOperation('get', { sdk: 'getThing', responses: [opResponse(200, bodyType, 'application/json')] })])]);
+
+    const opts = { outPath: '/sdk/src/things.client.ts', sdkOptionsPath: '/sdk/sdk-options.ts' };
+
+    it('imports the plain parseJson when no response carries a bigint', () => {
+        // `bigIntReviver` matches /^-?\d+n$/ against every string in the document, so a contract
+        // with no bigint anywhere still had a legitimate "123n" silently turned into a BigInt.
+        const out = generateSdk(withBody('Thing'), opts);
+        expect(out).toContain("import { parseJson } from '../sdk-options.js';");
+        expect(out).not.toContain('parseJsonWithBigInt');
+    });
+
+    it('imports the bigint-aware variant under the same name when one does', () => {
+        const root = opRoot([
+            opRoute('/things', [
+                opOperation('get', {
+                    sdk: 'getThing',
+                    responses: [opResponse(200, inlineObjectType([field('seq', scalarType('bigint'))]), 'application/json')],
+                }),
+            ]),
+        ]);
+        const out = generateSdk(root, opts);
+        // Aliased, so the method bodies are identical either way and only the import differs.
+        expect(out).toContain("import { parseJsonWithBigInt as parseJson } from '../sdk-options.js';");
+        expect(out).toContain('await parseJson<');
+    });
+
+    it('emits both variants in the shared runtime, since clients pick per contract', () => {
+        const runtime = generateSdkOptions();
+        expect(runtime).toContain('export async function parseJson<T>(res: Response): Promise<T> {');
+        expect(runtime).toContain('export async function parseJsonWithBigInt<T>(res: Response): Promise<T> {');
+        expect(runtime).toContain('return JSON.parse(await res.text()) as T;');
+        expect(runtime).toContain('return JSON.parse(await res.text(), bigIntReviver) as T;');
+    });
+});
+
+// ─── Hyphenated path parameters ───────────────────────────────────────────
+
+describe('generateSdk — path parameter names that are not identifiers', () => {
+    it('binds a valid identifier and interpolates it', () => {
+        const root = opRoot([
+            opRoute(
+                '/invoices/{invoice-id}',
+                [opOperation('get', { sdk: 'getInvoice', responses: [opResponse(200, 'Invoice', 'application/json')] })],
+                [opParam('invoice-id', scalarType('uuid'))],
+            ),
+        ]);
+        const out = generateSdk(root);
+        // `async getInvoice(invoice-id: string)` did not parse, and the URL kept the literal braces.
+        expect(out).toContain('async getInvoice(invoiceId: string)');
+        expect(out).toContain('${encodeURIComponent(invoiceId)}');
+        expect(out).not.toContain('{invoice-id}');
+    });
+});

package/tests/codegen-server.test.ts

@@ -5,8 +5,12 @@ import { opRoot, opRoute, opOperation, opParam, opRequest, opResponse, scalarTyp
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
-function makeCtx(rootDir = '/project', options: Record<string, unknown> = {}): PluginContext & { emitted: Map<string, string> } {
+function makeCtx(
+    rootDir = '/project',
+    options: Record<string, unknown> = {},
+): PluginContext & { emitted: Map<string, string>; warnings: string[] } {
     const emitted = new Map<string, string>();
+    const warnings: string[] = [];
     return {
         rootDir,
         options,
@@ -15,7 +19,11 @@ function makeCtx(rootDir = '/project', options: Record<string, unknown> = {}): P
         emitFile: (outPath: string, content: string) => {
             emitted.set(outPath, content);
         },
+        warn: (message: string) => {
+            warnings.push(message);
+        },
         emitted,
+        warnings,
     };
 }
 
@@ -495,3 +503,37 @@ describe('createTypescriptPlugin (sdk) — scaffold', () => {
         expect(pkg.dependencies).toBeUndefined();
     });
 });
+
+// ─── Output path template variables ───────────────────────────────────────
+
+describe('unresolved output path template variables', () => {
+    it('warns and names the key when a template variable has no value', async () => {
+        const plugin = createTypescriptPlugin({ server: { output: { routes: '{area}/{filename}.router.ts' } } }, '/project');
+        const ctx = makeCtx('/project');
+        // The .ck file declares no `options { keys { area } }`, so `{area}` has no value.
+        await plugin.generateTargets!(inputs(), ctx);
+
+        expect(ctx.warnings).toHaveLength(1);
+        expect(ctx.warnings[0]).toContain('{area}');
+        expect(ctx.warnings[0]).toContain('users.router.ts');
+        expect(ctx.warnings[0]).toContain('options { keys { area');
+    });
+
+    it('still emits the file, since visibility is the point and not refusal', async () => {
+        // Throwing would be worse than a literal directory: cli.ts catches and continues to the
+        // next plugin, so one bad template would cost this plugin its entire output.
+        const plugin = createTypescriptPlugin({ server: { output: { routes: '{area}/{filename}.router.ts' } } }, '/project');
+        const ctx = makeCtx('/project');
+        await plugin.generateTargets!(inputs(), ctx);
+
+        expect([...ctx.emitted.keys()].some(p => p.includes('{area}'))).toBe(true);
+    });
+
+    it('stays quiet when every variable resolves', async () => {
+        const plugin = createTypescriptPlugin({ server: { output: { routes: '{filename}.router.ts' } } }, '/project');
+        const ctx = makeCtx('/project');
+        await plugin.generateTargets!(inputs(), ctx);
+
+        expect(ctx.warnings).toEqual([]);
+    });
+});

package/tests/helpers.ts

@@ -107,8 +107,13 @@ export function contractRoot(models: ModelNode[], file = 'test.ck'): ContractRoo
     return { kind: 'contractRoot', meta: {}, models, file };
 }
 
-export function opParam(name: string, type: ContractTypeNode): OpParamNode {
-    return { name, type, loc: loc(1, 'test.op') };
+/**
+ * `optional` and `nullable` default to `false` rather than being omitted. Once codegen reads
+ * them, an omitted `undefined` is falsy and so silently means "required" — which would make a
+ * fixture that meant to say nothing accidentally assert something.
+ */
+export function opParam(name: string, type: ContractTypeNode, overrides?: Partial<OpParamNode>): OpParamNode {
+    return { name, type, optional: false, nullable: false, loc: loc(1, 'test.op'), ...overrides };
 }
 
 export function paramNodes(nodes: OpParamNode[]): ParamSource {

package/tests/pipeline.test.ts

@@ -5,6 +5,10 @@ import { generateSdk } from '../src/codegen-sdk.js';
 import { generateMcpFile } from '../src/codegen-mcp.js';
 import { SIMPLE_USER_CONTRACT, VISIBILITY_CONTRACT, INHERITANCE_CONTRACT, SIMPLE_USERS_OP, PARAMETERIZED_OP } from './helpers.js';
 
+/** The narrowed numeric coercion `renderScalar` emits — see NUMERIC_PREPROCESS in codegen-contract. */
+const NUM = `z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number())`;
+const NUM_INT = `z.preprocess((v) => (typeof v === 'string' && v.trim() !== '' ? Number(v) : v), z.number().int())`;
+
 function compileContractSource(source: string) {
     const diag = new DiagnosticCollector();
     const ck = parseCk(source, 'test.ck', diag);
@@ -29,7 +33,7 @@ describe('Contract pipeline (source -> parse -> codegen)', () => {
         expect(output).toContain('id: z.uuid()');
         expect(output).toContain('name: z.string()');
         expect(output).toContain('email: z.email()');
-        expect(output).toContain('age: z.coerce.number().optional()');
+        expect(output).toContain(`age: ${NUM}.optional()`);
         expect(output).toContain(`active: z.preprocess((v) => v === 'true' ? true : v === 'false' ? false : v, z.boolean()).default(true)`);
     });
 
@@ -60,7 +64,8 @@ contract Payslip: {
     it('compiles a contract with visibility to three-schema pattern', () => {
         const { output, diag } = compileContractSource(VISIBILITY_CONTRACT);
         expect(diag.hasErrors()).toBe(false);
-        expect(output).toContain('const UserBase = z.strictObject({');
+        // No writeonly model extends User, so no UserBase is emitted — nothing would read it.
+        expect(output).not.toContain('const UserBase');
         expect(output).toContain('export const User = z.strictObject({');
         expect(output).toContain('export const UserInput = z.strictObject({');
 
@@ -95,11 +100,11 @@ contract Kitchen: {
         const { output, diag } = compileContractSource(source);
         expect(diag.hasErrors()).toBe(false);
         expect(output).toContain('z.array(z.string())');
-        expect(output).toContain('z.tuple([z.coerce.number(), z.coerce.number()])');
+        expect(output).toContain(`z.tuple([${NUM}, ${NUM}])`);
         expect(output).toContain('z.record(z.string(), z.unknown())');
         expect(output).toContain('z.enum(["open", "closed"])');
         expect(output).toContain('z.literal("kitchen")');
-        expect(output).toContain('z.union([z.string(), z.coerce.number()])');
+        expect(output).toContain(`z.union([z.string(), ${NUM}])`);
         expect(output).toContain('Address');
         expect(output).toContain('z.lazy(() => Kitchen)');
     });
@@ -462,3 +467,45 @@ operation /users: {
         expect(warnings).toHaveLength(0);
     });
 });
+
+// ─── Numeric coercion, as it actually behaves at runtime ─────────────────
+
+describe('numeric scalar coercion', () => {
+    /** Build the emitted schema for one field and run real Zod against it. */
+    async function schemaFor(fieldDecl: string) {
+        const { output } = compileContractSource(`contract M: {\n    ${fieldDecl}\n}\n`);
+        const body = output.split('export const M = ')[1]!.split(');')[0]! + ')';
+        const { z } = await import('zod');
+        return new Function('z', `return ${body}`)(z) as { parse: (v: unknown) => unknown };
+    }
+
+    it('still coerces a string-shaped number, which query strings and headers depend on', async () => {
+        const M = await schemaFor('n: number');
+        expect(M.parse({ n: '42' })).toEqual({ n: 42 });
+        expect(M.parse({ n: 42 })).toEqual({ n: 42 });
+    });
+
+    it('rejects the values Number() silently turned into a number', async () => {
+        // `z.coerce.number()` is `Number(v)`: [] and '' become 0, null becomes 0, true becomes 1.
+        // Each of these validated cleanly and handed the handler a value the client never sent.
+        const M = await schemaFor('n: number');
+        for (const bad of [[], {}, null, true, '']) {
+            expect(() => M.parse({ n: bad }), `expected ${JSON.stringify(bad)} to be rejected`).toThrow();
+        }
+    });
+
+    it('keeps min and max chaining onto the outer schema', async () => {
+        const M = await schemaFor('n: int(min=1, max=5)');
+        expect(M.parse({ n: '3' })).toEqual({ n: 3 });
+        expect(() => M.parse({ n: 9 })).toThrow();
+        expect(() => M.parse({ n: 2.5 })).toThrow();
+    });
+
+    it('leaves boolean alone, which was already safe', async () => {
+        // Its preprocess maps only the two literal strings and hands everything else to
+        // z.boolean(), which rejects it — the shape the numeric scalars now share.
+        const M = await schemaFor('b: boolean');
+        expect(M.parse({ b: 'true' })).toEqual({ b: true });
+        expect(() => M.parse({ b: 1 })).toThrow();
+    });
+});

package/tests/ts-render.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { sourceLink } from '../src/ts-render.js';
+
+describe('sourceLink', () => {
+    it('emits a plain relative path, not a file:// URL', () => {
+        // `file://./x.ck` opens an authority component, so `.` parses as the host and the link
+        // resolves to nothing. The whole point of the helper is to not do that.
+        const link = sourceLink('User', '/out/schemas/user.schema.ts', '/out/contracts/user.ck', 5);
+        expect(link).toBe('[User](../contracts/user.ck#L5)');
+        expect(link).not.toContain('file://');
+    });
+
+    it('relativises the source path against the emitted file, not the process cwd', () => {
+        expect(sourceLink('User', '/a/b/c/out.ts', '/a/user.ck')).toBe('[User](../../user.ck)');
+    });
+
+    it('prefixes a bare sibling path with ./ so it reads as relative', () => {
+        expect(sourceLink('User', '/out/user.schema.ts', '/out/user.ck', 3)).toBe('[User](./user.ck#L3)');
+    });
+
+    it('omits the line anchor when no line is given', () => {
+        expect(sourceLink('billing.ck', '/out/sdk.ts', '/out/billing.ck')).toBe('[billing.ck](./billing.ck)');
+    });
+
+    it('falls back to the source path when there is no output path', () => {
+        // Codegen runs without a destination in the prettier plugin and in several tests.
+        expect(sourceLink('User', undefined, 'contracts/user.ck', 9)).toBe('[User](./contracts/user.ck#L9)');
+    });
+});