openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/api/discriminator-scan.ts

@@ -0,0 +1,272 @@
+import type { Logger } from "../application/ports/logger.js";
+import type {
+  DiscriminatorObject,
+  GeneratorOptions,
+  OpenAPI3,
+  ReferenceObject,
+  SchemaObject,
+} from "../types.js";
+import { defaultLogger } from "./default-ports.js";
+import { addEnumProperty, type EnumPatch } from "./discriminator-enum.js";
+import { resolveDocumentRef, walkDocument } from "./document-refs.js";
+import { createRef } from "./legacy-utils.js";
+
+/**
+ * The inherited discriminator pre-pass. It finds every discriminator in the bundled document and
+ * patches the mapped schemas in place with a required enum property, so that TypeScript can narrow
+ * the generated union. The behavior and the warning text match the original `scanDiscriminators`.
+ */
+
+type DiscriminatorMapping = Record<string, { inferred?: string; defined?: string[] }>;
+
+/** How to scan; `fixesValueConflicts` is the `discriminator-values` fix (ADR-021, roadmap R12). */
+export interface DiscriminatorScanOptions {
+  readonly silent: boolean;
+  readonly logger: Logger;
+  readonly fixesValueConflicts: boolean;
+}
+
+/** What the two passes share: the document they patch and what they found so far. */
+interface ScanState extends DiscriminatorScanOptions {
+  readonly schema: OpenAPI3;
+  readonly objects: Record<string, DiscriminatorObject>;
+  readonly refsHandled: string[];
+  /** With the fix: the enum added to each schema, by schema and property, so values merge. */
+  readonly patchedEnums: Map<string, SchemaObject>;
+  /** With the fix: schema-name values, applied after both passes where no mapping names one. */
+  readonly inferredPatches: EnumPatch[];
+}
+
+/** The enum the schema at `patch.ref` gets, or null (with a warning) for another kind of schema. */
+function addDiscriminatorEnum(state: ScanState, patch: EnumPatch): SchemaObject | null {
+  const { silent, logger } = state;
+  const resolved = resolveDocumentRef<SchemaObject>(state.schema, patch.ref, { silent, logger });
+  const added = addEnumProperty(resolved, patch);
+  if (added === null) {
+    warnInvalidMapping(patch, state.logger);
+  }
+  return added;
+}
+
+/** One schema and discriminator property; two discriminators of one property share an enum. */
+function enumKey(patch: EnumPatch): string {
+  return `${patch.ref}\n${patch.discriminator.propertyName}`;
+}
+
+/** With the fix, a second discriminator of the same property adds its values to the first enum. */
+function mergeIntoPatchedEnum(state: ScanState, key: string, values: readonly string[]): boolean {
+  const patched = state.patchedEnums.get(key);
+  if (patched === undefined) {
+    return false;
+  }
+  const merged = patched.enum as unknown[];
+  merged.push(...values.filter((value) => !merged.includes(value)));
+  return true;
+}
+
+/**
+ * Add or replace the discriminator enum in the schema at `patch.ref`. Returns false, with a
+ * warning, when that schema is neither an `allOf` nor an object schema. Without the fix every
+ * patch adds a property, so two discriminators with different values intersect to `never`.
+ */
+function patchDiscriminatorEnum(state: ScanState, patch: EnumPatch): boolean {
+  if (!state.fixesValueConflicts) {
+    return addDiscriminatorEnum(state, patch) !== null;
+  }
+  const key = enumKey(patch);
+  if (mergeIntoPatchedEnum(state, key, patch.values)) {
+    return true;
+  }
+  const added = addDiscriminatorEnum(state, patch);
+  if (added !== null) {
+    state.patchedEnums.set(key, added);
+  }
+  return added !== null;
+}
+
+function markHandled(state: ScanState, ref: string): void {
+  if (!state.refsHandled.includes(ref)) {
+    state.refsHandled.push(ref);
+  }
+}
+
+function warnInvalidMapping(patch: EnumPatch, logger: Logger): void {
+  const mapped = `${patch.ref} => ${patch.values.join(", ")}`;
+  logger.warn(
+    "Discriminator mapping has an invalid schema (neither an object schema nor an allOf array): " +
+      `${mapped} (Discriminator: ${patch.discriminatorRef})`,
+  );
+}
+
+/** The schema name at the end of each `oneOf` `$ref` is the inferred discriminator value. */
+function inferredMapping(oneOf: (SchemaObject | ReferenceObject)[]): DiscriminatorMapping {
+  const mapping: DiscriminatorMapping = {};
+  for (const item of oneOf) {
+    if (!("$ref" in item)) {
+      continue;
+    }
+    const value = item.$ref.split("/").pop();
+    if (value) {
+      mapping[item.$ref] = { ...mapping[item.$ref], inferred: value };
+    }
+  }
+  return mapping;
+}
+
+/** Values defined in `discriminator.mapping` replace inferred ones for the same schema. */
+function addDefinedMapping(
+  mapping: DiscriminatorMapping,
+  discriminator: DiscriminatorObject,
+): void {
+  for (const [mappedValue, mappedRef] of Object.entries(discriminator.mapping ?? {})) {
+    if (!mappedRef) {
+      continue;
+    }
+    if (!mapping[mappedRef]?.defined) {
+      mapping[mappedRef] = { defined: [] };
+    }
+    mapping[mappedRef].defined?.push(mappedValue);
+  }
+}
+
+function patchMappedSchemas(
+  state: ScanState,
+  mapping: DiscriminatorMapping,
+  discriminator: Omit<EnumPatch, "ref" | "values">,
+): void {
+  for (const [ref, { inferred, defined }] of Object.entries(mapping)) {
+    const isSkipped = !state.fixesValueConflicts && state.refsHandled.includes(ref);
+    if (isSkipped || (!inferred && !defined)) {
+      continue;
+    }
+    // A defined value wins: the schema name may not be the value the API sends.
+    const values = defined ?? [inferred as string];
+    if (state.fixesValueConflicts && defined === undefined) {
+      // A mapping found later, in this pass or the next, may name the schema.
+      state.inferredPatches.push({ ...discriminator, ref, values });
+    } else if (patchDiscriminatorEnum(state, { ...discriminator, ref, values })) {
+      markHandled(state, ref);
+    }
+  }
+}
+
+/** Pass 1: collect every discriminator; patch the schemas of a discriminator + `oneOf`. */
+function collectDiscriminator(
+  state: ScanState,
+  value: Record<string, unknown>,
+  path: (string | number)[],
+): void {
+  const discriminator = value.discriminator as DiscriminatorObject | undefined;
+  if (!discriminator?.propertyName) {
+    return;
+  }
+  const discriminatorRef = createRef(path);
+  state.objects[discriminatorRef] = discriminator;
+  if (!Array.isArray(value.oneOf)) {
+    return;
+  }
+  const mapping = inferredMapping(value.oneOf);
+  if (discriminator.mapping) {
+    addDefinedMapping(mapping, discriminator);
+  }
+  patchMappedSchemas(state, mapping, { discriminator, discriminatorRef });
+}
+
+/** The mapping keys of `discriminator` that point at `ref`. */
+function valuesMappedTo(discriminator: DiscriminatorObject, ref: string): string[] {
+  return Object.entries(discriminator.mapping ?? {})
+    .filter(([, mappedRef]) => mappedRef === ref)
+    .map(([mappedValue]) => mappedValue);
+}
+
+/**
+ * An `allOf` item that is a `$ref` to a discriminator owner: the schema at `ref` inherits the
+ * discriminator, and gets its enum when the parent's mapping names it. Returns false when the
+ * `$ref` owns no discriminator, which ends the scan of this `allOf` (as in the original).
+ */
+function inheritFromRef(state: ScanState, parentRef: string, ref: string): boolean {
+  const discriminator = state.objects[parentRef];
+  if (!discriminator) {
+    return false;
+  }
+  const values = valuesMappedTo(discriminator, ref);
+  const patch = { ref, values, discriminator, discriminatorRef: parentRef };
+  if (values.length > 0 && patchDiscriminatorEnum(state, patch)) {
+    markHandled(state, ref);
+  }
+  state.objects[ref] = { ...discriminator };
+  return true;
+}
+
+/** Pass 2: a schema whose `allOf` holds a discriminator, or a `$ref` to one, inherits it. */
+function inheritDiscriminators(
+  state: ScanState,
+  value: Record<string, unknown>,
+  path: (string | number)[],
+): void {
+  if (!Array.isArray(value.allOf)) {
+    return;
+  }
+  for (const item of value.allOf as (SchemaObject | ReferenceObject)[]) {
+    if ("$ref" in item) {
+      if (!inheritFromRef(state, item.$ref, createRef(path))) {
+        return;
+      }
+    } else if (item.discriminator?.propertyName) {
+      state.objects[createRef(path)] = { ...item.discriminator };
+    }
+  }
+}
+
+/** The discriminators of a bundled document, after patching the mapped schemas in place. */
+export interface DiscriminatorScan {
+  objects: Record<string, DiscriminatorObject>;
+  refsHandled: string[];
+}
+
+/**
+ * With the fix: a schema-name value, only for a schema and property that no mapping gave a value.
+ * Every enum patched so far came from a mapping, since schema-name values wait for this step.
+ */
+function applyInferredPatches(state: ScanState): void {
+  const mapped = new Set(state.patchedEnums.keys());
+  for (const patch of state.inferredPatches) {
+    if (!mapped.has(enumKey(patch)) && patchDiscriminatorEnum(state, patch)) {
+      markHandled(state, patch.ref);
+    }
+  }
+}
+
+/** Find every discriminator in `schema`; warnings go to `logger` unless `silent`. */
+export function findDiscriminators(
+  schema: OpenAPI3,
+  options: DiscriminatorScanOptions,
+): DiscriminatorScan {
+  const state: ScanState = {
+    ...options,
+    schema,
+    objects: {},
+    refsHandled: [],
+    patchedEnums: new Map(),
+    inferredPatches: [],
+  };
+  walkDocument(schema, (value, path) => collectDiscriminator(state, value, path));
+  // A second pass, because an `allOf` may name a discriminator that is defined later.
+  walkDocument(schema, (value, path) => inheritDiscriminators(state, value, path));
+  applyInferredPatches(state);
+  return { objects: state.objects, refsHandled: state.refsHandled };
+}
+
+/**
+ * Return a key–value map of discriminator objects found in a schema. Warnings go to `logger`;
+ * without one, to the default terminal logger, as the original did.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function scanDiscriminators(
+  schema: OpenAPI3,
+  options: GeneratorOptions,
+  logger: Logger = defaultLogger(options.silent ?? false),
+): DiscriminatorScan {
+  const silent = options.silent ?? false;
+  return findDiscriminators(schema, { silent, logger, fixesValueConflicts: false });
+}

package/src/api/document-declarations.ts

@@ -0,0 +1,41 @@
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { printWithTypeScript } from "../adapters/type-ast-bridge/print-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+
+/** The document in three parts; the footer may hold TypeScript nodes from user code. */
+export interface TransformedDocument {
+  readonly body: readonly IrDeclaration[];
+  readonly footer: readonly FooterEntry[];
+  readonly closing: readonly IrDeclaration[];
+}
+
+/** The TypeScript printer ends the file with a line break; a raw declaration's text has none. */
+function withoutFinalLineBreak(text: string): string {
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+/** A TypeScript node from user code, as the TypeScript printer prints it. */
+function printedNode(node: ts.Node): IrDeclaration {
+  return {
+    kind: "rawDeclaration",
+    text: withoutFinalLineBreak(printWithTypeScript(loadTypeScript(), [node])),
+  };
+}
+
+function entryDeclaration(entry: FooterEntry): IrDeclaration {
+  return isIrDeclaration(entry) ? entry : printedNode(entry);
+}
+
+/**
+ * The document as IR declarations in output order. Footer TypeScript nodes from user code become
+ * raw text through the bridge; raw text is printed as written (ADR-010, decision 4).
+ */
+export function documentDeclarations({
+  body,
+  footer,
+  closing,
+}: TransformedDocument): IrDeclaration[] {
+  return [...body, ...footer.map(entryDeclaration), ...closing];
+}

package/src/api/document-refs.ts

@@ -0,0 +1,71 @@
+import { parseRef } from "@redocly/openapi-core/lib/ref-utils.js";
+import type { Logger } from "../application/ports/logger.js";
+import { defaultLogger } from "./default-ports.js";
+
+/** `$ref` resolution and the document walk that the generator's pre-pass uses. */
+
+export interface ResolveRefOptions {
+  silent: boolean;
+  visited?: string[];
+  /** @internal Where warnings go; the default terminal logger (respecting `silent`) if absent. */
+  logger?: Logger;
+}
+
+/** Resolve a `$ref` in a document; warns and returns undefined when it cannot. */
+export function resolveDocumentRef<T>(
+  schema: any,
+  $ref: string,
+  options: ResolveRefOptions,
+): T | undefined {
+  const { visited = [] } = options;
+  const logger = options.logger ?? defaultLogger(options.silent ?? false);
+  const { pointer } = parseRef($ref);
+  if (!pointer.length) {
+    return undefined;
+  }
+  let node = schema;
+  for (const key of pointer) {
+    if (node && typeof node === "object" && node[key]) {
+      node = node[key];
+    } else {
+      logger.warn(`Could not resolve $ref "${$ref}"`);
+      return undefined;
+    }
+  }
+
+  // if this is also a $ref, keep tracing
+  if (node && typeof node === "object" && node.$ref) {
+    if (visited.includes(node.$ref)) {
+      logger.warn(`Could not resolve circular $ref "${$ref}"`);
+      return undefined;
+    }
+    return resolveDocumentRef(schema, node.$ref, {
+      ...options,
+      logger,
+      visited: [...visited, node.$ref],
+    });
+  }
+
+  return node;
+}
+
+/** Call `cb` for every object in a JSON-serializable (non-circular) value, depth first. */
+export function walkDocument(
+  obj: unknown,
+  cb: (value: Record<string, unknown>, path: (string | number)[]) => void,
+  path: (string | number)[] = [],
+): void {
+  if (!obj || typeof obj !== "object") {
+    return;
+  }
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      walkDocument(obj[i], cb, path.concat(i));
+    }
+    return;
+  }
+  cb(obj as Record<string, unknown>, path);
+  for (const k of Object.keys(obj)) {
+    walkDocument((obj as Record<string, unknown>)[k], cb, path.concat(k));
+  }
+}

package/src/api/document-run.ts

@@ -0,0 +1,159 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { Config as RedoclyConfig } from "@redocly/openapi-core";
+import { sourceEmptyError } from "../adapters/redocly-loader/schema-load-errors.js";
+import type { Logger } from "../application/ports/logger.js";
+import type { RefAccess, SchemaLoader } from "../application/ports/schema-loader.js";
+import { withStackOverflowReported } from "../application/stack-overflow.js";
+import {
+  ineffectiveFixNotices,
+  OutputFix,
+  outputFixNamesOf,
+  resolveOutputFixes,
+} from "../domain/output-fixes.js";
+import type { GeneratorOptions, GlobalContext, OpenAPI3, SchemaSource } from "../types.js";
+import { findDiscriminators } from "./discriminator-scan.js";
+import { resolveDocumentRef } from "./document-refs.js";
+import { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
+
+/** The ports of one generator run, wired by the Node API or the CLI (ENGINEERING_PLAN 4.5). */
+export interface GeneratorPorts {
+  readonly loader: SchemaLoader;
+  readonly logger: Logger;
+  /** The Redocly config the loader uses; the run's context exposes it as `ctx.redoc`. */
+  readonly redoc: RedoclyConfig;
+  /** A monotonic time in milliseconds, for debug durations. */
+  readonly now: () => number;
+}
+
+/** A validated, bundled document and the context of one generator run. */
+export interface DocumentRun {
+  readonly schema: OpenAPI3;
+  readonly ctx: GlobalContext;
+}
+
+/** The context fields that are user flags, with the original defaults. */
+type ContextFlags = Omit<
+  GlobalContext,
+  | "discriminators"
+  | "injectFooter"
+  | "redoc"
+  | "resolve"
+  | "runFooter"
+  | "legacyCallbackWarnings"
+  | "logger"
+  | "fix"
+>;
+
+function sourceCwd(options: GeneratorOptions): URL {
+  return options.cwd instanceof URL
+    ? options.cwd
+    : new URL(`file://${options.cwd ?? process.cwd()}/`);
+}
+
+/** The `$ref` limits of the options; a relative local root resolves against the cwd. */
+function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {
+  const { localRefRoot, remoteRefHosts } = options;
+  const localRoot =
+    typeof localRefRoot === "string"
+      ? pathToFileURL(path.resolve(fileURLToPath(cwd), localRefRoot))
+      : localRefRoot;
+  return {
+    ...(localRoot === undefined ? {} : { localRoot }),
+    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteRefHosts }),
+  };
+}
+
+function callbackOptions(options: GeneratorOptions) {
+  return {
+    irCallbacks: options.irCallbacks === true,
+    postTransform: typeof options.postTransform === "function" ? options.postTransform : undefined,
+    transform: typeof options.transform === "function" ? options.transform : undefined,
+    transformProperty:
+      typeof options.transformProperty === "function" ? options.transformProperty : undefined,
+  };
+}
+
+function contextFlags(options: GeneratorOptions): ContextFlags {
+  return {
+    additionalProperties: options.additionalProperties ?? false,
+    alphabetize: options.alphabetize ?? false,
+    arrayLength: options.arrayLength ?? false,
+    binaryAsBlob: options.binaryAsBlob ?? false,
+    defaultNonNullable: options.defaultNonNullable ?? true,
+    emptyObjectsUnknown: options.emptyObjectsUnknown ?? false,
+    enum: options.enum ?? false,
+    enumValues: options.enumValues ?? false,
+    conditionalEnums: options.conditionalEnums ?? false,
+    dedupeEnums: options.dedupeEnums ?? false,
+    excludeDeprecated: options.excludeDeprecated ?? false,
+    exportType: options.exportType ?? false,
+    immutable: options.immutable ?? false,
+    rootTypes: options.rootTypes ?? false,
+    rootTypesNoSchemaPrefix: options.rootTypesNoSchemaPrefix ?? false,
+    rootTypesKeepCasing: options.rootTypesKeepCasing ?? false,
+    pathParamsAsTypes: options.pathParamsAsTypes ?? false,
+    propertiesRequiredByDefault: options.propertiesRequiredByDefault ?? false,
+    silent: options.silent ?? false,
+    ...(options.inject === undefined ? {} : { inject: options.inject }),
+    makePathsEnum: options.makePathsEnum ?? false,
+    generatePathParams: options.generatePathParams ?? false,
+    readWriteMarkers: options.readWriteMarkers ?? false,
+    ...callbackOptions(options),
+  };
+}
+
+/**
+ * The fixes of the options, `all` expanded; fails with `OPTION_FIX_UNKNOWN` for another name.
+ * A fix named without the option it needs is reported, since it changes nothing.
+ */
+function outputFixesOf(options: GeneratorOptions, logger: Logger): readonly OutputFix[] {
+  const names = outputFixNamesOf(options.fix ?? []);
+  for (const notice of ineffectiveFixNotices(names, (option) => options[option] === true)) {
+    logger.warn(notice);
+  }
+  return [...resolveOutputFixes(names)];
+}
+
+/**
+ * Load the source through the ports, then build the run's context from the options. The fix names
+ * are checked first, so a typo fails before the document is read.
+ */
+export async function createDocumentRun(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<DocumentRun> {
+  if (!source) {
+    throw sourceEmptyError("Empty schema. Please specify a URL, file path, or Redocly Config");
+  }
+  const { logger } = ports;
+  const fix = outputFixesOf(options, logger);
+  const silent = options.silent ?? false;
+  const cwd = sourceCwd(options);
+  const schema = await ports.loader.load({
+    source,
+    cwd,
+    shouldLint: options.lint ?? true,
+    refAccess: refAccessOf(options, cwd),
+  });
+  withStackOverflowReported("transform", () => warnUnsupportedFeatures(schema, logger));
+  const ctx: GlobalContext = {
+    ...contextFlags(options),
+    fix,
+    // The scan walks every schema before the transform does, so on a larger stack, where loading
+    // passed, it is the first step to run out.
+    discriminators: withStackOverflowReported("transform", () =>
+      findDiscriminators(schema, {
+        silent,
+        logger,
+        fixesValueConflicts: fix.includes(OutputFix.DISCRIMINATOR_VALUES),
+      }),
+    ),
+    injectFooter: [],
+    redoc: ports.redoc,
+    resolve: ($ref) => resolveDocumentRef(schema, $ref, { silent, logger }),
+    logger,
+  };
+  return { schema, ctx };
+}

package/src/api/footer-entry.ts

@@ -0,0 +1,23 @@
+import { isTypeAliasNamed } from "../adapters/type-ast-bridge/footer-nodes.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+
+/** A footer entry: a declaration in IR, or a TypeScript node added by user code. */
+export type FooterEntry = IrDeclaration | ts.Node;
+
+/** IR nodes have a string `kind`; TypeScript nodes have a numeric `SyntaxKind`. */
+export function isIrDeclaration(entry: FooterEntry): entry is IrDeclaration {
+  return typeof entry.kind === "string";
+}
+
+/**
+ * Whether the entry declares a type alias with this name: an IR type alias, a named raw
+ * declaration (the helper types), or a user's TypeScript type alias. Helpers are added once.
+ */
+export function declaresTypeAlias(entry: FooterEntry, name: string): boolean {
+  if (!isIrDeclaration(entry)) {
+    return isTypeAliasNamed(loadTypeScript(), entry, name);
+  }
+  return (entry.kind === "typeAlias" || entry.kind === "rawDeclaration") && entry.name === name;
+}

package/src/api/footer-sink.ts

@@ -0,0 +1,67 @@
+import { appendMember, asInterfaceNamed } from "../adapters/type-ast-bridge/footer-nodes.js";
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import type { FooterSink } from "../application/transform/footer/document-footer.js";
+import type {
+  IrDeclaration,
+  IrInterfaceDeclaration,
+  IrPropertySignature,
+} from "../domain/ir/nodes.js";
+import { declaresTypeAlias, type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+
+const OPERATIONS_NAME = "operations";
+
+/**
+ * The footer of a run is its `ctx.injectFooter` list. The generator adds IR declarations; user
+ * code may add IR declarations or TypeScript nodes (ENGINEERING_PLAN 6.2).
+ */
+export class ContextFooterSink implements FooterSink {
+  private readonly footer: FooterEntry[];
+
+  constructor(footer: FooterEntry[]) {
+    this.footer = footer;
+  }
+
+  hasTypeAlias(name: string): boolean {
+    return this.footer.some((entry) => declaresTypeAlias(entry, name));
+  }
+
+  add(declaration: IrDeclaration): void {
+    this.footer.push(declaration);
+  }
+
+  /**
+   * Add a member to the `operations` interface, declared first (exported) when missing, so it
+   * comes before any declaration `build` adds. A user's TypeScript `operations` interface gets
+   * the member in place, as in the original.
+   */
+  addOperation(build: () => IrPropertySignature): void {
+    const existing = this.findOperations();
+    if (existing !== null && !isIrDeclaration(existing.entry)) {
+      const ts = loadTypeScript();
+      const node = asInterfaceNamed(ts, existing.entry, OPERATIONS_NAME);
+      if (node) {
+        appendMember(ts, node, build());
+      }
+      return;
+    }
+    const index = existing?.index ?? this.footer.push(emptyOperations()) - 1;
+    const member = build();
+    const operations = this.footer[index] as IrInterfaceDeclaration;
+    this.footer[index] = { ...operations, members: [...operations.members, member] };
+  }
+
+  /** The first `operations` interface: the generator's (IR) or a user's (TypeScript). */
+  private findOperations(): { entry: FooterEntry; index: number } | null {
+    const index = this.footer.findIndex((entry) =>
+      isIrDeclaration(entry)
+        ? entry.kind === "interface" && entry.name === OPERATIONS_NAME
+        : asInterfaceNamed(loadTypeScript(), entry, OPERATIONS_NAME) !== null,
+    );
+    const entry = this.footer[index];
+    return entry === undefined ? null : { entry, index };
+  }
+}
+
+function emptyOperations(): IrInterfaceDeclaration {
+  return { kind: "interface", name: OPERATIONS_NAME, isExported: true, members: [], comments: [] };
+}

package/src/api/legacy-callback-warning.ts

@@ -0,0 +1,29 @@
+import type { GlobalContext, LegacyCallbackName } from "../types.js";
+import { defaultLogger } from "./default-ports.js";
+
+/** Where the IR callbacks are documented; the warning points users there. */
+export const IR_CALLBACKS_GUIDE_URL =
+  "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/node.md#ir-callbacks";
+
+const USES: Readonly<Record<LegacyCallbackName, string>> = {
+  transform: "`transform` returned a TypeScript node",
+  postTransform: "`postTransform` receives TypeScript nodes",
+  transformProperty: "`transformProperty` receives TypeScript nodes",
+};
+
+function message(name: LegacyCallbackName): string {
+  return (
+    `${USES[name]}. This form works in 1.x through the TypeScript bridge and is removed in 2.0. ` +
+    `Use irCallbacks: true and return IR or type text instead: ${IR_CALLBACKS_GUIDE_URL}`
+  );
+}
+
+/** Warn once per run and callback; `silent` runs record the use but print nothing. */
+export function warnLegacyCallback(ctx: GlobalContext, name: LegacyCallbackName): void {
+  ctx.legacyCallbackWarnings ??= new Set();
+  if (ctx.legacyCallbackWarnings.has(name)) {
+    return;
+  }
+  ctx.legacyCallbackWarnings.add(name);
+  (ctx.logger ?? defaultLogger(ctx.silent)).warn(message(name));
+}