openapi-typesafe 1.0.0-rc.2 → 1.0.0-rc.4

package/src/adapters/redocly-loader/schema-source.ts

@@ -17,6 +17,8 @@ import {
   pathStringError,
   sourceEmptyError,
   sourceInvalidError,
+  type TextOrigin,
+  urlInvalidError,
 } from "./schema-load-errors.js";
 
 /** Parse a schema source of any supported type into a Redocly document (ENGINEERING_PLAN 4.5). */
@@ -24,6 +26,8 @@ import {
 export interface ParseSchemaOptions {
   absoluteRef: string;
   resolver: BaseResolver;
+  /** Where document text came from, for the message of text that is only a string. */
+  textOrigin?: TextOrigin;
 }
 
 /**
@@ -38,21 +42,28 @@ async function readStream(stream: Readable, absoluteRef: string): Promise<string
   }
 }
 
-const URL_PREFIXES = ["http://", "https://", "file://"] as const;
+/** A URL source string; a scheme is the same in any case (RFC 3986, section 3.1). */
+const URL_PREFIX_RE = /^(?:https?|file):\/\//i;
 
-/** A string is a URL, JSON (starts with `{`) or YAML. */
+/**
+ * A string is a URL, JSON (starts with `{`) or YAML. A string that starts like a URL but does not
+ * parse as one fails with `SCHEMA_SOURCE_INVALID`, not the parser's `TypeError`.
+ */
 function parseSchemaText(
   schema: string,
   options: ParseSchemaOptions,
 ): Promise<Document> | Document {
-  if (URL_PREFIXES.some((prefix) => schema.startsWith(prefix))) {
-    const url = new URL(schema);
+  if (URL_PREFIX_RE.test(schema)) {
+    const url = URL.parse(schema);
+    if (url === null) {
+      throw urlInvalidError(schema);
+    }
     const absoluteRef = url.protocol === "file:" ? fileURLToPath(url) : url.href;
     return parseSchema(url, { absoluteRef, resolver: options.resolver });
   }
   return schema[0] === "{"
     ? parseJsonText(schema, options.absoluteRef)
-    : parseYamlText(schema, options.absoluteRef);
+    : parseYamlText(schema, options.absoluteRef, options.textOrigin ?? "string");
 }
 
 function parseJsonText(text: string, absoluteRef: string): Document {
@@ -63,7 +74,7 @@ function parseJsonText(text: string, absoluteRef: string): Document {
   }
 }
 
-function parseYamlText(text: string, absoluteRef: string): Document {
+function parseYamlText(text: string, absoluteRef: string, origin: TextOrigin): Document {
   let document: Document;
   try {
     document = makeDocumentFromString(text, absoluteRef);
@@ -72,7 +83,7 @@ function parseYamlText(text: string, absoluteRef: string): Document {
   }
   // Text that is only a YAML string scalar, such as "./openapi.yaml", was meant as a file path.
   if (typeof document.parsed === "string") {
-    throw pathStringError(text);
+    throw pathStringError(text, origin);
   }
   const failure = aliasExpansionFailure(document.parsed);
   if (failure !== undefined) {
@@ -139,7 +150,8 @@ export async function parseSchema(schema: unknown, options: ParseSchemaOptions):
     return resolveSchemaURL(options);
   }
   if (schema instanceof Readable) {
-    return parseSchema(await readStream(schema, options.absoluteRef), options);
+    const text = await readStream(schema, options.absoluteRef);
+    return parseSchema(text, { ...options, textOrigin: "stream" });
   }
   if (schema instanceof Buffer) {
     return parseSchema(schema.toString("utf8"), options);

package/src/adapters/redocly-loader/unsupported-keys.ts

@@ -1,4 +1,5 @@
 import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
 
 /**
  * Keys Redocly 1.34 cannot walk. It looks up the type of every key with `type.properties[key]`,
@@ -57,11 +58,6 @@ interface PendingNode {
   readonly pointer: string;
 }
 
-/** RFC 6901: `~` becomes `~0` and `/` becomes `~1`. */
-function escapePointerSegment(segment: string): string {
-  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
-}
-
 /**
  * The unsupported keys of one parsed document. The walk uses its own stack, so a deeply nested
  * document is checked without running out of call stack; nodes shared by YAML aliases are checked
@@ -77,10 +73,10 @@ function unsupportedKeysOf(document: LoadedDocument): UnsupportedKey[] {
       pending.push({ value, pointer });
     }
   };
-  enqueue(document.parsed, "#");
+  enqueue(document.parsed, ROOT_POINTER);
   for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
     for (const [key, child] of Object.entries(node.value)) {
-      const pointer = `${node.pointer}/${escapePointerSegment(key)}`;
+      const pointer = childPointer(node.pointer, key);
       if (isUnsupportedEntry(key, child)) {
         found.push({ key, pointer, source: document.source });
       }

package/src/adapters/terminal-logger/terminal-logger.ts

@@ -1,6 +1,6 @@
 import colors from "ansi-colors";
 import type { DebugGroup, Logger } from "../../application/ports/logger.js";
-import { redactUrlCredentials } from "../../domain/url-credentials.js";
+import { redactUrlSecrets } from "../../domain/url-secrets.js";
 
 /**
  * The Logger port on a terminal, with the original output format: ` ⚠  ` warnings, ` ✘  `
@@ -16,7 +16,10 @@ export interface TerminalSink {
 }
 
 export interface TerminalLoggerOptions {
-  /** Drop warnings (errors and debug lines are still written). */
+  /**
+   * Drop warnings and error lines; debug lines, which `DEBUG` asks for, are still written. The
+   * error lines are the problems of a document that fails to load, which the thrown error lists.
+   */
   readonly silent: boolean;
   /** The value of `DEBUG`: `*`, `openapi-ts:*` or `openapi-ts:<group>` turn debug lines on. */
   readonly debugFilter: string | undefined;
@@ -81,18 +84,20 @@ class TerminalLogger implements Logger {
     // The original wrote no space without a duration (`openapi-ts:lintIgnored …`).
     const time =
       durationMs === undefined ? " " : this.#palette.green(` ${formatDuration(durationMs)} `);
-    const text = redactUrlCredentials(message);
+    const text = redactUrlSecrets(message);
     this.#options.sink.debug(`  ${this.#palette.bold(name)}${time}${text}`);
   }
 
   warn(message: string): void {
     if (!this.#options.silent) {
-      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${redactUrlCredentials(message)}`));
+      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${redactUrlSecrets(message)}`));
     }
   }
 
   error(message: string): void {
-    this.#options.sink.error(this.#palette.red(` ✘  ${redactUrlCredentials(message)}`));
+    if (!this.#options.silent) {
+      this.#options.sink.error(this.#palette.red(` ✘  ${redactUrlSecrets(message)}`));
+    }
   }
 }
 

package/src/api/default-ports.ts

@@ -1,8 +1,13 @@
 import { performance } from "node:perf_hooks";
 import { createConfig, type Config as RedoclyConfig } from "@redocly/openapi-core";
 import supportsColor from "supports-color";
+import { createNodeDeprecationReporter } from "../adapters/node-deprecations/node-deprecations.js";
 import type { RemoteDocumentLimits } from "../adapters/redocly-loader/remote-fetch.js";
-import { createTerminalLogger } from "../adapters/terminal-logger/terminal-logger.js";
+import {
+  createTerminalLogger,
+  type TerminalSink,
+} from "../adapters/terminal-logger/terminal-logger.js";
+import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
 import type { Logger } from "../application/ports/logger.js";
 
 /**
@@ -16,16 +21,34 @@ export function terminalSupportsColor(): boolean {
   return Boolean(stdout) && stdout !== false && stdout.hasBasic !== false;
 }
 
-/** The terminal logger with `DEBUG` from the environment, writing to the console. */
+/**
+ * Every line of the logger goes to stderr: the CLI writes the types to stdout, and `console.debug`
+ * writes there too, so debug lines would end up inside the generated file.
+ */
+const STDERR_SINK: TerminalSink = {
+  // biome-ignore lint/suspicious/noConsole: the terminal logger's own channel
+  debug: (line) => console.error(line),
+  // biome-ignore lint/suspicious/noConsole: the terminal logger's own channel
+  warn: (line) => console.warn(line),
+  // biome-ignore lint/suspicious/noConsole: the terminal logger's own channel
+  error: (line) => console.error(line),
+};
+
+/** The terminal logger with `DEBUG` from the environment, writing to stderr. */
 export function defaultLogger(silent: boolean): Logger {
   return createTerminalLogger({
     silent,
     debugFilter: process.env.DEBUG,
     useColors: terminalSupportsColor(),
-    sink: console,
+    sink: STDERR_SINK,
   });
 }
 
+/** Deprecations as Node.js `DeprecationWarning`s, each code once per process. */
+export function defaultDeprecationReporter(): DeprecationReporter {
+  return createNodeDeprecationReporter();
+}
+
 /**
  * How long one remote `$ref` (or a remote source) may take to load. Large documents (the 27 MB
  * Cloudflare spec) download in seconds; a minute covers slow hosts, while Node's own fetch would
@@ -33,14 +56,27 @@ export function defaultLogger(silent: boolean): Logger {
  */
 export const REMOTE_REF_TIMEOUT_MS = 60_000;
 
+const MEBIBYTE = 1024 * 1024;
+
 /**
- * Bounds on the remote documents of one run (ADR-033). Large split documents have a few thousand
+ * Bounds on the remote documents of one schema (ADR-033). Large split documents have a few thousand
  * files, so 10,000 leaves room and still ends an endless fan-out. 16 parallel fetches keep a
  * multi-file document fast without exhausting local ports.
+ *
+ * The size limits count decoded bytes and parsed nodes (threat model T2, ADR-033 decision 6).
+ * The largest document of the 1,820-entry compatibility corpus is Microsoft Graph beta: 71 MiB,
+ * 2.65 million nodes (keys and values), 1.6 GB peak memory when loaded from a URL. A remote body
+ * took about 7 bytes of memory per byte of text and 110 per node in our measurements, so 128 MiB
+ * per document (1.8 times Graph beta), 256 MiB per schema (a split document may be twice as
+ * large) and 8 million nodes per schema (3 times Graph beta) let crafted documents finish within
+ * a heap of 2 GB; with the default heap of 4 GB they peak at about 1.2 to 2.3 GB.
  */
 export const DEFAULT_REMOTE_DOCUMENT_LIMITS: RemoteDocumentLimits = {
   maxDocuments: 10_000,
   maxParallelFetches: 16,
+  maxDocumentBytes: 128 * MEBIBYTE,
+  maxTotalBytes: 256 * MEBIBYTE,
+  maxNodes: 8_000_000,
 };
 
 /** The working directory of the process: the default `cwd` of an inline source. */

package/src/api/discriminator-conflict-warnings.ts

@@ -3,7 +3,7 @@ import {
   type DiscriminatorValueConflict,
   findDiscriminatorValueConflicts,
 } from "../domain/openapi/discriminator-conflicts.js";
-import { OutputFix } from "../domain/output-fixes.js";
+import { FIX, type OutputFix } from "../domain/output-fixes.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
 
 const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
@@ -36,7 +36,7 @@ export function warnDiscriminatorValueConflicts(
   fixes: readonly OutputFix[],
   logger: Logger,
 ): void {
-  const isUnionReused = fixes.includes(OutputFix.ALLOF_DISCRIMINATED_UNION);
+  const isUnionReused = fixes.includes(FIX.ALLOF_DISCRIMINATED_UNION);
   for (const conflict of findDiscriminatorValueConflicts(document, { isUnionReused })) {
     logger.warn(warningText(warningOf(conflict), WARNING_CODES.DISCRIMINATOR_VALUE_NOT_ALLOWED));
   }

package/src/api/discriminator-enum-parent.ts

@@ -1,4 +1,4 @@
-import { createRef, parseRefPointer } from "../domain/openapi/json-pointer.js";
+import { appendPointer, parseRefPointer, ROOT_POINTER } from "../domain/openapi/json-pointer.js";
 import type { SchemaObject } from "../types.js";
 import type { EnumPatch } from "./discriminator-enum.js";
 
@@ -31,7 +31,7 @@ const ROOT_SEGMENTS = 3;
 function typedAt(ref: string): string {
   const segments = parseRefPointer(ref);
   const nested = segments.slice(ROOT_SEGMENTS).filter((segment) => segment !== PROPERTIES_KEYWORD);
-  return createRef([...segments.slice(0, ROOT_SEGMENTS), ...nested]);
+  return appendPointer(ROOT_POINTER, [...segments.slice(0, ROOT_SEGMENTS), ...nested]);
 }
 
 function isSchemaObject(value: unknown): value is SchemaObject {
@@ -41,7 +41,7 @@ function isSchemaObject(value: unknown): value is SchemaObject {
 /** The property `name` of a schema object typed at `ref`. */
 function ownProperty(item: SchemaObject, ref: string, name: string): DeclaredProperty | undefined {
   const property = ("properties" in item ? item.properties : undefined)?.[name];
-  return property === undefined ? undefined : { property, path: createRef([ref, name]) };
+  return property === undefined ? undefined : { property, path: appendPointer(ref, [name]) };
 }
 
 /** The property `name` of the schema at `ref`, its own or from an `allOf` item, depth first. */

package/src/api/discriminator-other-owners.ts

@@ -1,3 +1,5 @@
+import { appendAll } from "../domain/append-all.js";
+import { canonicalRef } from "../domain/openapi/json-pointer.js";
 import type { DiscriminatorObject, ReferenceObject, SchemaObject } from "../types.js";
 import type { EnumPatch } from "./discriminator-enum.js";
 import { enumKey, patchDiscriminatorEnum, type ScanState } from "./discriminator-patch.js";
@@ -22,7 +24,7 @@ function allOfRefs(state: ScanState, ref: string): string[] {
   const schema = resolveDocumentRef<SchemaObject>(state.schema, ref, { silent, logger });
   const items = (schema?.allOf ?? []) as (SchemaObject | ReferenceObject)[];
   return items.flatMap((item) =>
-    "$ref" in item && typeof item.$ref === "string" ? [item.$ref] : [],
+    "$ref" in item && typeof item.$ref === "string" ? [canonicalRef(item.$ref)] : [],
   );
 }
 
@@ -45,7 +47,7 @@ function otherOwners(state: ScanState, parentRef: string): OtherOwner[] {
     if (discriminator && name !== undefined && name !== own && !found.has(name)) {
       found.set(name, { discriminator, ownerRef: ref });
     }
-    queue.push(...allOfRefs(state, ref));
+    appendAll(queue, allOfRefs(state, ref));
   }
   return [...found.values()];
 }
@@ -75,7 +77,7 @@ export function inheritOtherOwners(state: ScanState, parentRef: string, ref: str
     }
     recordOtherProperty(state, ref, discriminator.propertyName);
     const mapped = Object.entries(discriminator.mapping ?? {})
-      .filter(([, target]) => target === ref)
+      .filter(([, target]) => canonicalRef(target) === ref)
       .map(([value]) => value);
     const name = ref.slice(ref.lastIndexOf("/") + 1);
     const patch: EnumPatch = { ref, values: mapped, discriminator, discriminatorRef: ownerRef };

package/src/api/discriminator-patch.ts

@@ -1,5 +1,6 @@
 import type { Logger } from "../application/ports/logger.js";
-import { OutputFix } from "../domain/output-fixes.js";
+import { appendAll } from "../domain/append-all.js";
+import { FIX, type OutputFix } from "../domain/output-fixes.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import type { DiscriminatorObject, OpenAPI3, SchemaObject } from "../types.js";
 import { addEnumProperty, declaresValues, type EnumPatch } from "./discriminator-enum.js";
@@ -46,7 +47,7 @@ export interface ScanState extends DiscriminatorScanOptions {
 
 /** Whether `discriminator-values` is on: values of two discriminators merge into one enum. */
 export function mergesValues(state: ScanState): boolean {
-  return state.fixes.has(OutputFix.DISCRIMINATOR_VALUES);
+  return state.fixes.has(FIX.DISCRIMINATOR_VALUES);
 }
 
 function patchedSchema(state: ScanState, patch: EnumPatch): SchemaObject | undefined {
@@ -60,8 +61,7 @@ function patchedSchema(state: ScanState, patch: EnumPatch): SchemaObject | undef
  */
 function isDeclared(state: ScanState, patch: EnumPatch): boolean {
   return (
-    state.fixes.has(OutputFix.DISCRIMINATOR_VALUES) &&
-    declaresValues(patchedSchema(state, patch), patch)
+    state.fixes.has(FIX.DISCRIMINATOR_VALUES) && declaresValues(patchedSchema(state, patch), patch)
   );
 }
 
@@ -70,7 +70,7 @@ function isDeclared(state: ScanState, patch: EnumPatch): boolean {
  * added, or a discriminator object that a schema inherited.
  */
 export function recordEnumParent(state: ScanState, owner: DiscriminatorOwner, key: object): void {
-  if (!state.fixes.has(OutputFix.DISCRIMINATOR_VALUES)) {
+  if (!state.fixes.has(FIX.DISCRIMINATOR_VALUES)) {
     return;
   }
   const { silent, logger } = state;
@@ -105,7 +105,10 @@ function mergeIntoPatchedEnum(state: ScanState, key: string, values: readonly st
     return false;
   }
   const merged = patched.enum as unknown[];
-  merged.push(...values.filter((value) => !merged.includes(value)));
+  appendAll(
+    merged,
+    values.filter((value) => !merged.includes(value)),
+  );
   return true;
 }
 

package/src/api/discriminator-scan.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "../application/ports/logger.js";
 import { isUnionMember, unionAt } from "../domain/openapi/discriminated-union.js";
-import { OutputFix } from "../domain/output-fixes.js";
+import { appendPointer, canonicalRef, ROOT_POINTER } from "../domain/openapi/json-pointer.js";
+import { FIX } from "../domain/output-fixes.js";
 import type {
   DiscriminatorObject,
   GeneratorOptions,
@@ -22,7 +23,6 @@ import {
   type ScanState,
 } from "./discriminator-patch.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
@@ -39,9 +39,11 @@ function inferredMapping(oneOf: (SchemaObject | ReferenceObject)[]): Discriminat
     if (!("$ref" in item)) {
       continue;
     }
+    // The value is the name as the `$ref` writes it, as in the original.
     const value = item.$ref.split("/").pop();
+    const ref = canonicalRef(item.$ref);
     if (value) {
-      mapping[item.$ref] = { ...mapping[item.$ref], inferred: value };
+      mapping[ref] = { ...mapping[ref], inferred: value };
     }
   }
   return mapping;
@@ -52,10 +54,11 @@ function addDefinedMapping(
   mapping: DiscriminatorMapping,
   defined: Readonly<Record<string, string>>,
 ): void {
-  for (const [mappedValue, mappedRef] of Object.entries(defined)) {
-    if (!mappedRef) {
+  for (const [mappedValue, target] of Object.entries(defined)) {
+    if (!target) {
       continue;
     }
+    const mappedRef = canonicalRef(target);
     if (!mapping[mappedRef]?.defined) {
       mapping[mappedRef] = { defined: [] };
     }
@@ -94,7 +97,7 @@ function collectDiscriminator(
   if (!discriminator?.propertyName) {
     return;
   }
-  const discriminatorRef = createRef(path);
+  const discriminatorRef = appendPointer(ROOT_POINTER, path);
   state.objects[discriminatorRef] = discriminator;
   state.owners.add(discriminatorRef);
   if (!Array.isArray(value.oneOf)) {
@@ -110,7 +113,7 @@ function collectDiscriminator(
 /** 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)
+    .filter(([, mappedRef]) => canonicalRef(mappedRef) === ref)
     .map(([mappedValue]) => mappedValue);
 }
 
@@ -121,7 +124,7 @@ function valuesMappedTo(discriminator: DiscriminatorObject, ref: string): string
  * schema that the union's mapping names is a member.
  */
 function inheritsDiscriminator(state: ScanState, parentRef: string, ref: string): boolean {
-  if (!state.fixes.has(OutputFix.ALLOF_DISCRIMINATED_UNION)) {
+  if (!state.fixes.has(FIX.ALLOF_DISCRIMINATED_UNION)) {
     return true;
   }
   const resolve = (target: string) => resolveDocumentRef(state.schema, target, state);
@@ -141,7 +144,7 @@ function recordInherited(
   discriminator: DiscriminatorObject,
   ownerRef: string,
 ): void {
-  if (state.fixes.has(OutputFix.DISCRIMINATOR_VALUES) && state.owners.has(ref)) {
+  if (state.fixes.has(FIX.DISCRIMINATOR_VALUES) && state.owners.has(ref)) {
     return;
   }
   const inherited = { ...discriminator };
@@ -184,12 +187,17 @@ function inheritDiscriminators(
   }
   for (const item of value.allOf as (SchemaObject | ReferenceObject)[]) {
     if ("$ref" in item) {
-      if (!inheritFromRef(state, item.$ref, createRef(path))) {
+      if (!inheritFromRef(state, canonicalRef(item.$ref), appendPointer(ROOT_POINTER, path))) {
         return;
       }
     } else if (item.discriminator?.propertyName) {
       // The inline item is typed at the schema's own location.
-      recordInherited(state, createRef(path), item.discriminator, createRef(path));
+      recordInherited(
+        state,
+        appendPointer(ROOT_POINTER, path),
+        item.discriminator,
+        appendPointer(ROOT_POINTER, path),
+      );
     }
   }
 }

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";
@@ -25,15 +26,18 @@ import { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
 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. */
   readonly now: () => number;
 }
 
-/** A validated, bundled document and the context of one generator run. */
+/** A validated, bundled document, the local files it was read from, and the run's context. */
 export interface DocumentRun {
   readonly schema: OpenAPI3;
+  readonly localFiles: readonly URL[];
   readonly ctx: RunContext;
 }
 
@@ -47,6 +51,7 @@ type ContextFlags = Omit<
   | "runFooter"
   | "legacyCallbackWarnings"
   | "logger"
+  | "deprecations"
   | "fix"
 >;
 
@@ -152,7 +157,7 @@ export async function createDocumentRun(
   const fix = outputFixesOf(options, logger);
   const silent = options.silent ?? false;
   const cwd = sourceCwd(options);
-  const schema = await ports.loader.load({
+  const { document: schema, localFiles } = await ports.loader.load({
     source,
     cwd,
     shouldLint: options.lint ?? true,
@@ -175,6 +180,7 @@ export async function createDocumentRun(
     redoc: ports.redoc,
     resolve: ($ref) => resolveDocumentRef(schema, $ref, { silent, logger }),
     logger,
+    deprecations: ports.deprecations,
   };
-  return { schema, ctx };
+  return { schema, localFiles, ctx };
 }

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

@@ -1,6 +1,6 @@
-import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import { DEPRECATION_CODES, type DeprecationCode } from "../domain/deprecations.js";
 import type { LegacyCallbackName } from "../types.js";
-import { defaultLogger } from "./default-ports.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. */
@@ -13,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. ` +
@@ -20,14 +26,15 @@ function message(name: LegacyCallbackName): string {
   );
 }
 
-/** Warn once per run and callback; `silent` runs record the use but print nothing. */
+/**
+ * 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(
-    warningText(message(name), WARNING_CODES.LEGACY_CALLBACK_DEPRECATED),
-  );
+  (ctx.deprecations ?? defaultDeprecationReporter()).report(CODES[name], message(name));
 }

package/src/api/legacy-utils.ts

@@ -36,7 +36,11 @@ export function createDiscriminatorProperty(
   return discriminatorProperty(discriminator, path, readonly);
 }
 
-/** Create a $ref pointer (even from other $refs) */
+/**
+ * Create a $ref pointer (even from other $refs). A part that contains `#/` is read as a `$ref`
+ * and contributes its decoded segments, so it throws URIError for a malformed percent escape; any
+ * other part is one segment. To append raw document keys, escape each one instead.
+ */
 export function createRef(parts: (number | string | undefined | null)[]): string {
   return createDomainRef(parts);
 }

package/src/api/openapi-ts.ts

@@ -4,6 +4,7 @@ import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { GeneratorOptions, SchemaSource } from "../types.js";
 import {
   DEFAULT_REMOTE_DOCUMENT_LIMITS,
+  defaultDeprecationReporter,
   defaultLogger,
   defaultRedoclyConfig,
   monotonicNow,
@@ -17,24 +18,42 @@ import transformSchema from "./transform-schema.js";
  * `generateDeclarations` runs with any ports, which is how the CLI calls it.
  */
 
+/** The declarations of one document, and the local files it was read from. */
+export interface GeneratedDocument {
+  readonly declarations: IrDeclaration[];
+  readonly localFiles: readonly URL[];
+}
+
 /** Load, validate and bundle the source, then transform it into IR declarations. */
-export async function generateDeclarations(
+export async function generateDocument(
   source: SchemaSource,
   options: GeneratorOptions,
   ports: GeneratorPorts,
-): Promise<IrDeclaration[]> {
-  const { schema, ctx } = await createDocumentRun(source, options, ports);
+): Promise<GeneratedDocument> {
+  const { schema, localFiles, ctx } = await createDocumentRun(source, options, ports);
   const startedAt = ports.now();
-  const result = withStackOverflowReported("transform", () => transformSchema(schema, ctx));
+  const declarations = withStackOverflowReported("transform", () => transformSchema(schema, ctx));
   ports.logger.debug(
     "Completed AST transformation for entire document",
     "ts",
     ports.now() - startedAt,
   );
-  return result;
+  return { declarations, localFiles };
 }
 
-/** The default ports: the terminal logger, the given or default Redocly config, Redocly loading. */
+/** As `generateDocument`, the declarations only. */
+export async function generateDeclarations(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<IrDeclaration[]> {
+  return (await generateDocument(source, options, ports)).declarations;
+}
+
+/**
+ * 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());
@@ -45,7 +64,7 @@ export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<
     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

@@ -1,5 +1,7 @@
+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 { SchemaDialect } from "../domain/openapi/schema-dialect.js";
 import type { GlobalContext, LegacyCallbackName, SchemaObject } from "../types.js";
 
 /**
@@ -25,10 +27,14 @@ export interface RunContext extends GlobalContext {
      */
     readonly otherProperties?: Readonly<Record<string, readonly string[]>>;
   };
+  /** The schema dialect of the run's document; without it, OpenAPI 3.0 (`schemaDialectOf`). */
+  schemaDialect?: SchemaDialect;
   /** 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;
 }