openapi-typesafe 1.0.0-rc.1 → 1.0.0-rc.3

package/src/api/document-refs.ts

@@ -1,5 +1,6 @@
 import { parseRef } from "@redocly/openapi-core/lib/ref-utils.js";
 import type { Logger } from "../application/ports/logger.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import { defaultLogger } from "./default-ports.js";
 
 /** `$ref` resolution and the document walk that the generator's pre-pass uses. */
@@ -11,9 +12,13 @@ export interface ResolveRefOptions {
   logger?: Logger;
 }
 
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 /** Resolve a `$ref` in a document; warns and returns undefined when it cannot. */
 export function resolveDocumentRef<T>(
-  schema: any,
+  schema: unknown,
   $ref: string,
   options: ResolveRefOptions,
 ): T | undefined {
@@ -23,30 +28,29 @@ export function resolveDocumentRef<T>(
   if (!pointer.length) {
     return undefined;
   }
-  let node = schema;
+  let node: unknown = schema;
   for (const key of pointer) {
-    if (node && typeof node === "object" && node[key]) {
-      node = node[key];
-    } else {
-      logger.warn(`Could not resolve $ref "${$ref}"`);
+    const child = isObject(node) ? node[key] : undefined;
+    if (!child) {
+      logger.warn(warningText(`Could not resolve $ref "${$ref}"`, WARNING_CODES.REF_NOT_FOUND));
       return undefined;
     }
+    node = child;
   }
 
   // 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}"`);
+  const next = isObject(node) ? node.$ref : undefined;
+  if (typeof next === "string" && next) {
+    if (visited.includes(next)) {
+      logger.warn(
+        warningText(`Could not resolve circular $ref "${$ref}"`, WARNING_CODES.REF_CIRCULAR),
+      );
       return undefined;
     }
-    return resolveDocumentRef(schema, node.$ref, {
-      ...options,
-      logger,
-      visited: [...visited, node.$ref],
-    });
+    return resolveDocumentRef(schema, next, { ...options, logger, visited: [...visited, next] });
   }
 
-  return node;
+  return node as T;
 }
 
 /** Call `cb` for every object in a JSON-serializable (non-circular) value, depth first. */

package/src/api/document-run.ts

@@ -2,6 +2,7 @@ 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 { DeprecationReporter } from "../application/ports/deprecation-reporter.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";
@@ -11,17 +12,22 @@ import {
   outputFixNamesOf,
   resolveOutputFixes,
 } from "../domain/output-fixes.js";
-import type { GeneratorOptions, GlobalContext, OpenAPI3, SchemaSource } from "../types.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import type { GeneratorOptions, OpenAPI3, SchemaSource } from "../types.js";
+import { processCwd } from "./default-ports.js";
 import { warnDiscriminatorValueConflicts } from "./discriminator-conflict-warnings.js";
 import { findDiscriminators } from "./discriminator-scan.js";
 import { resolveDocumentRef } from "./document-refs.js";
 import { warnIdenticalPathTemplates } from "./path-template-warnings.js";
+import type { RunContext } from "./run-context.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;
+  /** Where the run reports the deprecated callback forms (ADR-004). */
+  readonly deprecations: DeprecationReporter;
   /** 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. */
@@ -31,12 +37,12 @@ export interface GeneratorPorts {
 /** A validated, bundled document and the context of one generator run. */
 export interface DocumentRun {
   readonly schema: OpenAPI3;
-  readonly ctx: GlobalContext;
+  readonly ctx: RunContext;
 }
 
 /** The context fields that are user flags, with the original defaults. */
 type ContextFlags = Omit<
-  GlobalContext,
+  RunContext,
   | "discriminators"
   | "injectFooter"
   | "redoc"
@@ -44,6 +50,7 @@ type ContextFlags = Omit<
   | "runFooter"
   | "legacyCallbackWarnings"
   | "logger"
+  | "deprecations"
   | "fix"
 >;
 
@@ -56,7 +63,7 @@ function sourceCwd(options: GeneratorOptions): URL {
   if (cwd instanceof URL) {
     return cwd.pathname.endsWith("/") ? cwd : new URL(`${cwd.pathname}/`, cwd);
   }
-  const directory = path.resolve(cwd === undefined ? process.cwd() : cwd.toString());
+  const directory = path.resolve(cwd === undefined ? processCwd() : cwd.toString());
   return pathToFileURL(path.join(directory, path.sep));
 }
 
@@ -119,7 +126,7 @@ function contextFlags(options: GeneratorOptions): ContextFlags {
 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);
+    logger.warn(warningText(notice, WARNING_CODES.FIX_NEEDS_OPTION));
   }
   return [...resolveOutputFixes(names)];
 }
@@ -156,7 +163,7 @@ export async function createDocumentRun(
     refAccess: refAccessOf(options, cwd),
   });
   warnAboutDocument(schema, fix, logger);
-  const ctx: GlobalContext = {
+  const ctx: RunContext = {
     ...contextFlags(options),
     fix,
     // The scan walks every schema before the transform does, so on a larger stack, where loading
@@ -172,6 +179,7 @@ export async function createDocumentRun(
     redoc: ports.redoc,
     resolve: ($ref) => resolveDocumentRef(schema, $ref, { silent, logger }),
     logger,
+    deprecations: ports.deprecations,
   };
   return { schema, ctx };
 }

package/src/api/footer-sink.ts

@@ -4,6 +4,7 @@ import type { FooterSink } from "../application/transform/footer/document-footer
 import type {
   IrDeclaration,
   IrInterfaceDeclaration,
+  IrMember,
   IrPropertySignature,
 } from "../domain/ir/nodes.js";
 import { declaresTypeAlias, type FooterEntry, isIrDeclaration } from "./footer-entry.js";
@@ -16,6 +17,12 @@ const OPERATIONS_NAME = "operations";
  */
 export class ContextFooterSink implements FooterSink {
   private readonly footer: FooterEntry[];
+  /**
+   * The IR `operations` entry this sink wrote last, with its members array that only this sink
+   * holds. Adding to it in place keeps a run linear: copying the members on every operation was
+   * quadratic (about 0.4 s on Microsoft Graph beta).
+   */
+  private owned: OwnedOperations | null = null;
 
   constructor(footer: FooterEntry[]) {
     this.footer = footer;
@@ -35,6 +42,11 @@ export class ContextFooterSink implements FooterSink {
    * the member in place, as in the original.
    */
   addOperation(build: () => IrPropertySignature): void {
+    const owned = this.currentOwnedOperations();
+    if (owned !== null) {
+      owned.members.push(build());
+      return;
+    }
     const existing = this.findOperations();
     if (existing !== null && !isIrDeclaration(existing.entry)) {
       const ts = loadTypeScript();
@@ -45,9 +57,23 @@ export class ContextFooterSink implements FooterSink {
       return;
     }
     const index = existing?.index ?? this.footer.push(emptyOperations()) - 1;
-    const member = build();
+    this.takeOwnership(index).members.push(build());
+  }
+
+  /** The owned entry, unless user code replaced or moved it in the footer since. */
+  private currentOwnedOperations(): OwnedOperations | null {
+    const owned = this.owned;
+    return owned !== null && this.footer[owned.index] === owned.entry ? owned : null;
+  }
+
+  /** Replace the IR entry at `index` with a copy whose members array only this sink holds. */
+  private takeOwnership(index: number): OwnedOperations {
     const operations = this.footer[index] as IrInterfaceDeclaration;
-    this.footer[index] = { ...operations, members: [...operations.members, member] };
+    const members: IrMember[] = [...operations.members];
+    const entry: IrInterfaceDeclaration = { ...operations, members };
+    this.footer[index] = entry;
+    this.owned = { entry, members, index };
+    return this.owned;
   }
 
   /** The first `operations` interface: the generator's (IR) or a user's (TypeScript). */
@@ -62,6 +88,12 @@ export class ContextFooterSink implements FooterSink {
   }
 }
 
+interface OwnedOperations {
+  readonly entry: IrInterfaceDeclaration;
+  readonly members: IrMember[];
+  readonly index: number;
+}
+
 function emptyOperations(): IrInterfaceDeclaration {
   return { kind: "interface", name: OPERATIONS_NAME, isExported: true, members: [], comments: [] };
 }

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

@@ -1,5 +1,7 @@
-import type { GlobalContext, LegacyCallbackName } from "../types.js";
-import { defaultLogger } from "./default-ports.js";
+import { DEPRECATION_CODES, type DeprecationCode } from "../domain/deprecations.js";
+import type { LegacyCallbackName } from "../types.js";
+import { defaultDeprecationReporter } from "./default-ports.js";
+import type { RunContext } from "./run-context.js";
 
 /** Where the IR callbacks are documented; the warning points users there. */
 export const IR_CALLBACKS_GUIDE_URL =
@@ -11,6 +13,12 @@ const USES: Readonly<Record<LegacyCallbackName, string>> = {
   transformProperty: "`transformProperty` receives TypeScript nodes",
 };
 
+const CODES: Readonly<Record<LegacyCallbackName, DeprecationCode>> = {
+  transform: DEPRECATION_CODES.OPENAPI_TYPESAFE_DEP_TS_TRANSFORM,
+  postTransform: DEPRECATION_CODES.OPENAPI_TYPESAFE_DEP_TS_POST_TRANSFORM,
+  transformProperty: DEPRECATION_CODES.OPENAPI_TYPESAFE_DEP_TS_TRANSFORM_PROPERTY,
+};
+
 function message(name: LegacyCallbackName): string {
   return (
     `${USES[name]}. This form works in 1.x through the TypeScript bridge and is removed in 2.0. ` +
@@ -18,12 +26,15 @@ function message(name: LegacyCallbackName): string {
   );
 }
 
-/** Warn once per run and callback; `silent` runs record the use but print nothing. */
-export function warnLegacyCallback(ctx: GlobalContext, name: LegacyCallbackName): void {
+/**
+ * Report a deprecated callback form once per run and callback, as a deprecation (not through the
+ * logger, so `silent` does not hide it). The Node.js reporter shows each code once per process.
+ */
+export function warnLegacyCallback(ctx: RunContext, 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));
+  (ctx.deprecations ?? defaultDeprecationReporter()).report(CODES[name], message(name));
 }

package/src/api/legacy-ts-helpers.ts

@@ -103,7 +103,7 @@ export function tsDedupe(types: TypeInput[]): ts.TypeNode[] {
 }
 
 /** @deprecated The generator keeps its own enum registry per run; kept for 1.x (ADR-004). */
-export const enumCache = new Map<string, ts.EnumDeclaration>();
+export const enumCache: Map<string, ts.EnumDeclaration> = new Map();
 
 /**
  * Create a TS enum (with sanitized name and members)
@@ -114,7 +114,7 @@ export function tsEnum(
   members: (string | number)[],
   metadata?: { name?: string; description?: string | null }[],
   options?: { export?: boolean; shouldCache?: boolean },
-) {
+): ts.EnumDeclaration {
   const ts = loadTypeScript();
   let enumName = sanitizeMemberName(name);
   enumName = `${enumName.charAt(0).toUpperCase()}${enumName.substring(1)}`;
@@ -149,7 +149,7 @@ export function tsArrayLiteralExpression(
   elementType: TypeInput,
   values: (string | number)[],
   options?: { export?: boolean; readonly?: boolean; injectFooter?: FooterEntry[] },
-) {
+): ts.VariableStatement {
   const ts = loadTypeScript();
   let variableName = sanitizeMemberName(name);
   variableName = `${variableName.charAt(0).toLowerCase()}${variableName.substring(1)}`;
@@ -223,7 +223,7 @@ function enumMemberName(value: string | number, explicitName: string | undefined
 export function tsEnumMember(
   value: string | number,
   metadata: { name?: string; description?: string | null } = {},
-) {
+): ts.EnumMember {
   const ts = loadTypeScript();
   const name = enumMemberName(value, metadata.name);
   const member = ts.factory.createEnumMember(name, toValueExpression(ts, value));
@@ -281,7 +281,9 @@ export function tsModifiers(modifiers: { readonly?: boolean; export?: boolean })
  * Create a valid property index
  * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
  */
-export function tsPropertyIndex(index: string | number) {
+export function tsPropertyIndex(
+  index: string | number,
+): ts.Identifier | ts.NumericLiteral | ts.StringLiteral {
   const ts = loadTypeScript();
   if (
     (typeof index === "number" && !(index < 0)) ||

package/src/api/legacy-utils.ts

@@ -90,7 +90,7 @@ export type { ResolveRefOptions } from "./document-refs.js";
  * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
  */
 export function resolveRef<T>(
-  schema: any,
+  schema: unknown,
   $ref: string,
   options: ResolveRefOptions,
 ): T | undefined {

package/src/api/openapi-ts.ts

@@ -3,6 +3,8 @@ import { withStackOverflowReported } from "../application/stack-overflow.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { GeneratorOptions, SchemaSource } from "../types.js";
 import {
+  DEFAULT_REMOTE_DOCUMENT_LIMITS,
+  defaultDeprecationReporter,
   defaultLogger,
   defaultRedoclyConfig,
   monotonicNow,
@@ -33,7 +35,10 @@ export async function generateDeclarations(
   return result;
 }
 
-/** The default ports: the terminal logger, the given or default Redocly config, Redocly loading. */
+/**
+ * The default ports: the terminal logger, Node.js deprecation warnings, the given or default
+ * Redocly config, Redocly loading.
+ */
 export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<GeneratorPorts> {
   const logger = defaultLogger(options.silent ?? false);
   const redoc = options.redocly ?? (await defaultRedoclyConfig());
@@ -42,8 +47,9 @@ export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<
     logger,
     now: monotonicNow,
     remoteRefTimeoutMs: REMOTE_REF_TIMEOUT_MS,
+    remoteDocumentLimits: DEFAULT_REMOTE_DOCUMENT_LIMITS,
   });
-  return { loader, logger, redoc, now: monotonicNow };
+  return { loader, logger, deprecations: defaultDeprecationReporter(), redoc, now: monotonicNow };
 }
 
 /**

package/src/api/run-context.ts

@@ -0,0 +1,37 @@
+import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
+import type { Logger } from "../application/ports/logger.js";
+import type { DocumentFooter } from "../application/transform/transform-context.js";
+import type { GlobalContext, LegacyCallbackName, SchemaObject } from "../types.js";
+
+/**
+ * The context the generator builds for a run: the public `GlobalContext` plus the run's own
+ * state. The state is not part of the public type, so it can change in a minor release; every
+ * field is optional, so a context a user builds by hand is a valid `RunContext` without it.
+ * Callbacks receive this object as `options.ctx` and may spread it; the state travels with it.
+ */
+export interface RunContext extends GlobalContext {
+  readonly discriminators: GlobalContext["discriminators"] & {
+    /**
+     * With the `discriminator-values` fix: for each enum the scan added to a member and each
+     * inherited discriminator object, the enum of the owner's property and the location it is
+     * typed at.
+     */
+    readonly enumParents?: ReadonlyMap<
+      object,
+      { readonly schema: SchemaObject; readonly path: string }
+    >;
+    /**
+     * With the `discriminator-values` fix: for each schema, the properties of the discriminators
+     * it inherits besides `objects[ref]`, which it redefines too.
+     */
+    readonly otherProperties?: Readonly<Record<string, readonly string[]>>;
+  };
+  /** Footer state of this run (enum registry and enum naming), created on first use. */
+  runFooter?: DocumentFooter;
+  /** The deprecated callback forms this run has warned about (once each). */
+  legacyCallbackWarnings?: Set<LegacyCallbackName>;
+  /** Where this run reports warnings and debug output; without it, the terminal. */
+  logger?: Logger;
+  /** Where this run reports deprecated forms; without it, Node.js `DeprecationWarning`s. */
+  deprecations?: DeprecationReporter;
+}

package/src/api/string-to-ast.ts

@@ -1,27 +1,23 @@
-import { deprecate } from "node:util";
 import { parseStatements } from "../adapters/type-ast-bridge/ir-declarations-to-typescript.js";
 import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { DEPRECATION_CODES } from "../domain/deprecations.js";
+import { defaultDeprecationReporter } from "./default-ports.js";
 import { IR_CALLBACKS_GUIDE_URL } from "./legacy-callback-warning.js";
 
 const STRING_TO_AST_DEPRECATION =
   "stringToAST() is deprecated and removed in 2.0. Return TypeScript type text from an IR " +
   `callback (irCallbacks: true) instead: ${IR_CALLBACKS_GUIDE_URL}`;
 
-/** Node's deprecation code for `stringToAST`, so users can filter or trace the warning. */
-export const STRING_TO_AST_DEPRECATION_CODE = "OPENAPI_TYPESAFE_DEP_STRING_TO_AST";
-
-function parseSource(source: string): unknown[] {
-  return [...parseStatements(loadTypeScript(), source)];
-}
-
 /**
  * Convert an arbitrary string to TS (assuming it’s valid). Parses with the TypeScript bridge, so
- * it needs TypeScript 6 or earlier (or `@typescript/typescript6`). Node's `util.deprecate` warns
- * on the first call only.
+ * it needs TypeScript 6 or earlier (or `@typescript/typescript6`). Emits a Node.js
+ * `DeprecationWarning` (`OPENAPI_TYPESAFE_DEP_STRING_TO_AST`) on the first call only.
  * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 7). Use type text in IR callbacks.
  */
-export const stringToAST: (source: string) => unknown[] = deprecate(
-  parseSource,
-  STRING_TO_AST_DEPRECATION,
-  STRING_TO_AST_DEPRECATION_CODE,
-);
+export function stringToAST(source: string): unknown[] {
+  defaultDeprecationReporter().report(
+    DEPRECATION_CODES.OPENAPI_TYPESAFE_DEP_STRING_TO_AST,
+    STRING_TO_AST_DEPRECATION,
+  );
+  return [...parseStatements(loadTypeScript(), source)];
+}

package/src/api/transform-context.ts

@@ -11,22 +11,24 @@ import type {
   TransformDiagnostics,
   TransformOptions,
 } from "../application/transform/transform-context.js";
-import type { GlobalContext, TransformNodeOptions } from "../types.js";
+import type { TransformNodeOptions } from "../types.js";
 import { defaultLogger, monotonicNow } from "./default-ports.js";
 import { ContextFooterSink } from "./footer-sink.js";
+import type { RunContext } from "./run-context.js";
 import { schemaCallbacks } from "./schema-callbacks.js";
 
 /**
- * Builds the ported transformers' context from the original `GlobalContext`: options, refs,
- * discriminators, the run footer and the user callbacks (see `schema-callbacks.ts`).
+ * Builds the ported transformers' context from the original `GlobalContext` (in a run, a
+ * `RunContext`): options, refs, discriminators, the run footer and the user callbacks (see
+ * `schema-callbacks.ts`).
  */
 
-function transformOptions(ctx: GlobalContext): TransformOptions {
+function transformOptions(ctx: RunContext): TransformOptions {
   return {
     additionalProperties: ctx.additionalProperties,
     alphabetize: ctx.alphabetize,
     arrayLength: ctx.arrayLength,
-    binaryAsBlob: ctx.binaryAsBlob,
+    binaryAsBlob: ctx.binaryAsBlob ?? false,
     conditionalEnums: ctx.conditionalEnums,
     dedupeEnums: ctx.dedupeEnums,
     defaultNonNullable: ctx.defaultNonNullable,
@@ -50,7 +52,7 @@ function transformOptions(ctx: GlobalContext): TransformOptions {
 }
 
 /** One footer per run: it holds the enum registry, so it lives on the run's context. */
-function runFooter(ctx: GlobalContext): DocumentFooter {
+function runFooter(ctx: RunContext): DocumentFooter {
   ctx.runFooter ??= new RunFooter(new ContextFooterSink(ctx.injectFooter), ctx.dedupeEnums);
   return ctx.runFooter;
 }
@@ -60,7 +62,7 @@ const CASING: NameCasing = { pascalCase: (text) => changeCase.pascalCase(text) }
 /**
  * A monotonic clock and the run's logger (the default one for a user's own context), "ts" group.
  */
-function diagnostics(ctx: GlobalContext): TransformDiagnostics {
+function diagnostics(ctx: RunContext): TransformDiagnostics {
   const logger = ctx.logger ?? defaultLogger(ctx.silent);
   return {
     now: monotonicNow,
@@ -69,7 +71,7 @@ function diagnostics(ctx: GlobalContext): TransformDiagnostics {
 }
 
 /** The ported transformers' context for one call from a legacy transformer. */
-export function createTransformContext(ctx: GlobalContext): TransformContext {
+export function createTransformContext(ctx: RunContext): TransformContext {
   return {
     options: transformOptions(ctx),
     refs: { resolve: (ref) => ctx.resolve(ref) },

package/src/api/transform-schema.ts

@@ -9,13 +9,14 @@ import {
 } from "../application/transform/footer/shared-enum-names.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { DocumentObject } from "../domain/openapi/document-object.js";
-import { OutputFix } from "../domain/output-fixes.js";
+import { FIX } from "../domain/output-fixes.js";
 import type { GlobalContext, OpenAPI3 } from "../types.js";
 import { FirstSchemaNameRecorder } from "./discriminator-enum-names.js";
 import { documentDeclarations, type TransformedDocument } from "./document-declarations.js";
 import { excludedValuesWarning } from "./enum-values-warnings.js";
 import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
 import { ContextFooterSink } from "./footer-sink.js";
+import type { RunContext } from "./run-context.js";
 import { createTransformContext } from "./transform-context.js";
 
 const OPERATIONS_NAME = "operations";
@@ -46,11 +47,11 @@ interface EnumNameRecorder extends SharedEnumNames {
  */
 function sharedEnumNamesOf(
   document: DocumentObject,
-  ctx: GlobalContext,
+  ctx: RunContext,
   recorder: EnumNameRecorder,
 ): SharedEnumNames {
   const injectFooter: FooterEntry[] = [];
-  const scratch: GlobalContext = {
+  const scratch: RunContext = {
     ...ctx,
     injectFooter,
     runFooter: new RunFooter(new ContextFooterSink(injectFooter), true, recorder),
@@ -64,14 +65,14 @@ function sharedEnumNamesOf(
 
 /** The recorder of the run's fixes, or null where the first schema's name needs no first pass. */
 function enumNameRecorderOf(ctx: GlobalContext): EnumNameRecorder | null {
-  if (ctx.fix?.includes(OutputFix.DEDUPE_ENUM_NAMES)) {
+  if (ctx.fix?.includes(FIX.DEDUPE_ENUM_NAMES)) {
     return new SharedEnumNameRecorder();
   }
-  return ctx.fix?.includes(OutputFix.DISCRIMINATOR_VALUES) ? new FirstSchemaNameRecorder() : null;
+  return ctx.fix?.includes(FIX.DISCRIMINATOR_VALUES) ? new FirstSchemaNameRecorder() : null;
 }
 
 /** With a naming fix, `--enum` and `--dedupe-enums`, the run's footer names shared enums. */
-function withSharedEnumNames(document: DocumentObject, ctx: GlobalContext): void {
+function withSharedEnumNames(document: DocumentObject, ctx: RunContext): void {
   const recorder = ctx.runFooter === undefined ? enumNameRecorderOf(ctx) : null;
   if (recorder === null || !ctx.enum || !ctx.dedupeEnums) {
     return;
@@ -87,7 +88,7 @@ function withSharedEnumNames(document: DocumentObject, ctx: GlobalContext): void
 function enumValuesChecked(
   body: readonly IrDeclaration[],
   footer: FooterEntry[],
-  ctx: GlobalContext,
+  ctx: RunContext,
 ): FooterEntry[] {
   if (!ctx.enumValues) {
     return footer;
@@ -102,7 +103,7 @@ function enumValuesChecked(
 }
 
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
-export function transformDocument(schema: OpenAPI3, ctx: GlobalContext): TransformedDocument {
+export function transformDocument(schema: OpenAPI3, ctx: RunContext): TransformedDocument {
   const document = schema as DocumentObject;
   withSharedEnumNames(document, ctx);
   const context = createTransformContext(ctx);

package/src/application/ports/deprecation-reporter.ts

@@ -0,0 +1,9 @@
+import type { DeprecationCode } from "../../domain/deprecations.js";
+
+/**
+ * Where the generator reports the use of something 2.0 removes (ENGINEERING_PLAN 4.5). The
+ * adapter decides how often a code is shown; the Node.js one shows each code once per process.
+ */
+export interface DeprecationReporter {
+  report(code: DeprecationCode, message: string): void;
+}

package/src/application/print/type-printer.ts

@@ -1,4 +1,5 @@
 import { assertNever } from "../../domain/assert-never.js";
+import { DEFAULT_STRING_ENCODING } from "../../domain/ir/constructors.js";
 import type {
   IrIndexedAccessType,
   IrMember,
@@ -196,7 +197,7 @@ function printLeafType(type: IrLeafType): string {
     case "keyword":
       return type.keyword;
     case "stringLiteral":
-      return printStringLiteral(type.value, type.encoding);
+      return printStringLiteral(type.value, type.encoding ?? DEFAULT_STRING_ENCODING);
     case "numberLiteral":
       return printNumberLiteral(type.value);
     case "booleanLiteral":

package/src/application/transform/document/components.ts

@@ -19,7 +19,7 @@ import {
   singularizeComponentKind,
 } from "../../../domain/openapi/components-object.js";
 import { createRef } from "../../../domain/openapi/json-pointer.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { type DeprecatedEntryFilter, documentEntries } from "../document-entries.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
 import { transformSchema } from "../schema/schema-transform.js";
@@ -174,7 +174,7 @@ export function componentsType(
   // A plain object, as in the original: its key order (integer-like names first) is the
   // output order.
   const aliases: Record<string, IrTypeAliasDeclaration> = {};
-  const displaced = context.options.fixes.has(OutputFix.ROOT_TYPE_NUMBERING) ? [] : null;
+  const displaced = context.options.fixes.has(FIX.ROOT_TYPE_NUMBERING) ? [] : null;
   const isKept = (item: unknown) => kept.has(item as object);
   const request = { components, isKept, aliases, displaced };
   const declaredKinds = DECLARED_COMPONENT_KINDS.filter((kind) => components[kind] !== undefined);

package/src/application/transform/document/parameters.ts

@@ -16,7 +16,7 @@ import {
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
 import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { refType } from "../ref-type.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
 import { withSchemaComment } from "../schema-comment.js";
@@ -24,7 +24,8 @@ import type { TransformContext } from "../transform-context.js";
 import { isExplodedQueryObject } from "./exploded-query.js";
 import { parameterType } from "./parameter.js";
 
-const PATH_TEMPLATE_RE = /\{([^}]+)\}/g;
+/** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
+const PATH_TEMPLATE_RE = /\{([^{}]+)\}/g;
 
 /** A parameter as written in the document, and the object its `$ref` points to. */
 interface ParameterEntry {
@@ -165,7 +166,7 @@ function querystringMember(
 /** With `exploded-query-objects`, whether the parameter's object keys are keys of `query`. */
 function isExplodedEntry(entry: ResolvedEntry, context: TransformContext): boolean {
   return (
-    context.options.fixes.has(OutputFix.EXPLODED_QUERY_OBJECTS) &&
+    context.options.fixes.has(FIX.EXPLODED_QUERY_OBJECTS) &&
     isExplodedQueryObject(entry.resolved, context.refs)
   );
 }

package/src/application/transform/document/paths.ts

@@ -14,7 +14,7 @@ import {
   pathItemOperations,
 } from "../../../domain/openapi/path-item-object.js";
 import type { ReferenceSchema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { documentEntries } from "../document-entries.js";
 import { refType } from "../ref-type.js";
 import type { TransformContext } from "../transform-context.js";
@@ -35,7 +35,8 @@ import {
 } from "./path-template-replace.js";
 import { assignabilityProof } from "./type-assignability.js";
 
-const PATH_PARAMETER_RE = /\{[^}]+\}/g;
+/** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
+const PATH_PARAMETER_RE = /\{[^{}]+\}/g;
 
 /** Placeholders by parameter schema type; anything else is a string placeholder. */
 const PLACEHOLDERS: ReadonlyMap<unknown, PathPlaceholder> = new Map([
@@ -111,7 +112,7 @@ function pathTemplateParts(
     const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
     return { match, type: PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER };
   });
-  return context.options.fixes.has(OutputFix.PATH_PARAM_TYPE_NAMES)
+  return context.options.fixes.has(FIX.PATH_PARAM_TYPE_NAMES)
     ? splitTemplateParts(url, matches)
     : replacedTemplateParts(url, matches);
 }