openapi-typesafe 1.0.0-rc.3 → 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

@@ -3,7 +3,10 @@ import { createConfig, type Config as RedoclyConfig } from "@redocly/openapi-cor
 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";
 
@@ -18,13 +21,26 @@ 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,
   });
 }
 
@@ -40,14 +56,27 @@ export function defaultDeprecationReporter(): DeprecationReporter {
  */
 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-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,4 +1,5 @@
 import type { Logger } from "../application/ports/logger.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";
@@ -104,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,5 +1,6 @@
 import type { Logger } from "../application/ports/logger.js";
 import { isUnionMember, unionAt } from "../domain/openapi/discriminated-union.js";
+import { appendPointer, canonicalRef, ROOT_POINTER } from "../domain/openapi/json-pointer.js";
 import { FIX } from "../domain/output-fixes.js";
 import type {
   DiscriminatorObject,
@@ -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);
 }
 
@@ -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

@@ -34,9 +34,10 @@ export interface GeneratorPorts {
   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;
 }
 
@@ -156,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,
@@ -181,5 +182,5 @@ export async function createDocumentRun(
     logger,
     deprecations: ports.deprecations,
   };
-  return { schema, ctx };
+  return { schema, localFiles, ctx };
 }

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

@@ -18,21 +18,36 @@ 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 };
+}
+
+/** As `generateDocument`, the declarations only. */
+export async function generateDeclarations(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<IrDeclaration[]> {
+  return (await generateDocument(source, options, ports)).declarations;
 }
 
 /**

package/src/api/run-context.ts

@@ -1,6 +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";
 
 /**
@@ -26,6 +27,8 @@ 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). */

package/src/api/schema-callbacks.ts

@@ -9,10 +9,10 @@ import type {
 } from "../application/transform/schema/schema-context.js";
 import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
 import { irRaw } from "../domain/ir/constructors.js";
+import { isPrintableIrProperty, isPrintableIrType } from "../domain/ir/ir-shape.js";
 import type { IrPropertySignature, IrType } from "../domain/ir/nodes.js";
 import type {
   GlobalContext,
-  IrCallbackType,
   IrPostTransform,
   IrTransform,
   IrTransformProperty,
@@ -29,13 +29,15 @@ import { toIrType } from "./type-helpers.js";
  * their results are read by the bridge.
  */
 
+/** What a legacy `transformProperty` result fails to be. */
+const LEGACY_PROPERTY_PROBLEM = "a property with syntax the generator cannot read";
+
+/** A `transformProperty` result the generator cannot print as a property. */
 export class UnreadablePropertyError extends OpenAPITypesafeError {
-  constructor(path: string | undefined) {
+  constructor(path: string | undefined, problem = LEGACY_PROPERTY_PROBLEM) {
     super({
       code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
-      message:
-        `transformProperty at ${path} returned a property ` +
-        "with syntax the generator cannot read",
+      message: `transformProperty at ${path} returned ${problem}`,
       details: { callback: "transformProperty", path },
     });
     this.name = "UnreadablePropertyError";
@@ -44,16 +46,26 @@ export class UnreadablePropertyError extends OpenAPITypesafeError {
 
 /** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */
 export class UnreadableTypeError extends OpenAPITypesafeError {
-  constructor(callback: "transform" | "postTransform", path: string | undefined) {
+  constructor(
+    callback: "transform" | "postTransform",
+    path: string | undefined,
+    expected = "a TypeScript node",
+  ) {
     super({
       code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
-      message: `${callback} at ${path} returned a value that is not a TypeScript node`,
+      message: `${callback} at ${path} returned a value that is not ${expected}`,
       details: { callback, path },
     });
     this.name = "UnreadableTypeError";
   }
 }
 
+/** What an IR type result must be (docs/node.md, IR callbacks). */
+const IR_TYPE_EXPECTED = "an IR type or non-empty type text";
+
+/** What an IR property result must be. */
+const IR_PROPERTY_PROBLEM = "a value that is not an IR property the generator can print";
+
 function nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {
   return { ...location, ctx } as TransformNodeOptions;
 }
@@ -63,24 +75,50 @@ export function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
   return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);
 }
 
-/** An IR callback type; text is a raw type, printed as written. */
-function fromCallbackType(type: IrCallbackType): IrType {
-  return typeof type === "string" ? irRaw(type) : type;
+/**
+ * An IR callback type; text is a raw type, printed as written. Any other value, and IR the
+ * printer cannot write as TypeScript, fails with `CALLBACK_RESULT_UNREADABLE` (`ir-shape.ts`).
+ */
+function fromCallbackType(
+  callback: "transform" | "postTransform",
+  type: unknown,
+  location: SchemaLocation,
+): IrType {
+  const candidate = typeof type === "string" ? irRaw(type) : type;
+  if (!isPrintableIrType(candidate)) {
+    throw new UnreadableTypeError(callback, location.path, IR_TYPE_EXPECTED);
+  }
+  return candidate;
 }
 
-function irCustomType(result: ReturnType<IrTransform>): CustomType | null {
+function irCustomType(result: unknown, location: SchemaLocation): CustomType | null {
   if (result === undefined || result === null) {
     return null;
   }
   if (typeof result === "object" && "schema" in result) {
-    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };
+    const { schema, questionToken } = result as { schema: unknown; questionToken?: unknown };
+    return {
+      type: fromCallbackType("transform", schema, location),
+      isOptional: Boolean(questionToken),
+    };
   }
-  return { type: fromCallbackType(result), isOptional: false };
+  return { type: fromCallbackType("transform", result, location), isOptional: false };
+}
+
+function irProperty(result: unknown, location: SchemaLocation): IrPropertySignature | null {
+  if (result === undefined || result === null) {
+    return null;
+  }
+  if (!isPrintableIrProperty(result)) {
+    throw new UnreadablePropertyError(location.path, IR_PROPERTY_PROBLEM);
+  }
+  return result;
 }
 
 /**
  * The context fields hold either callback form; `irCallbacks` says which one, so the casts below
- * only name the form the user declared with `OpenAPITSIrOptions`.
+ * only name the form the user declared with `OpenAPITSIrOptions`. The results are checked, since
+ * JavaScript callers can return any value.
  */
 function irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
   const transform = ctx.transform as IrTransform | undefined;
@@ -89,14 +127,19 @@ function irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {
   return {
     transform: (schema, location) =>
       transform
-        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)))
+        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)), location)
         : null,
     postTransform(type, location) {
       const result = postTransform?.(type, nodeOptions(ctx, location));
-      return result === undefined ? null : fromCallbackType(result);
+      return result === undefined ? null : fromCallbackType("postTransform", result, location);
     },
     transformProperty: (property, schema, location) =>
-      transformProperty?.(property, schema as SchemaObject, nodeOptions(ctx, location)) ?? null,
+      transformProperty
+        ? irProperty(
+            transformProperty(property, schema as SchemaObject, nodeOptions(ctx, location)),
+            location,
+          )
+        : null,
   };
 }
 

package/src/api/transform-context.ts

@@ -11,6 +11,8 @@ import type {
   TransformDiagnostics,
   TransformOptions,
 } from "../application/transform/transform-context.js";
+import { canonicalRef } from "../domain/openapi/json-pointer.js";
+import { SCHEMA_DIALECTS } from "../domain/openapi/schema-dialect.js";
 import type { TransformNodeOptions } from "../types.js";
 import { defaultLogger, monotonicNow } from "./default-ports.js";
 import { ContextFooterSink } from "./footer-sink.js";
@@ -40,6 +42,7 @@ function transformOptions(ctx: RunContext): TransformOptions {
     immutable: ctx.immutable,
     propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,
     readWriteMarkers: ctx.readWriteMarkers,
+    schemaDialect: ctx.schemaDialect ?? SCHEMA_DIALECTS.OPENAPI_3_0,
     generatePathParams: ctx.generatePathParams,
     pathParamsAsTypes: ctx.pathParamsAsTypes,
     rootTypes: ctx.rootTypes,
@@ -76,9 +79,10 @@ export function createTransformContext(ctx: RunContext): TransformContext {
     options: transformOptions(ctx),
     refs: { resolve: (ref) => ctx.resolve(ref) },
     discriminators: {
-      objectAt: (ref) => ctx.discriminators.objects[ref],
-      isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
-      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],
+      // The scan keys pointers canonically; a caller may pass a `$ref` as the document writes it.
+      objectAt: (ref) => ctx.discriminators.objects[canonicalRef(ref)],
+      isHandled: (ref) => ctx.discriminators.refsHandled.includes(canonicalRef(ref)),
+      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[canonicalRef(ref)] ?? [],
       enumParentOf: (schema) =>
         ctx.discriminators.enumParents?.get(schema) as DiscriminatorEnumParent | undefined,
     },