genoc 0.4.0 → 0.4.2

package/dist/analyzer/schema-mapper.js

@@ -1,7 +1,8 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { formatToBrandTypeName } from '../utils/case.js';
 import { buildTypeJsDoc, sanitizeTypeName } from '../utils/generator-helpers.js';
-import { quoteKey } from '../utils/string.js';
+import { escapeStringLiteral, quoteKey } from '../utils/string.js';
+import { parseJsonPointer } from '../utils/url.js';
 /** Indentation contract for multi-line types — 2-space unit pinned from the generated ServerParams interface; binding for downstream generators. */
 const INDENT_UNIT = '  ';
 function indentBy(level) {
@@ -28,6 +29,70 @@ function isComplexType(tsType) {
 function needsParens(tsType) {
     return tsType.includes(' | ') || tsType.includes(' & ');
 }
+/**
+ * Whether the rendered type has a top-level `|` (depth 0, outside any
+ * brackets/braces and outside string literals). Unlike the substring check
+ * in `needsParens`, nested unions inside `{...}`, `<...>` or `'...'` do not
+ * trigger it — this is the guard for appending `& {...}` onto a type whose
+ * tail could otherwise capture the append (`X | null & {...}` loses the
+ * literal to `null`).
+ */
+function hasTopLevelUnion(tsType) {
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < tsType.length; i++) {
+        const ch = tsType[i];
+        if (ch === '\\') {
+            i++;
+            continue;
+        }
+        if (ch === "'") {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (ch === '(' || ch === '{' || ch === '[' || ch === '<')
+            depth++;
+        else if (ch === ')' || ch === '}' || ch === ']' || ch === '>')
+            depth--;
+        else if (depth === 0 && ch === '|' && tsType[i - 1] === ' ' && tsType[i + 1] === ' ') {
+            return true;
+        }
+    }
+    return false;
+}
+/** Decode the last segment of a `$ref` string into its raw component key (`~1`/`~0` unescaped). */
+function decodedLastRefSegment(refStr) {
+    const segments = refStr.startsWith('#') ? parseJsonPointer(refStr.slice(1)) : refStr.split('/');
+    return segments[segments.length - 1] ?? refStr;
+}
+/** Encode a component key for embedding in a `#/components/schemas/…` ref string. */
+function encodePointerSegment(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function spineForEntry(entry) {
+    return {
+        familyId: entry.familyId,
+        propertyName: entry.propertyName,
+        literalValue: entry.literalValue,
+    };
+}
+/**
+ * A variant's own declared discriminant on the discriminator property:
+ * `const` first, then a single-value `enum` (D3). Multi-value enums and
+ * absent props yield nothing.
+ */
+function ownDeclaredDiscriminant(propSchema) {
+    if (!propSchema)
+        return undefined;
+    if (propSchema.const !== undefined)
+        return String(propSchema.const);
+    if (propSchema.enum !== undefined && propSchema.enum.length === 1) {
+        return String(propSchema.enum[0]);
+    }
+    return undefined;
+}
 /**
  * SchemaMapper converts OpenAPI 3.1 Schema Objects to TypeScript type strings.
  *
@@ -38,24 +103,33 @@ export class SchemaMapper {
     resolver;
     typeNameGenerator;
     discriminatorTargets;
-    reservedNames;
+    emittedNames;
+    discriminatorRegistry;
     brandedTypes = new Map();
     nullableWarned = false;
     warnSink;
-    constructor(resolver, typeNameGenerator, discriminatorTargets, reservedNames, warnSink) {
+    effectiveVersion;
+    constructor(resolver, opts) {
         // NOTE: discriminatorTargets must be keyed by names produced by the SAME
         // (rename-aware) typeNameGenerator that resolves $refs. Passing targets
         // keyed by raw schema names means renamed subtypes silently lose their
         // `& { prop: 'literal' }` intersection in the generated output.
+        // analyze() no longer builds or passes a targets map — the discriminator
+        // registry (when provided) is the SINGLE discriminator knowledge source
+        // (D1–D10 seam). The optional legacy targets param is kept for
+        // registry-less constructions; it only drives the legacy ref fallback in
+        // `resolveDiscriminatorInfo` below.
         this.resolver = resolver;
-        this.typeNameGenerator = typeNameGenerator ?? defaultTypeNameGenerator;
-        this.discriminatorTargets = discriminatorTargets ?? new Map();
-        this.reservedNames = reservedNames ?? new Set();
+        this.typeNameGenerator = opts?.typeNameGenerator ?? defaultTypeNameGenerator;
+        this.discriminatorTargets = opts?.discriminatorTargets ?? new Map();
+        this.emittedNames = opts?.emittedNames ?? new Set();
+        this.discriminatorRegistry = opts?.discriminatorRegistry;
         this.warnSink =
-            warnSink ??
+            opts?.warnSink ??
                 ((message) => {
                     process.stderr.write(message);
                 });
+        this.effectiveVersion = opts?.effectiveVersion;
     }
     getBrandedTypes() {
         return this.brandedTypes;
@@ -73,12 +147,28 @@ export class SchemaMapper {
             return { tsType: schema ? 'unknown' : 'never', imports: [] };
         }
         const visited = new Set();
-        const result = this.mapInternal(schema, name, context, visited, 0);
-        if (name && this.discriminatorTargets.has(name)) {
-            const target = this.discriminatorTargets.get(name);
-            result.tsType += ` & { ${quoteKey(target.propertyName)}: '${target.literalValue}' }`;
+        if (this.discriminatorRegistry && name !== undefined) {
+            const entry = this.discriminatorRegistry.byName.get(name);
+            const spine = entry ? spineForEntry(entry) : undefined;
+            const result = this.mapInternal(schema, name, context, visited, 0, spine);
+            if (entry) {
+                return this.appendDiscriminatorLiteral(result, entry.propertyName, entry.literalValue);
+            }
+            return result;
         }
-        return result;
+        return this.mapInternal(schema, name, context, visited, 0, undefined);
+    }
+    /**
+     * Append the discriminator literal intersection exactly ONCE (site 2),
+     * parenthesizing a top-level union so `X | null & {...}` cannot bind the
+     * literal to the last union member only (D9).
+     */
+    appendDiscriminatorLiteral(result, propertyName, literalValue) {
+        const appendage = ` & { ${quoteKey(propertyName)}: '${literalValue}' }`;
+        const tsType = hasTopLevelUnion(result.tsType)
+            ? `(${result.tsType})${appendage}`
+            : `${result.tsType}${appendage}`;
+        return { tsType, imports: result.imports };
     }
     getBrandTypeName(format, openApiType) {
         if (!format || format.trim() === '')
@@ -86,14 +176,17 @@ export class SchemaMapper {
         if (format === 'binary' || format === 'byte')
             return null;
         const brandName = formatToBrandTypeName(format, openApiType);
-        if (this.reservedNames.has(brandName))
+        if (this.emittedNames.has(brandName))
             return null;
         return brandName;
     }
-    mapInternal(schema, name, context, visited, indent) {
+    mapInternal(schema, name, context, visited, indent, spine) {
         if (isRefObject(schema)) {
             const refStr = schema.$ref;
             const refName = this.typeNameGenerator(refStr);
+            if (this.discriminatorRegistry) {
+                return this.translateRefThroughSeam(refStr, refName, context, visited, indent, spine);
+            }
             let resolved;
             try {
                 resolved = this.resolver.resolveSchema(schema);
@@ -104,9 +197,8 @@ export class SchemaMapper {
             if (resolved) {
                 const discInfo = this.resolveDiscriminatorInfo(resolved, refStr);
                 if (discInfo) {
-                    const expanded = this.mapInternal(resolved, undefined, context, visited, indent);
-                    expanded.tsType += ` & { ${quoteKey(discInfo.propertyName)}: '${discInfo.literalValue}' }`;
-                    return expanded;
+                    const expanded = this.mapInternal(resolved, undefined, context, visited, indent, undefined);
+                    return this.appendDiscriminatorLiteral(expanded, discInfo.propertyName, escapeStringLiteral(discInfo.literalValue));
                 }
             }
             return { tsType: refName, imports: [refName] };
@@ -122,7 +214,7 @@ export class SchemaMapper {
         // TODO: Remove deprecated nullable warning and handling when OpenAPI 3.1 support is complete
         // The 'nullable' property is deprecated in OpenAPI 3.1 in favor of type arrays like ["string", "null"]
         // This warning should be removed once full type array support is implemented
-        if (s.nullable === true && !this.nullableWarned) {
+        if (s.nullable === true && this.effectiveVersion !== '3.0' && !this.nullableWarned) {
             this.warnSink('Warning: \'nullable\' is deprecated in OpenAPI 3.1. Use \'type: ["string", "null"]\' instead.');
             this.nullableWarned = true;
         }
@@ -134,7 +226,7 @@ export class SchemaMapper {
             return { tsType, imports: [] };
         }
         if (s.allOf !== undefined && s.allOf.length > 0) {
-            const result = this.mapCombinator(s.allOf, '&', context, visited, indent);
+            const result = this.mapCombinator(s.allOf, '&', context, visited, indent, spine);
             if (s.nullable === true) {
                 return {
                     tsType: needsParens(result.tsType)
@@ -147,8 +239,8 @@ export class SchemaMapper {
         }
         if (s.oneOf !== undefined && s.oneOf.length > 0) {
             const result = s.discriminator
-                ? this.mapDiscriminatedUnion(s.oneOf, s.discriminator, context, visited, indent)
-                : this.mapCombinator(s.oneOf, '|', context, visited, indent);
+                ? this.mapDiscriminatedUnion(s.oneOf, s.discriminator, context, visited, indent, spine)
+                : this.mapCombinator(s.oneOf, '|', context, visited, indent, spine);
             if (s.nullable === true) {
                 return {
                     tsType: needsParens(result.tsType)
@@ -161,8 +253,8 @@ export class SchemaMapper {
         }
         if (s.anyOf !== undefined && s.anyOf.length > 0) {
             const result = s.discriminator
-                ? this.mapDiscriminatedUnion(s.anyOf, s.discriminator, context, visited, indent)
-                : this.mapCombinator(s.anyOf, '|', context, visited, indent);
+                ? this.mapDiscriminatedUnion(s.anyOf, s.discriminator, context, visited, indent, spine)
+                : this.mapCombinator(s.anyOf, '|', context, visited, indent, spine);
             if (s.nullable === true) {
                 return {
                     tsType: needsParens(result.tsType)
@@ -182,7 +274,7 @@ export class SchemaMapper {
             if (nonNull.length === 0) {
                 return { tsType: 'null', imports: [] };
             }
-            const baseResult = this.mapInternal({ ...s, type: nonNull[0] }, name, context, new Set(visited), indent);
+            const baseResult = this.mapInternal({ ...s, type: nonNull[0] }, name, context, new Set(visited), indent, spine);
             if (hasNull) {
                 return {
                     tsType: `${baseResult.tsType} | null`,
@@ -239,11 +331,96 @@ export class SchemaMapper {
             case 'array':
                 return this.mapArray(s, context, visited, indent);
             case 'object':
-                return this.mapObject(s, name, context, visited, indent);
+                return this.mapObject(s, name, context, visited, indent, spine);
             default:
                 return { tsType: 'unknown', imports: [] };
         }
     }
+    /**
+     * The single ref-translation seam (site 1). When the mapper carries a
+     * discriminator registry, EVERY `$ref` resolves through here:
+     *
+     * - a discriminator BASE becomes `{Base}Variant` at all sites except
+     *   inside a same-family member's own definition spine, where it stays
+     *   the bare base name (structural inheritance, no circularity — D1);
+     * - a same-family mapping target inside a spine becomes `Omit<M, 'P'>`,
+     *   falling back to inline expansion WITHOUT the literal when M is a
+     *   union, nullable, unnamed or non-object (D2/D4);
+     * - a mapping target at any other site is its bare name — the literal is
+     *   injected exactly once, at the target's own named definition.
+     */
+    translateRefThroughSeam(refStr, refName, context, visited, indent, spine) {
+        const registry = this.discriminatorRegistry;
+        const canonical = this.canonicalSchemasRef(refStr);
+        const baseFamily = registry.baseRefs.get(refStr) ?? registry.baseRefs.get(canonical);
+        if (baseFamily) {
+            if (spine && spine.familyId === baseFamily.familyId) {
+                return { tsType: baseFamily.baseTypeName, imports: [baseFamily.baseTypeName] };
+            }
+            return { tsType: baseFamily.variantUnionName, imports: [baseFamily.variantUnionName] };
+        }
+        const entry = registry.byRef.get(refStr) ?? registry.byRef.get(canonical);
+        if (entry) {
+            if (spine && spine.familyId === entry.familyId) {
+                return this.mapSameFamilySpineRef(entry, context, visited, indent);
+            }
+            if (entry.isNamed) {
+                return { tsType: entry.typeName, imports: [entry.typeName] };
+            }
+            // Unnamed target at a leaf site: expand inline and append the literal
+            // here — the target has no named definition to carry it.
+            const resolved = this.tryResolveRef(entry.refStr);
+            if (resolved) {
+                const expanded = this.mapInternal(resolved, undefined, context, visited, indent, spineForEntry(entry));
+                return this.appendDiscriminatorLiteral(expanded, entry.propertyName, entry.literalValue);
+            }
+            return { tsType: entry.typeName, imports: [entry.typeName] };
+        }
+        return { tsType: refName, imports: [refName] };
+    }
+    /**
+     * D2/D4 spine rule for a same-family `$ref`. `Omit<M, 'P'>` strips the
+     * sibling's own literal so the appender can re-add ours; the inline-strip
+     * fallback covers the cases where `Omit` would silently drop data
+     * (union target: `Omit<A|B,K>` drops variant props; nullable target:
+     * `Omit<M|null,K>` collapses to `{}`; unnamed/non-object target).
+     */
+    mapSameFamilySpineRef(entry, context, visited, indent) {
+        const resolved = this.tryResolveRef(entry.refStr);
+        if (entry.isNamed && !entry.isUnion && !entry.isNullable && this.isObjectIshSchema(resolved)) {
+            const key = `'${escapeStringLiteral(entry.propertyName)}'`;
+            return { tsType: `Omit<${entry.typeName}, ${key}>`, imports: [entry.typeName] };
+        }
+        if (resolved) {
+            return this.mapInternal(resolved, undefined, context, visited, indent, spineForEntry(entry));
+        }
+        return { tsType: entry.typeName, imports: [entry.typeName] };
+    }
+    /** Normalize a `#/components/schemas/…` ref to its canonically-encoded form (`a/b` ↔ `a~1b`). */
+    canonicalSchemasRef(refStr) {
+        if (!refStr.startsWith('#/components/schemas/'))
+            return refStr;
+        return `#/components/schemas/${encodePointerSegment(decodedLastRefSegment(refStr))}`;
+    }
+    tryResolveRef(refStr) {
+        try {
+            return this.resolver.resolveSchema({ $ref: refStr });
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isObjectIshSchema(s) {
+        if (!s)
+            return false;
+        if (s.type === 'object')
+            return true;
+        if (Array.isArray(s.type))
+            return s.type.includes('object');
+        if (s.allOf !== undefined && s.allOf.length > 0)
+            return true;
+        return s.type === undefined && s.properties !== undefined;
+    }
     resolveDiscriminatorInfo(schema, refStr) {
         const schemaName = this.typeNameGenerator(refStr);
         const target = this.discriminatorTargets.get(schemaName);
@@ -272,7 +449,7 @@ export class SchemaMapper {
         return values
             .map((v) => {
             if (typeof v === 'string')
-                return `'${v}'`;
+                return `'${escapeStringLiteral(v)}'`;
             if (typeof v === 'number')
                 return String(v);
             if (typeof v === 'boolean')
@@ -283,8 +460,8 @@ export class SchemaMapper {
         })
             .join(' | ');
     }
-    mapCombinator(schemas, kind, context, visited, indent) {
-        const results = schemas.map((s) => this.mapInternal(s, undefined, context, visited, indent));
+    mapCombinator(schemas, kind, context, visited, indent, spine) {
+        const results = schemas.map((s) => this.mapInternal(s, undefined, context, visited, indent, spine));
         const allImports = [];
         for (const r of results) {
             allImports.push(...r.imports);
@@ -298,20 +475,83 @@ export class SchemaMapper {
         });
         return { tsType: parts.join(separator), imports: allImports };
     }
-    mapDiscriminatedUnion(schemas, discriminator, context, visited, indent) {
+    mapDiscriminatedUnion(schemas, discriminator, context, visited, indent, spine) {
         const propertyName = discriminator.propertyName;
         const mapping = discriminator.mapping;
         const allImports = [];
         const parts = [];
         for (const schema of schemas) {
-            const discriminantValue = this.resolveDiscriminantValue(schema, propertyName, mapping);
-            const variantResult = this.mapInternal(schema, undefined, context, visited, indent);
+            if (this.discriminatorRegistry && isRefObject(schema)) {
+                const refStr = schema.$ref;
+                const canonical = this.canonicalSchemasRef(refStr);
+                const entry = this.discriminatorRegistry.byRef.get(refStr) ??
+                    this.discriminatorRegistry.byRef.get(canonical);
+                // D7: registered family variants are bare names — their named
+                // definitions already carry the literal exactly once. An explicit
+                // mapping defines the family's membership: when one exists, a
+                // oneOf member absent from it is foreign (wrapper + warn below);
+                // without a mapping every oneOf ref is an implicit member (D3).
+                const mappedRef = mapping !== undefined &&
+                    (Object.values(mapping).includes(refStr) || Object.values(mapping).includes(canonical));
+                if (entry && entry.propertyName === propertyName && (mapping === undefined || mappedRef)) {
+                    if (entry.isNamed) {
+                        allImports.push(entry.typeName);
+                        parts.push(entry.typeName);
+                        continue;
+                    }
+                    const resolved = this.tryResolveRef(entry.refStr);
+                    if (resolved) {
+                        const expanded = this.mapInternal(resolved, undefined, context, visited, indent, spineForEntry(entry));
+                        allImports.push(...expanded.imports);
+                        parts.push(this.appendDiscriminatorLiteral(expanded, propertyName, entry.literalValue).tsType);
+                        continue;
+                    }
+                }
+                // Foreign (non-family) ref: keep the literal wrapper and warn —
+                // nothing guarantees the target declares its own discriminant.
+                this.warnSink(`Warning: discriminated union member "${refStr}" is not registered in a discriminator family; keeping the inline '{ ${propertyName}: <literal> } &' wrapper.\n`);
+            }
+            const discriminantValue = this.discriminatorRegistry
+                ? this.resolveRegistryDiscriminantValue(schema, propertyName, mapping)
+                : this.resolveDiscriminantValue(schema, propertyName, mapping);
+            const variantResult = this.mapInternal(schema, undefined, context, visited, indent, this.discriminatorRegistry ? undefined : spine);
             allImports.push(...variantResult.imports);
             const quotedProp = quoteKey(propertyName);
             parts.push(`({ ${quotedProp}: '${discriminantValue}' } & ${variantResult.tsType})`);
         }
         return { tsType: parts.join(' | '), imports: allImports };
     }
+    /**
+     * D3 literal precedence for registry-mode wrapper literals (inline variant
+     * schemas and foreign refs): mapping key > own `const` on the discriminant
+     * property > single-value `enum` > RAW last ref segment (the runtime
+     * value, NOT the sanitized type name). Values are escaped for a
+     * single-quoted TS string.
+     */
+    resolveRegistryDiscriminantValue(schema, propertyName, mapping) {
+        if (mapping && isRefObject(schema)) {
+            const refStr = schema.$ref;
+            for (const [value, ref] of Object.entries(mapping)) {
+                if (ref === refStr)
+                    return escapeStringLiteral(value);
+            }
+        }
+        const resolved = isRefObject(schema)
+            ? this.tryResolveRef(schema.$ref)
+            : schema;
+        const propSchema = resolved?.properties?.[propertyName];
+        if (propSchema && propSchema.const !== undefined) {
+            return escapeStringLiteral(String(propSchema.const));
+        }
+        if (propSchema && propSchema.enum !== undefined && propSchema.enum.length === 1) {
+            return escapeStringLiteral(String(propSchema.enum[0]));
+        }
+        if (isRefObject(schema)) {
+            const refStr = schema.$ref;
+            return escapeStringLiteral(decodedLastRefSegment(refStr));
+        }
+        return 'unknown';
+    }
     resolveDiscriminantValue(schema, propertyName, mapping) {
         // Try explicit mapping first
         if (mapping && isRefObject(schema)) {
@@ -343,7 +583,7 @@ export class SchemaMapper {
                 imports: [],
             };
         }
-        const itemResult = this.mapInternal(schema.items, undefined, context, visited, indent);
+        const itemResult = this.mapInternal(schema.items, undefined, context, visited, indent, undefined);
         const tsType = isComplexType(itemResult.tsType)
             ? `Array<${itemResult.tsType}>`
             : `${itemResult.tsType}[]`;
@@ -378,7 +618,7 @@ export class SchemaMapper {
         const ind = indentBy(indentLevel);
         return block.split('\n').map((line) => `${ind}${line}`);
     }
-    mapObject(schema, name, context, visited, indent) {
+    mapObject(schema, name, context, visited, indent, spine) {
         const properties = schema.properties ?? {};
         const requiredSet = new Set(schema.required ?? []);
         const propNames = Object.keys(properties);
@@ -393,6 +633,19 @@ export class SchemaMapper {
                 return false;
             return true;
         });
+        // Inside a mapping target's own definition the discriminator property is
+        // supplied by the single literal append — an own redeclaration (const or
+        // enum) would intersect a conflicting literal and collapse to `never`.
+        if (spine) {
+            const ownDiscIndex = filteredPropNames.indexOf(spine.propertyName);
+            if (ownDiscIndex !== -1) {
+                const ownValue = ownDeclaredDiscriminant(properties[spine.propertyName]);
+                if (ownValue !== undefined && escapeStringLiteral(ownValue) !== spine.literalValue) {
+                    this.warnSink(`Warning: Discriminator mapping key "${spine.literalValue}" for property "${spine.propertyName}" conflicts with the variant's own declared value "${ownValue}"; the mapping key wins.\n`);
+                }
+                filteredPropNames.splice(ownDiscIndex, 1);
+            }
+        }
         const ownIndent = indentBy(indent);
         const memberIndent = indentBy(indent + 1);
         const memberLines = [];
@@ -407,7 +660,7 @@ export class SchemaMapper {
         }
         for (const propName of filteredPropNames) {
             const propSchema = properties[propName];
-            const propResult = this.mapInternal(propSchema, undefined, context, visited, indent + 1);
+            const propResult = this.mapInternal(propSchema, undefined, context, visited, indent + 1, undefined);
             allImports.push(...propResult.imports);
             memberLines.push(...this.renderPropertyJsDoc(propSchema, indent + 1));
             const optional = requiredSet.has(propName) ? '' : '?';
@@ -423,7 +676,7 @@ export class SchemaMapper {
             indexSignature = '[key: string]: unknown';
         }
         else if (additionalProps !== undefined && typeof additionalProps === 'object') {
-            const addPropResult = this.mapInternal(additionalProps, undefined, context, visited, indent + 1);
+            const addPropResult = this.mapInternal(additionalProps, undefined, context, visited, indent + 1, undefined);
             allImports.push(...addPropResult.imports);
             indexSignature = `[key: string]: ${addPropResult.tsType}`;
         }
@@ -471,7 +724,9 @@ export class SchemaMapper {
         }
         if (schema.nullable === true) {
             return {
-                tsType: `${result.tsType} | null`,
+                tsType: hasTopLevelUnion(result.tsType)
+                    ? `(${result.tsType}) | null`
+                    : `${result.tsType} | null`,
                 imports: result.imports,
             };
         }

package/dist/analyzer/types.d.ts

@@ -95,7 +95,9 @@ export interface AnalyzedSpec {
     /**
      * Section-1 component schema declarations as finished entries, in the
      * pre-refactor emission order: topologically sorted schemas first, then
-     * discriminator `{Base}Variant` unions in discovery order.
+     * one always-emitted `{Base}Variant` union per discriminator family
+     * (members = mapping values ∪ implicit oneOf/anyOf refs, sourced from the
+     * discriminator registry; collision-safe names) in family discovery order.
      */
     schemaTypes: TypeDeclaration[];
     /** Branded format types discovered during mapping, in discovery order. */
@@ -116,4 +118,9 @@ export interface AnalyzeOptions {
     resolver?: RefResolver;
     /** Method naming strategy; defaults to `'path-based'`. */
     strategy?: MethodNameStrategy;
+    /**
+     * Effective OpenAPI dialect, sourced from `VersionProfile.effective`.
+     * Omitted is treated as `'3.1'`.
+     */
+    effectiveVersion?: '3.0' | '3.1';
 }

package/dist/cli/impl.js

@@ -165,7 +165,10 @@ async function runOneTarget(target, context) {
     };
     const { preserveRefSiblings } = profile;
     context.process.stdout.write('Generating client...\n');
-    await generateFullOutput(doc, config, { preserveRefSiblings });
+    await generateFullOutput(doc, config, {
+        preserveRefSiblings,
+        effectiveVersion: profile.effective,
+    });
     context.process.stdout.write(`✅ Success! Generated client files:\n`);
     context.process.stdout.write(`  - ${target.outputDir}/contracts.ts\n`);
     context.process.stdout.write(`  - ${target.outputDir}/client.ts\n`);

package/dist/generator/method-generator.js

@@ -1,34 +1,50 @@
 import { sanitizeJsDocText } from '../utils/generator-helpers.js';
 import { getSuccessType, operationEmissions } from '../utils/operation-naming.js';
+/**
+ * A `?:` parameter may only be followed by other optional parameters — a
+ * required parameter after an optional one is a TS1016 compile error
+ * ("A required parameter cannot follow an optional parameter"). Optional
+ * parameters that precede a required one are therefore rendered as
+ * `name: T | undefined` instead of `name?: T`.
+ */
+function renderParams(specs) {
+    return specs
+        .map((spec, index) => {
+        if (!spec.isOptional) {
+            return `${spec.name}: ${spec.type}`;
+        }
+        const hasRequiredAfter = specs.slice(index + 1).some((s) => !s.isOptional);
+        if (hasRequiredAfter) {
+            return `${spec.name}: ${spec.type} | undefined`;
+        }
+        return `${spec.name}?: ${spec.type}`;
+    })
+        .join(', ');
+}
 function buildParameters(op) {
-    const params = [];
     const emissions = operationEmissions(op);
+    const specs = [];
     for (const param of op.pathParams) {
-        params.push(`${param.name}: string`);
+        specs.push({ name: param.name, type: 'string', isOptional: false });
     }
     if (emissions.query !== undefined) {
         const allOptional = op.queryParams.every((p) => !p.required);
-        const hasRequiredAfter = !!op.requestBody?.required || op.headerParams.some((p) => p.required);
-        if (allOptional && hasRequiredAfter) {
-            // All optional query params + required param after: use explicit undefined to avoid "required param cannot follow optional" error
-            params.push(`query: ${emissions.query} | undefined`);
-        }
-        else {
-            // Normal case: use optional notation
-            const optional = allOptional ? '?' : '';
-            params.push(`query${optional}: ${emissions.query}`);
-        }
+        specs.push({ name: 'query', type: emissions.query, isOptional: allOptional });
     }
     if (op.requestBody) {
-        const optional = op.requestBody.required ? '' : '?';
-        params.push(`body${optional}: ${emissions.body}`);
+        // A schema-less body has no named type; the literal keeps the rendered
+        // signature byte-identical to the previous template-literal fallback.
+        specs.push({
+            name: 'body',
+            type: emissions.body ?? 'undefined',
+            isOptional: !op.requestBody.required,
+        });
     }
     if (emissions.headers !== undefined) {
         const allOptional = op.headerParams.every((p) => !p.required);
-        const optional = allOptional ? '?' : '';
-        params.push(`headers${optional}: ${emissions.headers}`);
+        specs.push({ name: 'headers', type: emissions.headers, isOptional: allOptional });
     }
-    return params.join(', ');
+    return renderParams(specs);
 }
 function buildJsDoc(op) {
     const lines = [];

package/dist/pipeline.d.ts

@@ -4,6 +4,8 @@ import type { OpenAPIDocument } from './types/openapi.js';
 export interface GenerationOptions {
     /** When true, sibling properties alongside $ref are preserved (OpenAPI 3.1 behavior). */
     preserveRefSiblings?: boolean;
+    /** Effective OpenAPI dialect, sourced from `VersionProfile.effective`. */
+    effectiveVersion?: '3.0' | '3.1';
 }
 /**
  * Generate and write all output files to disk: builds the resolver, runs the

package/dist/pipeline.js

@@ -15,6 +15,7 @@ export async function generateFullOutput(doc, config, options) {
     const analyzed = analyze(doc, {
         resolver,
         strategy: config.methodNameStrategy ?? 'path-based',
+        effectiveVersion: options?.effectiveVersion,
     });
     const { contracts, client, index } = generateOutput(analyzed, config);
     await mkdir(config.outputDir, { recursive: true });

package/dist/utils/proxy.d.ts

@@ -3,4 +3,6 @@ export type LoadOptions = {
 };
 export declare function assertValidProxyUrl(url: string): void;
 export declare function hasProxyEnv(): boolean;
+/** True when the dynamic `import('undici')` failed because undici is not installed (Node: ERR_MODULE_NOT_FOUND; Bun: "Cannot find package" message). */
+export declare function isMissingUndiciError(err: unknown): boolean;
 export declare function fetchSpec(url: string, opts?: LoadOptions): Promise<Response>;