@contractkit/plugin-csharp 0.0.0

package/tests/codegen-models.test.ts

@@ -0,0 +1,410 @@
+import { describe, expect, it } from 'vitest';
+import type { ContractRootNode, ScalarTypeNode } from '@contractkit/core';
+import { buildModelIndex } from '@contractkit/core';
+import { generateCSharpModels } from '../src/codegen-models.js';
+import { collectHoistedTypes } from '../src/hoist.js';
+import {
+    arrayType,
+    contractRoot,
+    enumType,
+    field,
+    inlineObjectType,
+    literalType,
+    model,
+    recordType,
+    refType,
+    scalarType,
+    tupleType,
+    unionType,
+} from './helpers.js';
+
+/** Render a root the way the plugin does: hoist across the project, then generate. */
+function render(
+    root: ContractRootNode,
+    opts: { modelsWithInput?: Set<string>; warn?: (m: string) => void; roots?: ContractRootNode[] } = {},
+): string {
+    const roots = opts.roots ?? [root];
+    const modelIndex = buildModelIndex(roots.flatMap(r => r.models));
+    const modelsWithInput = opts.modelsWithInput ?? new Set<string>();
+    const hoisted = collectHoistedTypes(roots, { modelIndex, modelsWithInput, warn: message => opts.warn?.(message) });
+    return generateCSharpModels(root, { namespace: 'Acme.Sdk', modelsWithInput, modelIndex, hoisted, warn: opts.warn });
+}
+
+function one(name: string, ...fields: Parameters<typeof field>[] extends never ? never : ReturnType<typeof field>[]): ContractRootNode {
+    return contractRoot([model(name, fields)]);
+}
+
+describe('file shape', () => {
+    it('opens with the generated header, re-enables nullable, and declares the models namespace', () => {
+        const out = render(one('Payment', field('id', scalarType('uuid'))));
+        expect(out.startsWith('// <auto-generated/>')).toBe(true);
+        // `<auto-generated/>` turns the nullable context off, so it has to be turned back on.
+        expect(out).toContain('#nullable enable');
+        expect(out).toContain('namespace Acme.Sdk.Models;');
+        expect(out).toContain('using System.Text.Json.Serialization;');
+    });
+});
+
+describe('scalar mapping', () => {
+    const cases: [ScalarTypeNode['name'], string][] = [
+        ['string', 'string'],
+        ['email', 'string'],
+        ['url', 'string'],
+        ['interval', 'string'],
+        ['number', 'double'],
+        ['int', 'long'],
+        ['bigint', 'BigInteger'],
+        ['decimal', 'decimal'],
+        ['boolean', 'bool'],
+        ['date', 'DateOnly'],
+        ['time', 'TimeOnly'],
+        ['datetime', 'DateTimeOffset'],
+        ['duration', 'TimeSpan'],
+        ['uuid', 'Guid'],
+        ['binary', 'byte[]'],
+        ['unknown', 'JsonElement'],
+        ['json', 'JsonElement'],
+        ['object', 'JsonElement'],
+    ];
+
+    it.each(cases)('maps %s to %s', (scalar, expected) => {
+        const out = render(one('M', field('f', scalarType(scalar))));
+        expect(out).toContain(`public required ${expected} F { get; init; }`);
+    });
+
+    it('maps int to long, since the source language means a JS safe integer', () => {
+        expect(render(one('M', field('f', scalarType('int'))))).toContain('public required long F { get; init; }');
+    });
+
+    it('maps a null scalar to a nullable object', () => {
+        expect(render(one('M', field('f', scalarType('null'))))).toContain('public required object? F { get; init; }');
+    });
+});
+
+describe('composite types', () => {
+    it('maps an array to List and a record to Dictionary', () => {
+        expect(render(one('M', field('f', arrayType(scalarType('string')))))).toContain('required List<string> F');
+        expect(render(one('M', field('f', recordType(scalarType('string'), scalarType('int')))))).toContain('required Dictionary<string, long> F');
+    });
+
+    it('warns about a record key that cannot be a JSON object key', () => {
+        const warnings: string[] = [];
+        render(one('M', field('f', recordType(scalarType('int'), scalarType('string')))), { warn: m => warnings.push(m) });
+        expect(warnings.join('\n')).toMatch(/not representable as a JSON object key/);
+    });
+
+    it('collapses a union of one non-null member to a nullable type rather than a declaration', () => {
+        const out = render(one('M', field('f', unionType(scalarType('string'), scalarType('null')))));
+        expect(out).toContain('required string? F');
+        expect(out).not.toContain('abstract record');
+    });
+});
+
+describe('optional, nullable, default and literal', () => {
+    it('makes a plain field required, so a missing property is a read error rather than a silent default', () => {
+        expect(render(one('M', field('f', scalarType('string'))))).toContain('public required string F { get; init; }');
+    });
+
+    it('omits an optional field when it is null, and does not mark it required', () => {
+        const out = render(one('M', field('f', scalarType('string'), { optional: true })));
+        expect(out).toContain('[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]');
+        expect(out).toContain('public string? F { get; init; }');
+        expect(out).not.toContain('required string? F');
+    });
+
+    it('writes an explicit null for a required nullable field, which the Kotlin SDK cannot express', () => {
+        const out = render(one('M', field('f', scalarType('string'), { nullable: true })));
+        expect(out).toContain('public required string? F { get; init; }');
+        expect(out).not.toContain('[JsonIgnore');
+    });
+
+    it('treats an optional nullable field as optional', () => {
+        const out = render(one('M', field('f', scalarType('string'), { optional: true, nullable: true })));
+        expect(out).toContain('[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]');
+        expect(out).not.toContain('required');
+    });
+
+    it('initializes a defaulted field instead of requiring it, typed for the scalar', () => {
+        expect(render(one('M', field('f', scalarType('int'), { default: 3 })))).toContain('public long F { get; init; } = 3L;');
+        expect(render(one('M', field('f', scalarType('number'), { default: 1.5 })))).toContain('public double F { get; init; } = 1.5d;');
+        expect(render(one('M', field('f', scalarType('decimal'), { default: 2 })))).toContain('public decimal F { get; init; } = 2m;');
+        expect(render(one('M', field('f', scalarType('boolean'), { default: true })))).toContain('public bool F { get; init; } = true;');
+        expect(render(one('M', field('f', scalarType('string'), { default: 'hi' })))).toContain('public string F { get; init; } = "hi";');
+        expect(render(one('M', field('f', scalarType('bigint'), { default: 7 })))).toContain('= new BigInteger(7);');
+    });
+
+    it('leaves a field required when its default has no C# literal form', () => {
+        const out = render(one('M', field('f', scalarType('uuid'), { default: 'not-a-literal' })));
+        expect(out).toContain('public required Guid F { get; init; }');
+    });
+
+    it('defaults a literal field to its one value, so the tag reaches the wire without a call site', () => {
+        expect(render(one('M', field('kind', literalType('card'))))).toContain('public string Kind { get; init; } = "card";');
+    });
+
+    it('names an enum member for a default written against a hoisted inline enum', () => {
+        const out = render(one('M', field('status', enumType('pending', 'done'), { default: 'done' })));
+        expect(out).toContain('public MStatus Status { get; init; } = MStatus.Done;');
+    });
+
+    it('names an enum member for a default written against a named enum contract', () => {
+        const root = contractRoot([
+            model('Rating', [], { type: enumType('good', 'neutral') }),
+            model('M', [field('r', refType('Rating'), { default: 'neutral' })]),
+        ]);
+        expect(render(root)).toContain('public Rating R { get; init; } = Rating.Neutral;');
+    });
+});
+
+describe('naming', () => {
+    it('PascalCases a property and keeps the declared name on the wire', () => {
+        const out = render(one('M', field('x-request-id', scalarType('string'))));
+        expect(out).toContain('[JsonPropertyName("x-request-id")]');
+        expect(out).toContain('public required string XRequestId { get; init; }');
+    });
+
+    it('renames a property that would collide with its own record, which C# rejects', () => {
+        const out = render(one('Invoice', field('invoice', scalarType('string'))));
+        expect(out).toContain('[JsonPropertyName("invoice")]');
+        expect(out).toContain('public required string InvoiceValue { get; init; }');
+    });
+});
+
+describe('wire key casing', () => {
+    it('renames keys for format(output=snake) without touching the property name', () => {
+        const root = contractRoot([model('M', [field('accessToken', scalarType('string'))], { outputCase: 'snake' })]);
+        const out = render(root);
+        expect(out).toContain('[JsonPropertyName("access_token")]');
+        expect(out).toContain('public required string AccessToken { get; init; }');
+    });
+
+    it('gives a split model one casing per direction', () => {
+        const root = contractRoot([
+            model('M', [field('accessToken', scalarType('string')), field('id', scalarType('string'), { visibility: 'readonly' })], {
+                inputCase: 'pascal',
+                outputCase: 'snake',
+            }),
+        ]);
+        const out = render(root);
+        expect(out).toContain('[JsonPropertyName("access_token")]');
+        expect(out).toContain('[JsonPropertyName("AccessToken")]');
+    });
+
+    it('warns when one unsplit record is asked for two different key sets', () => {
+        const warnings: string[] = [];
+        const root = contractRoot([model('M', [field('accessToken', scalarType('string'))], { inputCase: 'pascal', outputCase: 'snake' })]);
+        render(root, { warn: m => warnings.push(m) });
+        expect(warnings.join('\n')).toMatch(/can only spell one set of keys/);
+    });
+
+    it('warns that an anonymous object under a renamed contract keeps its own keys', () => {
+        const warnings: string[] = [];
+        const root = contractRoot([
+            model('M', [field('nested', inlineObjectType([field('innerKey', scalarType('string'))]))], { outputCase: 'snake' }),
+        ]);
+        render(root, { warn: m => warnings.push(m) });
+        expect(warnings.join('\n')).toMatch(/will not be snake-cased/);
+    });
+});
+
+describe('declarations', () => {
+    it('emits a sealed record, and a bodiless one for a contract with no fields', () => {
+        expect(render(one('M', field('f', scalarType('string'))))).toContain('public sealed record M');
+        expect(render(contractRoot([model('Empty', [])]))).toContain('public sealed record Empty;');
+    });
+
+    it('emits an enum whose members carry their wire spelling', () => {
+        const root = contractRoot([model('Status', [], { type: enumType('pending', 'in-progress') })]);
+        const out = render(root);
+        expect(out).toContain('[JsonConverter(typeof(JsonStringEnumConverter<Status>))]');
+        expect(out).toContain('[JsonStringEnumMemberName("in-progress")]');
+        expect(out).toContain('    InProgress,');
+    });
+
+    it('emits a non-object alias as a fully qualified global using, which is what an alias target needs', () => {
+        const root = contractRoot([model('UserId', [], { type: scalarType('string') })]);
+        expect(render(root)).toContain('global using UserId = System.String;');
+    });
+
+    it('qualifies a generic alias target too', () => {
+        const root = contractRoot([model('P', [field('id', scalarType('string'))]), model('Ps', [], { type: arrayType(refType('P')) })]);
+        expect(render(root)).toContain('global using Ps = System.Collections.Generic.List<Acme.Sdk.Models.P>;');
+    });
+
+    it('drops nullability from an alias, which C# cannot express, and says so', () => {
+        const warnings: string[] = [];
+        const root = contractRoot([model('MaybeName', [], { type: unionType(scalarType('string'), scalarType('null')) })]);
+        const out = render(root, { warn: m => warnings.push(m) });
+        expect(out).toContain('global using MaybeName = System.String;');
+        expect(warnings.join('\n')).toMatch(/cannot express as a using alias/);
+    });
+
+    it('emits an intersection at model level as a record rather than an opaque JSON value', () => {
+        const root = contractRoot([
+            model('A', [field('a', scalarType('string'))]),
+            model('B', [field('b', scalarType('string'))]),
+            model('C', [], { type: { kind: 'intersection', members: [refType('A'), refType('B')] } }),
+        ]);
+        const out = render(root);
+        expect(out).toContain('public sealed record C');
+        expect(out).toContain('public required string A { get; init; }');
+        expect(out).toContain('public required string B { get; init; }');
+    });
+});
+
+describe('inheritance', () => {
+    it('flattens bases into the record, later fields winning', () => {
+        const root = contractRoot([
+            model('Base', [field('id', scalarType('uuid')), field('note', scalarType('string'))]),
+            model('Child', [field('note', scalarType('int'), { override: true })], { bases: ['Base'] }),
+        ]);
+        const out = render(root);
+        expect(out).toContain('public sealed record Child');
+        expect(out).toContain('public required Guid Id { get; init; }');
+        expect(out).toContain('public required long Note { get; init; }');
+    });
+
+    it('warns rather than throwing when a base is undefined', () => {
+        const warnings: string[] = [];
+        render(contractRoot([model('Child', [field('x', scalarType('string'))], { bases: ['Missing'] })]), { warn: m => warnings.push(m) });
+        expect(warnings.join('\n')).toMatch(/extends 'Missing', which is not defined/);
+    });
+});
+
+describe('read and Input variants', () => {
+    it('splits a model with a readonly field into a read record and an Input twin', () => {
+        const root = contractRoot([model('M', [field('id', scalarType('uuid'), { visibility: 'readonly' }), field('name', scalarType('string'))])]);
+        const out = render(root);
+        expect(out).toContain('public sealed record M');
+        expect(out).toContain('public sealed record MInput');
+        expect(out.split('public sealed record MInput')[1]).not.toContain('Id');
+    });
+
+    it('drops a writeonly field from the read record', () => {
+        const root = contractRoot([
+            model('M', [field('secret', scalarType('string'), { visibility: 'writeonly' }), field('id', scalarType('uuid'))]),
+        ]);
+        const out = render(root);
+        expect(out.split('public sealed record MInput')[0]).not.toContain('Secret');
+        expect(out.split('public sealed record MInput')[1]).toContain('Secret');
+    });
+
+    it('aliases an enum Input twin rather than duplicating it, since an enum has no field visibility', () => {
+        const root = contractRoot([model('Status', [], { type: enumType('a', 'b') })]);
+        expect(render(root, { modelsWithInput: new Set(['Status']) })).toContain('global using StatusInput = Acme.Sdk.Models.Status;');
+    });
+});
+
+describe('plain unions', () => {
+    const root = contractRoot([
+        model('P', [field('id', scalarType('string'))]),
+        model('M', [field('v', unionType(refType('P'), scalarType('int')))]),
+    ]);
+
+    it('emits an abstract record closed by a private constructor', () => {
+        const out = render(root);
+        expect(out).toContain('public abstract record MV');
+        expect(out).toContain('    private MV() { }');
+        expect(out).toContain('public sealed record OfP(P Value) : MV;');
+        expect(out).toContain('public sealed record OfInt(long Value) : MV;');
+    });
+
+    it('tries members in declaration order, matching how the server parses the same union', () => {
+        const out = render(root);
+        expect(out).toContain('public sealed class MVConverter : JsonConverter<MV>');
+        const read = out.slice(out.indexOf('MV Read('), out.indexOf('void Write(', out.indexOf('MV Read(')));
+        expect(read.indexOf('OfP')).toBeLessThan(read.indexOf('OfInt'));
+        expect(out).toContain('throw new JsonException("No MV member matched the payload.");');
+    });
+
+    it('collapses a union of string literals to an enum instead', () => {
+        const literals = contractRoot([model('M', [field('v', unionType(literalType('a'), literalType('b')))])]);
+        const out = render(literals);
+        expect(out).toContain('public enum MV');
+        expect(out).toContain('[JsonStringEnumMemberName("a")]');
+    });
+});
+
+describe('discriminated unions', () => {
+    const root = contractRoot([
+        model('Card', [field('kind', literalType('card')), field('last4', scalarType('string'))]),
+        model('Bank', [field('kind', literalType('bank'))]),
+        model('M', [field('method', { kind: 'discriminatedUnion', discriminator: 'kind', members: [refType('Card'), refType('Bank')] })]),
+    ]);
+
+    it('emits an interface, so one contract can belong to several unions', () => {
+        const out = render(root);
+        expect(out).toContain('public interface MMethod');
+        expect(out).toContain('public sealed record Card : MMethod');
+        expect(out).toContain('public sealed record Bank : MMethod');
+    });
+
+    it('keeps the tag as a real defaulted property rather than serializer metadata', () => {
+        expect(render(root)).toContain('public string Kind { get; init; } = "card";');
+    });
+
+    it('dispatches on the tag value', () => {
+        const out = render(root);
+        expect(out).toContain('var tag = element.TryGetProperty("kind", out var tagElement)');
+        expect(out).toContain('"card" => element.Deserialize<Card>(options)!,');
+        expect(out).toContain('"bank" => element.Deserialize<Bank>(options)!,');
+    });
+
+    it('degrades to a JSON value and warns when the tag is not statically known', () => {
+        const warnings: string[] = [];
+        const enumTag = contractRoot([
+            model('Card', [field('kind', enumType('card'))]),
+            model('M', [field('method', { kind: 'discriminatedUnion', discriminator: 'kind', members: [refType('Card')] })]),
+        ]);
+        const out = render(enumTag, { warn: m => warnings.push(m) });
+        expect(warnings.join('\n')).toMatch(/is not a literal/);
+        expect(out).toContain('required JsonElement Method');
+    });
+});
+
+describe('tuples', () => {
+    it('hoists every arity, including the ones Kotlin maps onto Pair and Triple', () => {
+        const out = render(one('M', field('coords', tupleType(scalarType('number'), scalarType('number')))));
+        expect(out).toContain('public sealed record MCoords(double Item0, double Item1);');
+        expect(out).toContain('public sealed class MCoordsConverter : JsonConverter<MCoords>');
+    });
+
+    it('reads and writes a tuple as a JSON array of the declared length', () => {
+        const out = render(one('M', field('coords', tupleType(scalarType('number'), scalarType('string')))));
+        expect(out).toContain('array.GetArrayLength() != 2');
+        expect(out).toContain('array[0].Deserialize<double>(options)!,');
+        expect(out).toContain('array[1].Deserialize<string>(options)!');
+        expect(out).toContain('writer.WriteStartArray();');
+    });
+
+    it('travels correctly inside a collection, which a property-level converter could not', () => {
+        const out = render(one('M', field('all', arrayType(tupleType(scalarType('int'), scalarType('int'))))));
+        expect(out).toContain('required List<MAll> All');
+        expect(out).toContain('[JsonConverter(typeof(MAllConverter))]');
+    });
+});
+
+describe('hoisted shapes', () => {
+    it('names an inline object after the model and field that hold it', () => {
+        const out = render(one('M', field('nested', inlineObjectType([field('a', scalarType('string'))]))));
+        expect(out).toContain('public sealed record MNested');
+        expect(out).toContain('required MNested Nested');
+    });
+
+    it('lets a record in one file implement an interface declared in another', () => {
+        const a = contractRoot([model('Card', [field('kind', literalType('card'))])], 'a.ck');
+        const b = contractRoot([model('M', [field('m', { kind: 'discriminatedUnion', discriminator: 'kind', members: [refType('Card')] })])], 'b.ck');
+        const outA = render(a, { roots: [a, b] });
+        const outB = render(b, { roots: [a, b] });
+        expect(outA).toContain('public sealed record Card : MM');
+        expect(outB).toContain('public interface MM');
+    });
+});
+
+describe('deprecation', () => {
+    it('documents a deprecated model rather than marking it obsolete, which generated code would trip over', () => {
+        const out = render(contractRoot([model('M', [field('f', scalarType('string'))], { deprecated: true })]));
+        expect(out).toContain('/// <remarks>Deprecated in the contract.</remarks>');
+        expect(out).not.toContain('[Obsolete');
+    });
+});

package/tests/helpers.ts

@@ -0,0 +1,202 @@
+// Re-export all helpers from the SDK plugin's test helpers (same AST builder utilities)
+export type {
+    ContractRootNode,
+    ModelNode,
+    FieldNode,
+    ContractTypeNode,
+    ScalarTypeNode,
+    ArrayTypeNode,
+    TupleTypeNode,
+    RecordTypeNode,
+    EnumTypeNode,
+    LiteralTypeNode,
+    UnionTypeNode,
+    ModelRefTypeNode,
+    InlineObjectTypeNode,
+    LazyTypeNode,
+    SourceLocation,
+    OpRootNode,
+    OpRouteNode,
+    OpOperationNode,
+    OpParamNode,
+    OpRequestNode,
+    OpResponseNode,
+    HttpMethod,
+    ParamSource,
+    RouteModifier,
+} from '@contractkit/core';
+
+import type {
+    ContractRootNode,
+    ModelNode,
+    FieldNode,
+    ContractTypeNode,
+    ScalarTypeNode,
+    ArrayTypeNode,
+    TupleTypeNode,
+    RecordTypeNode,
+    EnumTypeNode,
+    LiteralTypeNode,
+    UnionTypeNode,
+    ModelRefTypeNode,
+    InlineObjectTypeNode,
+    LazyTypeNode,
+    SourceLocation,
+    OpRootNode,
+    OpRouteNode,
+    OpOperationNode,
+    OpParamNode,
+    OpRequestNode,
+    OpResponseNode,
+    HttpMethod,
+    ParamSource,
+    RouteModifier,
+} from '@contractkit/core';
+
+// ─── AST Builder Helpers ────────────────────────────────────────────────────
+
+export function loc(line = 1, file = 'test.ck'): SourceLocation {
+    return { file, line };
+}
+
+export function scalarType(name: ScalarTypeNode['name'], mods?: Partial<ScalarTypeNode>): ScalarTypeNode {
+    return { kind: 'scalar', name, ...mods };
+}
+
+export function arrayType(item: ContractTypeNode, mods?: { min?: number; max?: number }): ArrayTypeNode {
+    return { kind: 'array', item, ...mods };
+}
+
+export function tupleType(...items: ContractTypeNode[]): TupleTypeNode {
+    return { kind: 'tuple', items };
+}
+
+export function recordType(key: ContractTypeNode, value: ContractTypeNode): RecordTypeNode {
+    return { kind: 'record', key, value };
+}
+
+export function enumType(...values: string[]): EnumTypeNode {
+    return { kind: 'enum', values };
+}
+
+export function literalType(value: string | number | boolean): LiteralTypeNode {
+    return { kind: 'literal', value };
+}
+
+export function unionType(...members: ContractTypeNode[]): UnionTypeNode {
+    return { kind: 'union', members };
+}
+
+export function refType(name: string): ModelRefTypeNode {
+    return { kind: 'ref', name };
+}
+
+export function inlineObjectType(fields: FieldNode[]): InlineObjectTypeNode {
+    return { kind: 'inlineObject', fields };
+}
+
+export function lazyType(inner: ContractTypeNode): LazyTypeNode {
+    return { kind: 'lazy', inner };
+}
+
+export function field(name: string, type: ContractTypeNode, overrides?: Partial<FieldNode>): FieldNode {
+    return {
+        name,
+        optional: false,
+        nullable: false,
+        visibility: 'normal',
+        type,
+        loc: loc(),
+        ...overrides,
+    };
+}
+
+export function model(name: string, fields: FieldNode[], overrides?: Partial<ModelNode>): ModelNode {
+    return {
+        kind: 'model',
+        name,
+        fields,
+        loc: loc(),
+        ...overrides,
+    };
+}
+
+export function contractRoot(models: ModelNode[], file = 'test.ck'): ContractRootNode {
+    return { kind: 'contractRoot', meta: {}, models, file };
+}
+
+/**
+ * `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 {
+    return { kind: 'params', nodes };
+}
+
+export function paramRef(name: string): ParamSource {
+    return { kind: 'ref', name };
+}
+
+export function paramType(node: ContractTypeNode): ParamSource {
+    return { kind: 'type', node };
+}
+
+export function opRequest(bodyType: string | ContractTypeNode, contentType: string = 'application/json'): OpRequestNode {
+    const bt: ContractTypeNode = typeof bodyType === 'string' ? refType(bodyType) : bodyType;
+    return { bodies: [{ contentType, bodyType: bt }] };
+}
+
+export function opResponse(statusCode: number, bodyType?: string | ContractTypeNode, contentType?: string): OpResponseNode {
+    const bt: ContractTypeNode | undefined =
+        bodyType === undefined ? undefined : typeof bodyType === 'string' ? parseBodyTypeString(bodyType) : bodyType;
+    // A body with no explicit mime defaults to JSON, matching how every plugin used to read
+    // the old singular contentType field.
+    const bodies = bt === undefined ? [] : [{ contentType: contentType ?? 'application/json', bodyType: bt }];
+    return { statusCode, bodies, ...(bt !== undefined ? { hasBlock: true } : {}) };
+}
+
+function parseBodyTypeString(s: string): ContractTypeNode {
+    const arrayMatch = s.match(/^array\((.+)\)$/);
+    if (arrayMatch?.[1]) return { kind: 'array', item: refType(arrayMatch[1]) };
+    return refType(s);
+}
+
+function normalizeParamSource(value: unknown): ParamSource {
+    if (!value) return value as ParamSource;
+    if (typeof value === 'string') return { kind: 'ref', name: value };
+    if (Array.isArray(value)) return { kind: 'params', nodes: value as OpParamNode[] };
+    const v = value as ParamSource;
+    if (v.kind === 'params' || v.kind === 'ref' || v.kind === 'type') return v;
+    return { kind: 'type', node: value as ContractTypeNode };
+}
+
+export function opOperation(method: HttpMethod, overrides?: Partial<OpOperationNode> & { query?: unknown; headers?: unknown }): OpOperationNode {
+    const normalized = { ...overrides } as Partial<OpOperationNode>;
+    if (overrides?.query !== undefined) normalized.query = normalizeParamSource(overrides.query);
+    if (overrides?.headers !== undefined) normalized.headers = normalizeParamSource(overrides.headers);
+    return {
+        method,
+        responses: [],
+        loc: loc(1, 'test.op'),
+        ...normalized,
+    };
+}
+
+export function opRoute(
+    path: string,
+    operations: OpOperationNode[],
+    params?: ParamSource | OpParamNode[] | string,
+    modifiers?: RouteModifier[],
+): OpRouteNode {
+    const normalizedParams = params !== undefined ? normalizeParamSource(params) : undefined;
+    return { path, params: normalizedParams, operations, modifiers, loc: loc(1, 'test.op') };
+}
+
+export function opRoot(routes: OpRouteNode[], file = 'payments.op.ck', meta: Record<string, string> = {}): OpRootNode {
+    return { kind: 'opRoot', meta, routes, file };
+}