genoc 0.3.0 → 0.4.1

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,18 +103,33 @@ export class SchemaMapper {
     resolver;
     typeNameGenerator;
     discriminatorTargets;
-    reservedNames;
+    emittedNames;
+    discriminatorRegistry;
     brandedTypes = new Map();
-    static nullableWarned = false;
-    constructor(resolver, typeNameGenerator, discriminatorTargets, reservedNames) {
+    nullableWarned = false;
+    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 =
+            opts?.warnSink ??
+                ((message) => {
+                    process.stderr.write(message);
+                });
+        this.effectiveVersion = opts?.effectiveVersion;
     }
     getBrandedTypes() {
         return this.brandedTypes;
@@ -67,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() === '')
@@ -80,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);
@@ -98,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] };
@@ -116,11 +214,9 @@ 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 && !SchemaMapper.nullableWarned) {
-            // TODO: Replace with structured logging solution
-            // oxlint-disable-next-line no-console
-            console.warn('Warning: \'nullable\' is deprecated in OpenAPI 3.1. Use \'type: ["string", "null"]\' instead.');
-            SchemaMapper.nullableWarned = true;
+        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;
         }
         if (s.enum !== undefined && s.enum.length > 0) {
             let tsType = this.mapEnumValues(s.enum);
@@ -130,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)
@@ -143,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)
@@ -157,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)
@@ -178,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`,
@@ -235,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);
@@ -268,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')
@@ -279,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);
@@ -294,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)) {
@@ -339,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}[]`;
@@ -374,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);
@@ -389,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 = [];
@@ -403,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) ? '' : '?';
@@ -419,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}`;
         }
@@ -467,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

@@ -0,0 +1,126 @@
+import type { RefResolver } from '../parser/ref-resolver.js';
+import type { MethodNameStrategy } from '../types/client.js';
+import type { AnalyzedOperation } from './path-analyzer.js';
+/**
+ * Finished (render-ready) type declaration for the contracts file: the emitted
+ * type name, its complete definition statement, and an optional type-level
+ * JSDoc block rendered above it.
+ */
+export interface TypeDeclaration {
+    /** Emitted type name (rename-aware). */
+    name: string;
+    /** Complete definition statement, e.g. `export type User = { … };`. */
+    definition: string;
+    /** Type-level JSDoc block, when the source carries renderable metadata. */
+    jsDoc?: string;
+}
+/**
+ * Finished security scheme type declaration (contracts Section 1b): the
+ * collision-deduped `{Name}Auth` type name, the rendered object type text,
+ * and the description-only JSDoc block ('' when absent).
+ */
+export interface SecuritySchemeTypeDeclaration {
+    /** Emitted `{Name}Auth` type name (sanitized, numbered on collision). */
+    name: string;
+    /** Rendered object type text — the `securitySchemeToTsType` output. */
+    tsType: string;
+    /** Description JSDoc block; '' when the scheme carries no description. */
+    jsDoc: string;
+}
+/**
+ * Finished server variable type declaration (contracts Section 1c). Names
+ * are index-aware over ALL `doc.servers` — `ServerParams` when the document
+ * declares a single server, `Server{i}Params` otherwise — so servers without
+ * variables still occupy an index.
+ */
+export interface ServerTypeDeclaration {
+    name: string;
+    /** Server URL, emitted as the `/** Server: url *\/` comment when present. */
+    url?: string;
+    /** Finished interface body lines — variable JSDoc comments and property lines, indentation included. */
+    propertyLines: string[];
+}
+/** Branded format type discovered by the schema mapper during translation. */
+export interface BrandedTypeDeclaration {
+    name: string;
+    format: string;
+    baseType: string;
+}
+/**
+ * One multipart `FileInput` property fact from the ref-resolving walk of a
+ * multipart request body ($refs followed; a resolved `format: binary`
+ * property is a `file`/`file-array`, not a `field`).
+ */
+export interface FileUploadPropertyFact {
+    /** Property name in the multipart schema. */
+    name: string;
+    /** Whether the property is listed in the schema's `required` array. */
+    required: boolean;
+    /** `file` → `FileInput`, `file-array` → `FileInput[]`, `field` → `string`. */
+    kind: 'file' | 'file-array' | 'field';
+}
+/**
+ * Analyzed operation plus its finished translation results.
+ *
+ * The structural fields are the plain `AnalyzedOperation`; the added fields
+ * carry the real-mapper output the contracts renderer emits verbatim.
+ */
+export interface FinishedOperation extends AnalyzedOperation {
+    /**
+     * Finished contracts-file emission lines for this operation (Sections 2–4:
+     * query/header/body/response/error types, with JSDoc attached), in emission
+     * order. Assembled by `analyze()`; `renderContracts` spills them unchanged.
+     */
+    contractsLines: string[];
+    /**
+     * Multipart `FileInput` property facts from the ref-resolving walk of the
+     * request body schema (`$ref`s followed; a resolved `format: binary`
+     * property is a `file`/`file-array`, not a `field`). Present exactly when
+     * the operation has a multipart body WITH a schema — an empty array means a
+     * zero-property body; `undefined` means no multipart schema (no FormData
+     * emission). Sole fact source for the client generator's FormData appends.
+     */
+    fileUploadProperties?: FileUploadPropertyFact[];
+}
+/**
+ * Single-pass analysis model of an OpenAPI document — the ONLY input every
+ * generator renderer consumes. Renderers get the model plus config; they never
+ * touch the raw spec or a `RefResolver`.
+ */
+export interface AnalyzedSpec {
+    /** `doc.openapi` verbatim (e.g. `"3.1.0"`) — feeds generated file headers. */
+    specVersion: string;
+    /** Operations with structural facts and finished contracts emission lines. */
+    operations: FinishedOperation[];
+    /**
+     * Section-1 component schema declarations as finished entries, in the
+     * pre-refactor emission order: topologically sorted schemas first, then
+     * 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. */
+    brandedTypes: BrandedTypeDeclaration[];
+    /** Any operation has a multipart request body → contracts emits `FileInput`. */
+    hasFileUpload: boolean;
+    /**
+     * Finished security scheme type declarations (`{Name}Auth`), in spec key
+     * order. The `SecuritySchemes` union is emitted when more than one exists.
+     */
+    securitySchemeTypes: SecuritySchemeTypeDeclaration[];
+    /** Finished server variable interface declarations, in spec order. */
+    serverTypes: ServerTypeDeclaration[];
+}
+/** Options for `analyze()`. */
+export interface AnalyzeOptions {
+    /** Resolver for `$ref` pointers; defaults to a fresh `RefResolver(doc)`. */
+    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/app.d.ts

@@ -1,10 +1,12 @@
 interface Flags {
-    outputDir: string;
+    outputDir?: string;
     methodNameStrategy: 'path-based' | 'operationId' | 'operationId-with-fallback';
     specVersion?: string;
-    strictVersion: boolean;
+    strictVersion?: boolean;
     runtimeImportPath?: string;
     proxy?: string;
+    config?: string;
+    project?: string;
 }
 export type AppFlags = Flags;
 export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;