genoc 0.3.0 → 0.4.1

package/dist/analyzer/analyze.js

@@ -0,0 +1,493 @@
+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';
+/**
+ * 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
+ * whitespace-only so callers can skip emission entirely.
+ */
+export function buildDescriptionJsDoc(description) {
+    if (description === undefined)
+        return '';
+    const sanitized = sanitizeJsDocText(description);
+    return sanitized === '' ? '' : `/** ${sanitized} */`;
+}
+/**
+ * Prefix a type definition with its JSDoc block (single- or multi-line),
+ * keeping the comment directly above the `export type` line.
+ */
+function attachTypeJsDoc(jsDoc, definition) {
+    return jsDoc === '' ? definition : `${jsDoc}\n${definition}`;
+}
+/**
+ * Indent every line of a JSDoc block by one indent unit so property comments
+ * line up exactly with their property line (mapper indentation contract).
+ */
+function indentJsDocBlock(jsDoc) {
+    return jsDoc.split('\n').map((line) => `${INDENT_UNIT}${line}`);
+}
+/**
+ * Build the JSDoc block for a query/header parameter property using the
+ * pinned parameter merge rule: parameter-level description / deprecated /
+ * example win over the schema's; default, title and examples come from the
+ * schema only (carried by the spread).
+ */
+function buildParamPropertyJsDoc(param, schema) {
+    return buildTypeJsDoc({
+        ...schema,
+        description: param.description ?? schema.description,
+        deprecated: param.deprecated === true || schema.deprecated === true,
+        example: param.example ?? schema.example,
+    });
+}
+/**
+ * Render a `${prefix}Query` / `${prefix}Headers` object body in the mapper's
+ * multi-line format with per-property JSDoc from the parameter merge rule.
+ */
+function buildParamTypeBody(params, mapper) {
+    const lines = [];
+    for (const param of params) {
+        const paramSchema = param.schema ?? { type: 'string' };
+        const result = mapper.mapSchema(paramSchema);
+        const optional = param.required ? '' : '?';
+        const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `"${param.name}"`;
+        const jsDoc = buildParamPropertyJsDoc(param, paramSchema);
+        if (jsDoc !== '') {
+            lines.push(...indentJsDocBlock(jsDoc));
+        }
+        lines.push(`${INDENT_UNIT}${key}${optional}: ${result.tsType};`);
+    }
+    return `{\n${lines.join('\n')}\n}`;
+}
+/**
+ * Sort ContractEntry list so that referenced types appear before referrers.
+ * Uses DFS-based topological sort; cycles are broken by skipping.
+ */
+function topologicalSort(entries, allNames) {
+    if (entries.length <= 1)
+        return entries;
+    const nameToIndex = new Map();
+    entries.forEach((e, i) => nameToIndex.set(e.name, i));
+    const graph = new Map();
+    for (let i = 0; i < entries.length; i++) {
+        const deps = new Set();
+        const def = entries[i].definition;
+        for (const name of allNames) {
+            if (name === entries[i].name)
+                continue;
+            if (new RegExp(`\\b${name}\\b`).test(def)) {
+                const depIdx = nameToIndex.get(name);
+                if (depIdx !== undefined) {
+                    deps.add(depIdx);
+                }
+            }
+        }
+        graph.set(i, deps);
+    }
+    const sorted = [];
+    const visited = new Set();
+    const inStack = new Set();
+    function visit(idx) {
+        if (visited.has(idx))
+            return;
+        if (inStack.has(idx))
+            return;
+        inStack.add(idx);
+        const deps = graph.get(idx);
+        if (deps) {
+            for (const dep of deps) {
+                visit(dep);
+            }
+        }
+        inStack.delete(idx);
+        visited.add(idx);
+        sorted.push(entries[idx]);
+    }
+    for (let i = 0; i < entries.length; i++) {
+        visit(i);
+    }
+    return sorted;
+}
+function securitySchemeToTsType(scheme) {
+    const parts = [`type: "${scheme.type}"`];
+    if (scheme.description) {
+        parts.push(`description: "${scheme.description}"`);
+    }
+    if (scheme.type === 'apiKey') {
+        if (scheme.name)
+            parts.push(`name: "${scheme.name}"`);
+        if (scheme.in)
+            parts.push(`in: "${scheme.in}"`);
+    }
+    if (scheme.type === 'http') {
+        if (scheme.scheme)
+            parts.push(`scheme: "${scheme.scheme}"`);
+        if (scheme.bearerFormat)
+            parts.push(`bearerFormat: "${scheme.bearerFormat}"`);
+    }
+    if (scheme.type === 'oauth2' && scheme.flows) {
+        const flowParts = [];
+        const flows = scheme.flows;
+        if (flows.implicit) {
+            flowParts.push(`implicit: ${oAuth2FlowToTs(flows.implicit, true)}`);
+        }
+        if (flows.password) {
+            flowParts.push(`password: ${oAuth2FlowToTs(flows.password, false)}`);
+        }
+        if (flows.clientCredentials) {
+            flowParts.push(`clientCredentials: ${oAuth2FlowToTs(flows.clientCredentials, false)}`);
+        }
+        if (flows.authorizationCode) {
+            flowParts.push(`authorizationCode: ${oAuth2FlowToTs(flows.authorizationCode, true)}`);
+        }
+        parts.push(`flows: { ${flowParts.join('; ')} }`);
+    }
+    if (scheme.type === 'openIdConnect' && scheme.openIdConnectUrl) {
+        parts.push(`openIdConnectUrl: "${scheme.openIdConnectUrl}"`);
+    }
+    return `{ ${parts.join('; ')} }`;
+}
+function oAuth2FlowToTs(flow, hasAuthUrl) {
+    const entries = [];
+    if (hasAuthUrl && flow.authorizationUrl) {
+        entries.push(`authorizationUrl: "${flow.authorizationUrl}"`);
+    }
+    if (flow.tokenUrl) {
+        entries.push(`tokenUrl: "${flow.tokenUrl}"`);
+    }
+    if (flow.refreshUrl) {
+        entries.push(`refreshUrl: "${flow.refreshUrl}"`);
+    }
+    const scopeEntries = Object.entries(flow.scopes)
+        .map(([k, v]) => `"${k}": "${v}"`)
+        .join('; ');
+    entries.push(`scopes: { ${scopeEntries} }`);
+    return `{ ${entries.join('; ')} }`;
+}
+/**
+ * Translate `components.securitySchemes` into finished `{Name}Auth` type
+ * declarations: sanitize + PascalCase the key, number collisions, render the
+ * object type text and the description JSDoc. Spec key order preserved.
+ */
+function analyzeSecuritySchemes(securitySchemes) {
+    const entries = [];
+    if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
+        return entries;
+    }
+    const usedSecurityTypeNames = new Set();
+    for (const [schemeName, scheme] of Object.entries(securitySchemes)) {
+        const baseTypeName = `${sanitizeTypeName(toPascalCase(schemeName))}Auth`;
+        let typeName = baseTypeName;
+        let n = 2;
+        while (usedSecurityTypeNames.has(typeName)) {
+            typeName = `${baseTypeName}${n}`;
+            n += 1;
+        }
+        usedSecurityTypeNames.add(typeName);
+        entries.push({
+            name: typeName,
+            tsType: securitySchemeToTsType(scheme),
+            jsDoc: buildDescriptionJsDoc(scheme.description),
+        });
+    }
+    return entries;
+}
+/**
+ * Translate `doc.servers` into finished server variable interface
+ * declarations, one per server that declares variables. Names are index-aware
+ * over ALL servers (`ServerParams` for a single-server document,
+ * `Server{i}Params` otherwise), so variable-less servers still occupy an
+ * index. Property lines carry their JSDoc and indentation.
+ */
+function analyzeServers(servers) {
+    const entries = [];
+    if (!servers)
+        return entries;
+    for (let serverIdx = 0; serverIdx < servers.length; serverIdx++) {
+        const server = servers[serverIdx];
+        if (!server.variables || Object.keys(server.variables).length === 0) {
+            continue;
+        }
+        const typeName = servers.length === 1 ? 'ServerParams' : `Server${serverIdx + 1}Params`;
+        const props = [];
+        for (const [varName, variable] of Object.entries(server.variables)) {
+            const sv = variable;
+            const jsDocParts = [];
+            if (sv.description) {
+                const description = sanitizeJsDocText(sv.description);
+                if (description !== '') {
+                    jsDocParts.push(description);
+                }
+            }
+            if (sv.default !== undefined) {
+                jsDocParts.push(`@default ${sanitizeJsDocText(String(sv.default))}`);
+            }
+            let tsType;
+            if (sv.enum && sv.enum.length > 0) {
+                tsType = sv.enum.map((v) => `"${v}"`).join(' | ');
+            }
+            else {
+                tsType = 'string';
+            }
+            const jsDoc = jsDocParts.length > 0 ? `  /** ${jsDocParts.join(' ')} */` : null;
+            if (jsDoc) {
+                props.push(jsDoc);
+            }
+            props.push(`  ${varName}: ${tsType};`);
+        }
+        entries.push({
+            name: typeName,
+            url: server.url,
+            propertyLines: props,
+        });
+    }
+    return entries;
+}
+/**
+ * Analyze an OpenAPI document into the finished model every renderer consumes:
+ * schema→TS-type translation (rename machinery, discriminator discovery, the
+ * schema mapper) runs here exactly once, producing render-ready type text.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param opts - Optional resolver override and method naming strategy
+ * @returns The AnalyzedSpec model consumed by all generators
+ */
+export function analyze(doc, opts = {}) {
+    const resolver = opts.resolver ?? new RefResolver(doc);
+    const strategy = opts.strategy ?? 'path-based';
+    const schemaNameList = doc.components?.schemas ? Object.keys(doc.components.schemas) : [];
+    const renameMap = buildSchemaRenameMap(schemaNameList, RESERVED_TYPE_NAMES);
+    for (const [original, renamed] of renameMap) {
+        // TODO: Replace with structured logging solution
+        // oxlint-disable-next-line no-console
+        console.warn(`Warning: Schema "${original}" collides with a built-in type or another schema and was renamed to "${renamed}".`);
+    }
+    const renamingTypeGenerator = (refString) => {
+        const segments = refString.split('/');
+        const rawSegment = segments[segments.length - 1] || 'unknown';
+        return renameAwareTypeName(renameMap, rawSegment);
+    };
+    const allSchemaNames = new Set();
+    if (doc.components?.schemas) {
+        for (const name of Object.keys(doc.components.schemas)) {
+            allSchemaNames.add(renameMap.get(name) ?? sanitizeTypeName(name));
+        }
+    }
+    // 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) {
+        for (const [name, schema] of Object.entries(doc.components.schemas)) {
+            const renamedName = renameMap.get(name) ?? sanitizeTypeName(name);
+            const result = mapper.mapSchema(schema, renamedName);
+            const resolved = resolver.resolve(schema);
+            const definition = `export type ${renamedName} = ${result.tsType};`;
+            schemaEntries.push({
+                name: renamedName,
+                kind: 'type',
+                definition,
+                jsDoc: buildTypeJsDoc(resolved) || undefined,
+            });
+        }
+    }
+    const sortedSchemas = topologicalSort(schemaEntries, allSchemaNames);
+    const schemaTypes = sortedSchemas.map((entry) => ({
+        name: entry.name,
+        definition: entry.definition,
+        jsDoc: entry.jsDoc,
+    }));
+    // 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;
+        schemaTypes.push({
+            name: family.variantUnionName,
+            definition: `export type ${family.variantUnionName} = ${family.variantUnionMembers.join(' | ')};`,
+        });
+        allSchemaNames.add(family.variantUnionName);
+    }
+    const { operations: analyzedOperations, requestBodySchemas } = analyzePathsDetailed(doc, resolver, strategy);
+    const operations = [];
+    for (const op of analyzedOperations) {
+        operations.push({
+            ...op,
+            contractsLines: [],
+        });
+    }
+    const hasFileUpload = operations.some((op) => op.requestBody?.isMultipart);
+    // Sections 2-4: Operation-derived types. Presence decisions and type
+    // names come from the emission inventory (operationEmissions); the
+    // finished lines are assembled here so renderers never re-translate.
+    for (let opIdx = 0; opIdx < operations.length; opIdx++) {
+        const op = operations[opIdx];
+        // Raw request body schema, parallel to `operations` (analyzer-internal
+        // translation input; presence mirrors requestBody.hasSchema).
+        const rawBodySchema = requestBodySchemas[opIdx];
+        const emissions = operationEmissions(op);
+        const opLines = [];
+        // Section 2: Query parameter types
+        if (emissions.query) {
+            opLines.push(`export type ${emissions.query} = ${buildParamTypeBody(op.queryParams, mapper)};`);
+        }
+        // Section 2b: Header parameter types
+        if (emissions.headers) {
+            opLines.push(`export type ${emissions.headers} = ${buildParamTypeBody(op.headerParams, mapper)};`);
+        }
+        // Section 3: Request body types
+        const bodyJsDoc = op.requestBody ? buildDescriptionJsDoc(op.requestBody.description) : '';
+        if (op.requestBody?.isMultipart && rawBodySchema !== undefined) {
+            const schema = resolver.resolveSchema(rawBodySchema);
+            const requiredSet = new Set(schema.required ?? []);
+            const propLines = [];
+            const fileUploadProperties = [];
+            for (const [name, propSchema] of Object.entries(schema.properties ?? {})) {
+                const resolved = resolver.resolveSchema(propSchema);
+                const optional = requiredSet.has(name) ? '' : '?';
+                let tsType;
+                let kind;
+                if (resolved.format === 'binary') {
+                    tsType = 'FileInput';
+                    kind = 'file';
+                }
+                else if (resolved.type === 'array' && resolved.items?.format === 'binary') {
+                    tsType = 'FileInput[]';
+                    kind = 'file-array';
+                }
+                else {
+                    tsType = 'string';
+                    kind = 'field';
+                }
+                fileUploadProperties.push({ name, required: requiredSet.has(name), kind });
+                const jsDoc = buildTypeJsDoc(resolved);
+                if (jsDoc !== '') {
+                    propLines.push(...indentJsDocBlock(jsDoc));
+                }
+                propLines.push(`${INDENT_UNIT}${name}${optional}: ${tsType};`);
+            }
+            op.fileUploadProperties = fileUploadProperties;
+            if (propLines.length > 0) {
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${emissions.body} = {\n${propLines.join('\n')}\n};`));
+            }
+            else {
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${emissions.body} = Record<string, never>;`));
+            }
+        }
+        else if (op.requestBody?.hasSchema && rawBodySchema !== undefined) {
+            if (op.requestBody.isBinary) {
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${emissions.body} = Blob;`));
+            }
+            else {
+                const result = mapper.mapSchema(rawBodySchema, undefined, 'request');
+                opLines.push(attachTypeJsDoc(bodyJsDoc, `export type ${emissions.body} = ${result.tsType};`));
+            }
+        }
+        // Section 4: Response types
+        const successResponses = op.responses.filter((r) => r.isSuccess);
+        const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
+        const defaultResponse = op.responses.find((r) => !r.isSuccess && r.statusCode === 'default');
+        // Success type
+        if (emissions.response) {
+            const types = successResponses.map((r) => {
+                if (r.isBinary) {
+                    r.finishedType = 'StreamResponse';
+                    return 'StreamResponse';
+                }
+                if (r.schema) {
+                    const tsType = mapper.mapSchema(r.schema, undefined, 'response').tsType;
+                    r.finishedType = tsType;
+                    return tsType;
+                }
+                r.finishedType = r.isVoid ? 'void' : 'unknown';
+                return r.finishedType;
+            });
+            const successType = types.length === 1 ? types[0] : types.join(' | ');
+            // Type-level JSDoc from the lowest-numbered 2xx response (the analyzer
+            // returns success responses in ascending status order).
+            const responseJsDoc = buildDescriptionJsDoc(successResponses[0].description);
+            opLines.push(attachTypeJsDoc(responseJsDoc, `export type ${emissions.response} = ${successType};`));
+        }
+        // Error types per status (inventory pairs 1:1 with errorResponses by
+        // construction: same filter, same order)
+        for (let i = 0; i < errorResponses.length; i++) {
+            const err = errorResponses[i];
+            const errorTypeName = emissions.statusErrors[i].name;
+            let errorTsType;
+            if (err.isBinary) {
+                errorTsType = 'StreamResponse';
+            }
+            else if (err.schema) {
+                errorTsType = mapper.mapSchema(err.schema, undefined, 'response').tsType;
+            }
+            else {
+                errorTsType = 'unknown';
+            }
+            err.finishedType = errorTsType;
+            opLines.push(`export type ${errorTypeName} = ${errorTsType};`);
+        }
+        // Default response error type
+        if (emissions.defaultError) {
+            let defaultTsType;
+            if (defaultResponse?.isBinary) {
+                defaultTsType = 'StreamResponse';
+            }
+            else if (defaultResponse?.schema) {
+                defaultTsType = mapper.mapSchema(defaultResponse.schema, undefined, 'response').tsType;
+            }
+            else {
+                defaultTsType = 'unknown';
+            }
+            if (defaultResponse) {
+                defaultResponse.finishedType = defaultTsType;
+            }
+            opLines.push(`export type ${emissions.defaultError} = ${defaultTsType};`);
+        }
+        // Error union
+        if (emissions.errorsUnion) {
+            const unionParts = emissions.statusErrors.map((e) => `ApiError<${e.status}, ${e.name}>`);
+            opLines.push(`export type ${emissions.errorsUnion} = ${unionParts.join(' | ')};`);
+        }
+        op.contractsLines = opLines;
+    }
+    // Branded types snapshot after every mapSchema call has run, mirroring the
+    // pre-refactor read position at the end of generateContracts.
+    const brandedTypes = Array.from(mapper.getBrandedTypes().values());
+    const securitySchemeTypes = analyzeSecuritySchemes(doc.components?.securitySchemes);
+    const serverTypes = analyzeServers(doc.servers);
+    return {
+        specVersion: doc.openapi,
+        operations,
+        schemaTypes,
+        brandedTypes,
+        hasFileUpload,
+        securitySchemeTypes,
+        serverTypes,
+    };
+}

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;