genoc 0.4.0 → 0.4.1

package/README.md

@@ -4,7 +4,7 @@ Generate TypeScript HTTP clients from OpenAPI 3.0 or 3.1 specifications.
 Generated code depends only on the tiny `genoc/runtime` module. Full type safety. Bring your own HTTP client.
 
 [![npm version](https://img.shields.io/npm/v/genoc)](https://www.npmjs.com/package/genoc)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.18.1-green)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/typescript-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
@@ -122,7 +122,7 @@ For the full example of catching and narrowing errors, see [Error handling](./do
 
 ## Requirements
 
-- Node.js 18 or later
+- Node.js 20.18.1 or later
 - OpenAPI 3.0.x or 3.1.x specification (JSON or YAML, file path or URL)
 
 ## License

package/dist/analyzer/analyze.js

@@ -1,42 +1,21 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { buildSchemaRenameMap, buildTypeJsDoc, sanitizeJsDocText, sanitizeTypeName, toPascalCase, } from '../utils/generator-helpers.js';
 import { operationEmissions, RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { buildDiscriminatorRegistry, renameAwareTypeName } from './discriminator-registry.js';
 import { analyzePathsDetailed } from './path-analyzer.js';
 import { SchemaMapper } from './schema-mapper.js';
-/**
- * If the schema is a $ref to a discriminated base type (or an array whose items
- * are), replace the type name with the {Base}Variant union type.
- */
-function substituteDiscriminatedType(tsType, schema, discriminatorInfo, renameMap) {
-    const refSchema = schema;
-    if (!refSchema || typeof refSchema !== 'object')
-        return tsType;
-    if (typeof refSchema.$ref === 'string') {
-        const rawName = refSchema.$ref.split('/').pop();
-        const schemaName = sanitizeTypeName(rawName);
-        if (schemaName && discriminatorInfo.has(schemaName)) {
-            const renamed = renameMap.get(rawName) ?? schemaName;
-            return tsType.replace(new RegExp(`\\b${renamed}\\b`, 'g'), `${renamed}Variant`);
-        }
-    }
-    if (refSchema.items && typeof refSchema.items === 'object') {
-        const items = refSchema.items;
-        if (typeof items.$ref === 'string') {
-            const rawName = items.$ref.split('/').pop();
-            const schemaName = sanitizeTypeName(rawName);
-            if (schemaName && discriminatorInfo.has(schemaName)) {
-                const renamed = renameMap.get(rawName) ?? schemaName;
-                return tsType.replace(new RegExp(`\\b${renamed}\\b`, 'g'), `${renamed}Variant`);
-            }
-        }
-    }
-    return tsType;
-}
 /**
  * Indent unit matching `INDENT_UNIT` in schema-mapper.ts (2 spaces, pinned by
  * the mapper's golden tests). Kept local to avoid modifying the mapper module.
  */
 const INDENT_UNIT = '  ';
+/**
+ * Shared warning channel for analyze() and the discriminator registry —
+ * the same sink the mapper defaults to.
+ */
+function writeWarning(message) {
+    process.stderr.write(message);
+}
 /**
  * Build a description-only type-level JSDoc comment for operation-derived
  * types (body / response). Returns '' when the description is absent or
@@ -301,45 +280,25 @@ export function analyze(doc, opts = {}) {
     const renamingTypeGenerator = (refString) => {
         const segments = refString.split('/');
         const rawSegment = segments[segments.length - 1] || 'unknown';
-        return renameMap.get(rawSegment) ?? sanitizeTypeName(rawSegment);
+        return renameAwareTypeName(renameMap, rawSegment);
     };
-    const discriminatorInfo = new Map();
-    if (doc.components?.schemas) {
-        for (const [name, schema] of Object.entries(doc.components.schemas)) {
-            const resolved = resolver.resolve(schema);
-            if (resolved.discriminator) {
-                const mapping = new Map();
-                if (resolved.discriminator.mapping) {
-                    for (const [key, ref] of Object.entries(resolved.discriminator.mapping)) {
-                        const rawTarget = ref.split('/').pop() || key;
-                        const renamedTarget = renameMap.get(rawTarget) ?? sanitizeTypeName(rawTarget);
-                        mapping.set(key, renamedTarget);
-                    }
-                }
-                discriminatorInfo.set(sanitizeTypeName(name), {
-                    rawName: name,
-                    propertyName: resolved.discriminator.propertyName,
-                    mapping,
-                });
-            }
-        }
-    }
-    const discriminatorTargets = new Map();
-    for (const [, info] of discriminatorInfo) {
-        for (const [mappingKey, schemaName] of info.mapping) {
-            discriminatorTargets.set(schemaName, {
-                propertyName: info.propertyName,
-                literalValue: mappingKey,
-            });
-        }
-    }
     const allSchemaNames = new Set();
     if (doc.components?.schemas) {
         for (const name of Object.keys(doc.components.schemas)) {
             allSchemaNames.add(renameMap.get(name) ?? sanitizeTypeName(name));
         }
     }
-    const mapper = new SchemaMapper(resolver, renamingTypeGenerator, discriminatorTargets, allSchemaNames);
+    // Family-aware discriminator registry (plan D5) — the single knowledge
+    // source for discriminator translation: the mapper's ref-translation seam
+    // consumes it, and the always-emitted `{Base}Variant` unions below are
+    // emitted from it.
+    const discriminatorRegistry = buildDiscriminatorRegistry(doc.components?.schemas, resolver, renameMap, allSchemaNames, writeWarning);
+    const mapper = new SchemaMapper(resolver, {
+        typeNameGenerator: renamingTypeGenerator,
+        emittedNames: allSchemaNames,
+        discriminatorRegistry,
+        effectiveVersion: opts?.effectiveVersion,
+    });
     // Section 1: Schema types
     const schemaEntries = [];
     if (doc.components?.schemas) {
@@ -362,17 +321,18 @@ export function analyze(doc, opts = {}) {
         definition: entry.definition,
         jsDoc: entry.jsDoc,
     }));
-    for (const [, info] of discriminatorInfo) {
-        const subtypeNames = Array.from(info.mapping.values());
-        if (subtypeNames.length === 0)
+    // Variant unions are emitted from the registry (D6): ALWAYS (mapping
+    // values ∪ implicit oneOf/anyOf refs, deduped by rename-aware name) and
+    // under collision-safe names so a user schema named `{Base}Variant`
+    // cannot collide with the generated union.
+    for (const family of discriminatorRegistry.families.values()) {
+        if (family.variantUnionMembers.length === 0)
             continue;
-        const unionType = subtypeNames.join(' | ');
-        const renamedBase = renameMap.get(info.rawName) ?? sanitizeTypeName(info.rawName);
         schemaTypes.push({
-            name: `${renamedBase}Variant`,
-            definition: `export type ${renamedBase}Variant = ${unionType};`,
+            name: family.variantUnionName,
+            definition: `export type ${family.variantUnionName} = ${family.variantUnionMembers.join(' | ')};`,
         });
-        allSchemaNames.add(`${renamedBase}Variant`);
+        allSchemaNames.add(family.variantUnionName);
     }
     const { operations: analyzedOperations, requestBodySchemas } = analyzePathsDetailed(doc, resolver, strategy);
     const operations = [];
@@ -461,10 +421,9 @@ export function analyze(doc, opts = {}) {
                     return 'StreamResponse';
                 }
                 if (r.schema) {
-                    const result = mapper.mapSchema(r.schema, undefined, 'response').tsType;
-                    const substituted = substituteDiscriminatedType(result, r.schema, discriminatorInfo, renameMap);
-                    r.finishedType = substituted;
-                    return substituted;
+                    const tsType = mapper.mapSchema(r.schema, undefined, 'response').tsType;
+                    r.finishedType = tsType;
+                    return tsType;
                 }
                 r.finishedType = r.isVoid ? 'void' : 'unknown';
                 return r.finishedType;

package/dist/analyzer/discriminator-registry.d.ts

@@ -0,0 +1,108 @@
+import type { RefResolver } from '../parser/ref-resolver.js';
+import type { SchemaObject } from '../types/openapi.js';
+/**
+ * Family-aware discriminator registry (plan D5) — the single knowledge source
+ * for discriminator families the mapper seam will translate through:
+ *
+ * - One record per discriminator family (a component schema declaring
+ *   `discriminator`), keyed by `familyId` (the base's raw component name).
+ * - Variant entries keyed by the FULL `$ref` string (mapping values are exact
+ *   ref strings) plus a derived rename-aware name index.
+ * - Literals are stored PRE-ESCAPED (D8: `'` and `\` only) so the mapper never
+ *   interpolates raw values into string literals.
+ * - Implicit variants (oneOf/anyOf `$ref` members absent from `mapping`) carry
+ *   the RAW last ref segment as their literal (D3 precedence: mapping key >
+ *   own `const` > single-value `enum` > raw segment).
+ *
+ * Field budget (D5): audited — every remaining field has a live consumer in
+ * production (seam / Variant-union emission) or in the registry unit tests.
+ * Rename-aware keying is mandatory: the name index goes through the same
+ * `buildSchemaRenameMap` machinery `analyze()` uses (see the past-bug note at
+ * schema-mapper.ts:75–78 — raw-name keying silently drops literal injection
+ * for renamed subtypes).
+ */
+/** Rename-aware type-name derivation — the exact expression `analyze()` wires
+ * into the mapper's `typeNameGenerator` (`renameMap.get(raw) ?? sanitized`).
+ * Single source of truth so registry name keys can never diverge from the
+ * names the mapper emits for the same `$ref`.
+ */
+export declare function renameAwareTypeName(renameMap: Map<string, string>, rawName: string): string;
+/**
+ * One discriminator variant target inside a family. Consumers: `propertyName`
+ * → literal append + `Omit<M, quoteKey(P)>` key + union wrapper;
+ * `literalValue` → the appended literal (pre-escaped — render as
+ * `'${literalValue}'`); `isNamed` → bare-name vs inline-expansion decision;
+ * `isUnion`/`isNullable` → spine `Omit` fallback decision (D2); `familyId` →
+ * same-family spine detection (D1/D2); `refStr` → identity match at the
+ * ref-translation seam; `typeName` → bare-name emission and the name index.
+ */
+export interface DiscriminatorVariantEntry {
+    /** Discriminator property name declared by the family base (e.g. `'$type'`). */
+    propertyName: string;
+    /** Pre-escaped literal (D8) — the mapping key, own const/enum value, or raw ref segment. No surrounding quotes. */
+    literalValue: string;
+    /** The rename-aware derived name is an emitted component schema (`∈ allSchemaNames`). */
+    isNamed: boolean;
+    /** The target's own resolved schema declares `oneOf`/`anyOf` (spine `Omit` would drop variant props — D2 fallback). */
+    isUnion: boolean;
+    /** The target's own resolved schema is nullable (3.0 `nullable: true` or a 3.1 type array containing `'null'`). */
+    isNullable: boolean;
+    /** Owning family id — the discriminator base's raw component name. */
+    familyId: string;
+    /** The exact `$ref` string that produced this entry (mapping value or oneOf/anyOf member ref). */
+    refStr: string;
+    /** Rename-aware type name for the ref (same derivation as the mapper's `typeNameGenerator`). */
+    typeName: string;
+}
+/**
+ * One discriminator family: a component schema declaring `discriminator`
+ * (`familyId` = its raw component name). Consumers: `baseRefStr` → base-ref
+ * detection at the seam (D1: `$ref` to the base emits `variantUnionName`
+ * outside same-family spines); `variantUnionName` / `variantUnionMembers` →
+ * the always-emit `{Base}Variant` union (D6); `entriesByRef` → family
+ * construction substrate and per-family lookups.
+ */
+export interface DiscriminatorFamily {
+    /** Raw component name of the discriminator base — the family id. */
+    familyId: string;
+    /** Rename-aware emitted type name of the base. */
+    baseTypeName: string;
+    /** Canonical ref of the base component (`#/components/schemas/<encoded key>`). */
+    baseRefStr: string;
+    /** Discriminator property name (`discriminator.propertyName`). */
+    propertyName: string;
+    /** Collision-safe `{Base}Variant` union name (D6 — via the reserved-name machinery). */
+    variantUnionName: string;
+    /** Union member type names (rename-aware, deduped; mapping order, then unmapped oneOf/anyOf refs). */
+    variantUnionMembers: string[];
+    /** Family entries keyed by the FULL `$ref` string (mapping value or oneOf/anyOf member ref). */
+    entriesByRef: Map<string, DiscriminatorVariantEntry>;
+}
+/**
+ * The discriminator registry built once per `analyze()` run. Consumers:
+ * `byRef`/`byName` for variant-target lookup at the ref-translation seam;
+ * `baseRefs` for D1 base-ref translation; `families` for same-family spine
+ * scoping (entry `familyId` → family) and the `{Base}Variant` union emission.
+ * Flat lookups are first-wins across families (spec order) — ambiguous
+ * cross-family targets stay reachable through their per-family maps.
+ */
+export interface DiscriminatorRegistry {
+    /** Families keyed by familyId (raw base component name), in spec order. */
+    families: Map<string, DiscriminatorFamily>;
+    /** Flat lookup: full refStr → entry (first-wins across families). */
+    byRef: Map<string, DiscriminatorVariantEntry>;
+    /** Flat lookup: rename-aware type name → entry (first-wins across families). */
+    byName: Map<string, DiscriminatorVariantEntry>;
+    /** Canonical base refStr → family, for D1 base-ref translation. */
+    baseRefs: Map<string, DiscriminatorFamily>;
+}
+/**
+ * Build the family-aware discriminator registry from the component schemas.
+ *
+ * Inputs must be the SAME `renameMap` / `allSchemaNames` `analyze()` derives
+ * (the rename-aware keying discipline) — pass `buildSchemaRenameMap`'s output
+ * and the emitted-name set, never a parallel sanitization. Pure with respect
+ * to the document: no mutation of the schemas; warnings (D3 mapping-key
+ * conflicts) go to `warnSink`.
+ */
+export declare function buildDiscriminatorRegistry(schemas: Record<string, SchemaObject> | undefined, resolver: RefResolver, renameMap: Map<string, string>, allSchemaNames: ReadonlySet<string>, warnSink?: (message: string) => void): DiscriminatorRegistry;

package/dist/analyzer/discriminator-registry.js

@@ -0,0 +1,209 @@
+import { buildSchemaRenameMap, sanitizeTypeName } from '../utils/generator-helpers.js';
+import { RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
+import { parseJsonPointer } from '../utils/url.js';
+/**
+ * Family-aware discriminator registry (plan D5) — the single knowledge source
+ * for discriminator families the mapper seam will translate through:
+ *
+ * - One record per discriminator family (a component schema declaring
+ *   `discriminator`), keyed by `familyId` (the base's raw component name).
+ * - Variant entries keyed by the FULL `$ref` string (mapping values are exact
+ *   ref strings) plus a derived rename-aware name index.
+ * - Literals are stored PRE-ESCAPED (D8: `'` and `\` only) so the mapper never
+ *   interpolates raw values into string literals.
+ * - Implicit variants (oneOf/anyOf `$ref` members absent from `mapping`) carry
+ *   the RAW last ref segment as their literal (D3 precedence: mapping key >
+ *   own `const` > single-value `enum` > raw segment).
+ *
+ * Field budget (D5): audited — every remaining field has a live consumer in
+ * production (seam / Variant-union emission) or in the registry unit tests.
+ * Rename-aware keying is mandatory: the name index goes through the same
+ * `buildSchemaRenameMap` machinery `analyze()` uses (see the past-bug note at
+ * schema-mapper.ts:75–78 — raw-name keying silently drops literal injection
+ * for renamed subtypes).
+ */
+/** Rename-aware type-name derivation — the exact expression `analyze()` wires
+ * into the mapper's `typeNameGenerator` (`renameMap.get(raw) ?? sanitized`).
+ * Single source of truth so registry name keys can never diverge from the
+ * names the mapper emits for the same `$ref`.
+ */
+export function renameAwareTypeName(renameMap, rawName) {
+    return renameMap.get(rawName) ?? sanitizeTypeName(rawName);
+}
+function isRefObject(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        !Array.isArray(obj) &&
+        '$ref' in obj);
+}
+/** Decode the last segment of a `$ref` string into its raw component key (`~1`/`~0` unescaped). */
+function rawRefSegment(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');
+}
+/**
+ * A discriminator variant's own declared literal on the discriminator
+ * property: `const` first, then a single-value `enum` (D3 steps 2–3).
+ * Returns the string form; multi-value enums and absent props yield nothing.
+ */
+function resolveOwnDiscriminatorLiteral(resolved, propertyName, resolver) {
+    if (!resolved)
+        return undefined;
+    let prop = resolved.properties?.[propertyName];
+    if (prop === undefined)
+        return undefined;
+    if (isRefObject(prop)) {
+        try {
+            prop = resolver.resolveSchema(prop);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (prop.const !== undefined)
+        return { value: String(prop.const), source: 'const' };
+    if (prop.enum !== undefined && prop.enum.length === 1) {
+        return { value: String(prop.enum[0]), source: 'enum' };
+    }
+    return undefined;
+}
+/** Resolve a mapping/oneOf ref target for flag facts; unresolvable refs degrade to undefined (mapper-style try/catch). */
+function resolveTargetSchema(resolver, refStr) {
+    try {
+        return resolver.resolveSchema({ $ref: refStr });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the family-aware discriminator registry from the component schemas.
+ *
+ * Inputs must be the SAME `renameMap` / `allSchemaNames` `analyze()` derives
+ * (the rename-aware keying discipline) — pass `buildSchemaRenameMap`'s output
+ * and the emitted-name set, never a parallel sanitization. Pure with respect
+ * to the document: no mutation of the schemas; warnings (D3 mapping-key
+ * conflicts) go to `warnSink`.
+ */
+export function buildDiscriminatorRegistry(schemas, resolver, renameMap, allSchemaNames, warnSink) {
+    const warn = warnSink ??
+        ((message) => {
+            process.stderr.write(message);
+        });
+    const registry = {
+        families: new Map(),
+        byRef: new Map(),
+        byName: new Map(),
+        baseRefs: new Map(),
+    };
+    if (!schemas)
+        return registry;
+    // Pass 1 — discover families; per family, register mapping entries first
+    // (D3: mapping key wins), then implicit oneOf/anyOf variants absent from
+    // the mapping (literal = own const > single-value enum > RAW ref segment).
+    for (const [name, schema] of Object.entries(schemas)) {
+        const resolved = resolver.resolve(schema);
+        const disc = resolved.discriminator;
+        if (!disc)
+            continue;
+        const familyId = name;
+        const family = {
+            familyId,
+            baseTypeName: renameAwareTypeName(renameMap, name),
+            baseRefStr: `#/components/schemas/${encodePointerSegment(name)}`,
+            propertyName: disc.propertyName,
+            variantUnionName: '',
+            variantUnionMembers: [],
+            entriesByRef: new Map(),
+        };
+        const mappedRefStrs = new Set();
+        if (disc.mapping) {
+            for (const [mappingKey, refStr] of Object.entries(disc.mapping)) {
+                if (mappedRefStrs.has(refStr))
+                    continue; // two keys → same target: first key wins
+                mappedRefStrs.add(refStr);
+                const target = resolveTargetSchema(resolver, refStr);
+                const own = resolveOwnDiscriminatorLiteral(target, disc.propertyName, resolver);
+                if (own !== undefined && own.value !== mappingKey) {
+                    warn(`Warning: Discriminator mapping key "${mappingKey}" for "${refStr}" conflicts with its own declared ${own.source} literal "${own.value}"; the mapping key wins.\n`);
+                }
+                const rawSegment = rawRefSegment(refStr);
+                const entry = {
+                    propertyName: disc.propertyName,
+                    literalValue: escapeStringLiteral(mappingKey),
+                    isNamed: allSchemaNames.has(renameAwareTypeName(renameMap, rawSegment)),
+                    isUnion: (target?.oneOf?.length ?? 0) > 0 || (target?.anyOf?.length ?? 0) > 0,
+                    isNullable: target?.nullable === true ||
+                        (Array.isArray(target?.type) ? target.type.includes('null') : false),
+                    familyId,
+                    refStr,
+                    typeName: renameAwareTypeName(renameMap, rawSegment),
+                };
+                family.entriesByRef.set(refStr, entry);
+            }
+        }
+        const implicitRefs = [];
+        for (const member of [...(resolved.oneOf ?? []), ...(resolved.anyOf ?? [])]) {
+            if (isRefObject(member))
+                implicitRefs.push(member.$ref);
+        }
+        for (const refStr of implicitRefs) {
+            if (mappedRefStrs.has(refStr))
+                continue; // already registered via mapping
+            const target = resolveTargetSchema(resolver, refStr);
+            const own = resolveOwnDiscriminatorLiteral(target, disc.propertyName, resolver);
+            const rawSegment = rawRefSegment(refStr);
+            const entry = {
+                propertyName: disc.propertyName,
+                // D3 fallback chain for unmapped variants: own const > single-value
+                // enum > RAW last ref segment (the runtime value, NOT the sanitized
+                // type name).
+                literalValue: escapeStringLiteral(own?.value ?? rawSegment),
+                isNamed: allSchemaNames.has(renameAwareTypeName(renameMap, rawSegment)),
+                isUnion: (target?.oneOf?.length ?? 0) > 0 || (target?.anyOf?.length ?? 0) > 0,
+                isNullable: target?.nullable === true ||
+                    (Array.isArray(target?.type) ? target.type.includes('null') : false),
+                familyId,
+                refStr,
+                typeName: renameAwareTypeName(renameMap, rawSegment),
+            };
+            family.entriesByRef.set(refStr, entry);
+        }
+        registry.families.set(familyId, family);
+    }
+    // Pass 2 — flat lookups + per-family name index + union members
+    // (mapping order, then unmapped oneOf/anyOf refs; deduped by refStr and
+    // by typeName — alias refs to one emitted name collapse).
+    for (const family of registry.families.values()) {
+        const memberNames = [];
+        const seenNames = new Set();
+        for (const [refStr, entry] of family.entriesByRef) {
+            if (!registry.byRef.has(refStr))
+                registry.byRef.set(refStr, entry);
+            if (!registry.byName.has(entry.typeName))
+                registry.byName.set(entry.typeName, entry);
+            if (!seenNames.has(entry.typeName)) {
+                seenNames.add(entry.typeName);
+                memberNames.push(entry.typeName);
+            }
+        }
+        family.variantUnionMembers = memberNames;
+        registry.baseRefs.set(family.baseRefStr, family);
+    }
+    // Pass 3 — collision-safe `{Base}Variant` union names (D6): candidates go
+    // through the SAME reserved-name machinery as schemas, seeded with every
+    // emitted schema name, so a user schema literally named `ThingVariant`
+    // forces the generated union to `ThingVariantModel` (no duplicate export).
+    const unionCandidates = [...registry.families.values()].map((f) => `${f.baseTypeName}Variant`);
+    const unionRenames = buildSchemaRenameMap(unionCandidates, new Set([...RESERVED_TYPE_NAMES, ...allSchemaNames]));
+    for (const family of registry.families.values()) {
+        const candidate = `${family.baseTypeName}Variant`;
+        family.variantUnionName = unionRenames.get(candidate) ?? candidate;
+    }
+    return registry;
+}

package/dist/analyzer/schema-mapper.d.ts

@@ -1,10 +1,32 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import type { TypeMappingResult } from '../types/contracts.js';
 import type { SchemaObject, ReferenceObject } from '../types/openapi.js';
+import type { DiscriminatorRegistry } from './discriminator-registry.js';
 /**
  * Callback to customize how $ref strings are converted to TypeScript type names.
  */
 export type TypeNameGenerator = (refString: string) => string;
+/**
+ * Optional construction dependencies for {@link SchemaMapper}. Every field is
+ * optional and defaults exactly as the previous positional constructor
+ * parameters did.
+ */
+export interface SchemaMapperOptions {
+    typeNameGenerator?: TypeNameGenerator;
+    discriminatorTargets?: Map<string, {
+        propertyName: string;
+        literalValue: string;
+    }>;
+    emittedNames?: Set<string>;
+    warnSink?: (message: string) => void;
+    discriminatorRegistry?: DiscriminatorRegistry;
+    /**
+     * Effective OpenAPI dialect. Omitted is treated as '3.1' (the nullable
+     * deprecation warning fires). Pass '3.0' to silence it — 'nullable' is the
+     * correct mechanism in 3.0.
+     */
+    effectiveVersion?: '3.0' | '3.1';
+}
 /**
  * SchemaMapper converts OpenAPI 3.1 Schema Objects to TypeScript type strings.
  *
@@ -15,14 +37,13 @@ export declare class SchemaMapper {
     private readonly resolver;
     private readonly typeNameGenerator;
     private readonly discriminatorTargets;
-    private readonly reservedNames;
+    private readonly emittedNames;
+    private readonly discriminatorRegistry;
     private readonly brandedTypes;
     private nullableWarned;
     private readonly warnSink;
-    constructor(resolver: RefResolver, typeNameGenerator?: TypeNameGenerator, discriminatorTargets?: Map<string, {
-        propertyName: string;
-        literalValue: string;
-    }>, reservedNames?: Set<string>, warnSink?: (message: string) => void);
+    private readonly effectiveVersion;
+    constructor(resolver: RefResolver, opts?: SchemaMapperOptions);
     getBrandedTypes(): Map<string, {
         name: string;
         format: string;
@@ -37,12 +58,52 @@ export declare class SchemaMapper {
      * @returns TypeMappingResult with tsType string and imports array
      */
     mapSchema(schema: SchemaObject | ReferenceObject, name?: string, context?: 'request' | 'response'): TypeMappingResult;
+    /**
+     * 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).
+     */
+    private appendDiscriminatorLiteral;
     private getBrandTypeName;
     private mapInternal;
+    /**
+     * 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.
+     */
+    private translateRefThroughSeam;
+    /**
+     * 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).
+     */
+    private mapSameFamilySpineRef;
+    /** Normalize a `#/components/schemas/…` ref to its canonically-encoded form (`a/b` ↔ `a~1b`). */
+    private canonicalSchemasRef;
+    private tryResolveRef;
+    private isObjectIshSchema;
     private resolveDiscriminatorInfo;
     private mapEnumValues;
     private mapCombinator;
     private mapDiscriminatedUnion;
+    /**
+     * 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.
+     */
+    private resolveRegistryDiscriminantValue;
     private resolveDiscriminantValue;
     private mapArray;
     /**

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/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>;

package/dist/utils/proxy.js

@@ -48,6 +48,16 @@ export function hasProxyEnv() {
         process.env.HTTPS_PROXY ||
         process.env.https_proxy);
 }
+/** True when the dynamic `import('undici')` failed because undici is not installed (Node: ERR_MODULE_NOT_FOUND; Bun: "Cannot find package" message). */
+export function isMissingUndiciError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    if (code === 'ERR_MODULE_NOT_FOUND')
+        return true;
+    return /Cannot find (?:module|package) ['"]?undici/.test(err.message);
+}
+const MISSING_UNDICI_MESSAGE = "Proxy support requires the 'undici' package. Install it: npm install undici";
 export async function fetchSpec(url, opts) {
     if (opts?.proxy) {
         assertValidProxyUrl(opts.proxy);
@@ -59,6 +69,9 @@ export async function fetchSpec(url, opts) {
             }));
         }
         catch (err) {
+            if (isMissingUndiciError(err)) {
+                throw new Error(MISSING_UNDICI_MESSAGE);
+            }
             throw new Error(`Failed to fetch spec from URL via proxy ${redacted}: ${describeFetchError(err)}`, {
                 cause: err,
             });
@@ -72,6 +85,9 @@ export async function fetchSpec(url, opts) {
             }));
         }
         catch (err) {
+            if (isMissingUndiciError(err)) {
+                throw new Error(MISSING_UNDICI_MESSAGE);
+            }
             throw new Error(`Failed to fetch spec from URL via proxy env: ${describeFetchError(err)}`, {
                 cause: err,
             });

package/dist/utils/string.d.ts

@@ -26,6 +26,13 @@ export declare function isReservedWord(str: string): boolean;
  * @returns Safe TypeScript identifier
  */
 export declare function sanitizeIdentifier(str: string): string;
+/**
+ * Escape a value for interpolation inside a TypeScript single-quoted string
+ * literal (backslash first, then the quote itself)
+ * @param value The raw string value
+ * @returns The value with `\` and `'` escaped
+ */
+export declare function escapeStringLiteral(value: string): string;
 /**
  * Quote a key if needed for TypeScript object literals
  * @param key The key to potentially quote

package/dist/utils/string.js

@@ -163,6 +163,15 @@ export function sanitizeIdentifier(str) {
     }
     return final;
 }
+/**
+ * Escape a value for interpolation inside a TypeScript single-quoted string
+ * literal (backslash first, then the quote itself)
+ * @param value The raw string value
+ * @returns The value with `\` and `'` escaped
+ */
+export function escapeStringLiteral(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
 /**
  * Quote a key if needed for TypeScript object literals
  * @param key The key to potentially quote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genoc",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Generate typed HTTP clients from OpenAPI 3.0 / 3.1 specifications",
   "keywords": [
     "client",
@@ -43,19 +43,27 @@
   "dependencies": {
     "@stricli/core": "^1.2.6",
     "lilconfig": "^3.1.3",
-    "undici": "^6.13.0",
     "yaml": "^2.2.2",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.0",
-    "@types/node": "^25.6.0",
-    "oxfmt": "^0.48.0",
-    "oxlint": "^1.63.0",
+    "@changesets/cli": "^3.0.3",
+    "@types/node": "^26.6.2",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "undici": "^8",
+    "vitest": "^5.0.1"
+  },
+  "peerDependencies": {
+    "undici": "^6.13.0 || ^7 || ^8"
+  },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    }
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.18.1"
   }
 }