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

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/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,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,
     },

package/src/api/transform-schema.ts

@@ -1,15 +1,25 @@
 import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
 import { documentBody, documentClosing } from "../application/transform/document/document.js";
+import {
+  NAMES_THE_OUTPUT_MAY_NEED,
+  namesTheOutputNeeds,
+  withEnumsRenamed,
+} from "../application/transform/document/enum-names-given-back.js";
+import { operationKeysWritten } from "../application/transform/document/operation-keys-written.js";
 import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
-import { RunFooter } from "../application/transform/footer/document-footer.js";
+import { RunFooter, type RunFooterNames } from "../application/transform/footer/document-footer.js";
+import { EnumNameClaims } from "../application/transform/footer/enum-name-claims.js";
 import { checkedEnumValues } from "../application/transform/footer/enum-values-check.js";
+import { OperationKeys } from "../application/transform/footer/operation-keys.js";
 import {
+  FIRST_SCHEMA_NAMES,
   SharedEnumNameRecorder,
   type SharedEnumNames,
 } 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 { schemaDialectOf } from "../domain/openapi/schema-dialect.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";
@@ -65,20 +75,52 @@ 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: RunContext): void {
-  const recorder = ctx.runFooter === undefined ? enumNameRecorderOf(ctx) : null;
-  if (recorder === null || !ctx.enum || !ctx.dedupeEnums) {
+/**
+ * The run's footer: with a naming fix, `--enum` and `--dedupe-enums` it names shared enums. A
+ * footer that a call before created on the context is kept.
+ */
+function withRunFooter(document: DocumentObject, ctx: RunContext, names: RunFooterNames): void {
+  if (ctx.runFooter !== undefined) {
     return;
   }
-  const names = sharedEnumNamesOf(document, ctx, recorder);
-  ctx.runFooter = new RunFooter(new ContextFooterSink(ctx.injectFooter), true, names);
+  const recorder = enumNameRecorderOf(ctx);
+  const shared =
+    recorder === null || !ctx.enum || !ctx.dedupeEnums
+      ? null
+      : sharedEnumNamesOf(document, ctx, recorder);
+  const sink = new ContextFooterSink(ctx.injectFooter);
+  ctx.runFooter =
+    shared === null
+      ? new RunFooter(sink, ctx.dedupeEnums, FIRST_SCHEMA_NAMES, names)
+      : new RunFooter(sink, true, shared, names);
+}
+
+/**
+ * The document with the enums renamed that gave way to a name the output turned out not to need
+ * (`EnumNameClaims`): they get that name back, as before.
+ */
+function withEnumNamesGivenBack(
+  parts: TransformedDocument,
+  names: RunFooterNames,
+): TransformedDocument {
+  const footer = parts.footer.filter(isIrDeclaration);
+  const renames = names.enums.givenBack(namesTheOutputNeeds({ ...parts, footer }));
+  if (renames.size === 0) {
+    return parts;
+  }
+  return {
+    body: withEnumsRenamed(parts.body, renames),
+    footer: parts.footer.map((entry) =>
+      isIrDeclaration(entry) ? (withEnumsRenamed([entry], renames)[0] ?? entry) : entry,
+    ),
+    closing: withEnumsRenamed(parts.closing, renames),
+  };
 }
 
 /**
@@ -105,14 +147,24 @@ function enumValuesChecked(
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
 export function transformDocument(schema: OpenAPI3, ctx: RunContext): TransformedDocument {
   const document = schema as DocumentObject;
-  withSharedEnumNames(document, ctx);
+  ctx.schemaDialect = schemaDialectOf(document.openapi);
+  const names: RunFooterNames = {
+    enums: new EnumNameClaims(NAMES_THE_OUTPUT_MAY_NEED),
+    operations: new OperationKeys(operationKeysWritten(document)),
+  };
+  withRunFooter(document, ctx, names);
   const context = createTransformContext(ctx);
   // documentBody registers the enums in the footer, so the footer is read after it.
   const rawBody = documentBody(document, context, () => ctx.injectFooter.filter(isIrDeclaration));
-  const footer = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
-  const closing = documentClosing(document, context, footer.some(isOperations));
-  const body = renameTakenAliases(rawBody, footer.filter(isIrDeclaration), closing);
-  return { body, footer, closing };
+  const rawFooter = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
+  const rawClosing = documentClosing(document, context, rawFooter.some(isOperations));
+  const parts = { body: rawBody, footer: rawFooter, closing: rawClosing };
+  const { body, footer, closing } = withEnumNamesGivenBack(parts, names);
+  return {
+    body: renameTakenAliases(body, footer.filter(isIrDeclaration), closing),
+    footer,
+    closing,
+  };
 }
 
 /**

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/ports/file-system.ts

@@ -10,3 +10,42 @@ export interface FileReader {
 export interface FileWriter {
   writeText(file: URL, contents: string): void;
 }
+
+/**
+ * Whether two `file:` locations name one file: also through a symbolic link, a hard link, or
+ * another letter case on a case-insensitive file system, and also when the file does not exist
+ * yet. The CLI asks before it writes, so that an output path never replaces a file the run reads
+ * (`CLI_OUTPUT_IS_INPUT`) nor another API's output (`CLI_OUTPUT_DUPLICATE`).
+ */
+export interface FileIdentity {
+  isSameFile(left: URL, right: URL): boolean;
+}
+
+/**
+ * Whether a `file:` location is an existing directory. An output there is no file the CLI can
+ * write, so it fails with `CLI_OUTPUT_INVALID` before anything is generated.
+ */
+export interface DirectoryCheck {
+  isDirectory(file: URL): boolean;
+}
+
+/**
+ * An output file that exists before its content is written: the claim created it, empty, when it
+ * was missing, so the file system has given it its own identity.
+ */
+export interface ClaimedFile {
+  /** The file system's identity of the file: equal for two paths that name one file. */
+  readonly identity: string;
+  /** Remove what the claim created (the file and its new directories); existing ones stay. */
+  release(): void;
+}
+
+/**
+ * Claim output files before writing to them. Names cannot prove that two missing files are two:
+ * the file system may ignore Unicode normalization, fold `ß` to `SS`, ignore letter case where
+ * nothing can be probed, or follow a link to a directory that does not exist yet. Once each file
+ * exists, its identity is the file system's own. Fails with `OUTPUT_WRITE_FAILED`.
+ */
+export interface FileClaims {
+  claimFile(file: URL): ClaimedFile;
+}

package/src/application/ports/schema-loader.ts

@@ -20,6 +20,16 @@ export interface SchemaLoadRequest {
   readonly refAccess: RefAccess;
 }
 
+/** A bundled document, and the local files read to build it. */
+export interface LoadedSchema {
+  readonly document: OpenAPI3;
+  /**
+   * The root, when it is a local file, and every local file a `$ref` loaded. The CLI keeps its
+   * output from replacing any of them (`CLI_OUTPUT_IS_INPUT`).
+   */
+  readonly localFiles: readonly URL[];
+}
+
 /**
  * Read, validate and bundle an OpenAPI 3 document into one document (ENGINEERING_PLAN 4.5).
  * Fails with a typed error (ADR-011): `SCHEMA_SOURCE_*`, `SCHEMA_LOAD_FAILED`,
@@ -28,5 +38,5 @@ export interface SchemaLoadRequest {
  * `SCHEMA_TOO_DEEP` or `SCHEMA_KEY_UNSUPPORTED`.
  */
 export interface SchemaLoader {
-  load(request: SchemaLoadRequest): Promise<OpenAPI3>;
+  load(request: SchemaLoadRequest): Promise<LoadedSchema>;
 }

package/src/application/print/text-writer.ts

@@ -22,7 +22,12 @@ export function isLineBreak(code: number): boolean {
  */
 export class TextWriter {
   readonly #options: PrintOptions;
-  #output = "";
+  /**
+   * The written parts, joined once at the end. A string built with `+=` is kept by V8 as a tree
+   * of its parts, several times the size of the text, for as long as the text is kept (until the
+   * CLI writes it); `join` gives one flat string.
+   */
+  #parts: string[] = [];
   #indent = 0;
   #isAtLineStart = true;
 
@@ -39,7 +44,9 @@ export class TextWriter {
   }
 
   get text(): string {
-    return this.#output;
+    const text = this.#parts.join("");
+    this.#parts = [text];
+    return text;
   }
 
   increaseIndent(): void {
@@ -61,7 +68,7 @@ export class TextWriter {
 
   /** Write text exactly as given. */
   rawWrite(text: string): void {
-    this.#output += text;
+    this.#parts.push(text);
     this.#updateLineStart(text);
   }
 

package/src/application/stack-overflow.ts

@@ -4,9 +4,11 @@ import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
  * Deeply nested schemas (ENGINEERING_PLAN 8.5). Loading, bundling, transforming and printing walk
  * schemas recursively, and Redocly follows each `$ref` inside the walk. On the default Node.js
  * stack, about 550 levels of inline schemas or a chain of about 900 `$ref`s (each schema refers to
- * the next) run out of call stack. Real documents stay far below: every YAML or JSON file goes
- * through the YAML parser, which stops at 100 levels, and the whole corpus passes. The overflow is
- * reported as a typed error instead of a `RangeError` with a stack trace.
+ * the next) run out of call stack. Redocly's walk also passes the keys of an object to one call as
+ * arguments, so a single object with more than about 100,000 keys runs out of it while loading.
+ * Real documents stay far below: every YAML or JSON file goes through the YAML parser, which stops
+ * at 100 levels, and the whole corpus passes. The overflow is reported as a typed error instead of
+ * a `RangeError` with a stack trace.
  */
 
 /** The step that ran out of call stack; named in the message and the details. */
@@ -20,13 +22,15 @@ export function isStackOverflowError(error: unknown): boolean {
   return error instanceof RangeError && STACK_OVERFLOW_MESSAGE.test(error.message);
 }
 
-/** The typed error for a document nested too deeply for the call stack. */
+/** The typed error for a document nested too deeply, or too wide, for the call stack. */
 export function schemaTooDeepError(step: DeepSchemaStep, cause: unknown): OpenAPITypesafeError {
+  const wide = step === "load" ? ", and so does an object with more than about 100,000 keys" : "";
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_TOO_DEEP,
     message:
       `The schema is nested too deeply to ${step}: the call stack ran out. Both inline ` +
-      "schemas and chains of $ref (each schema referring to the next) count; shorten the deepest.",
+      `schemas and chains of $ref (each schema referring to the next) count${wide}; shorten ` +
+      "the deepest.",
     details: { step },
     cause,
   });

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

@@ -18,8 +18,8 @@ import {
   isEnumSchema,
   singularizeComponentKind,
 } from "../../../domain/openapi/components-object.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.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";
@@ -62,7 +62,7 @@ function componentMember(
   item: unknown,
   context: TransformContext,
 ): IrPropertySignature {
-  const location = { path: createRef(["components", kind, name]), schema: item };
+  const location = { path: appendPointer(ROOT_POINTER, ["components", kind, name]), schema: item };
   const type = COMPONENT_TRANSFORMS[kind](item as never, location, context);
   const custom = context.callbacks.transform(item, location);
   const property = irProperty(toPropertyName(name), custom?.type ?? type, {
@@ -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/declared-type-names.ts

@@ -0,0 +1,36 @@
+import type { IrDeclaration } from "../../../domain/ir/nodes.js";
+
+/**
+ * The type names that declarations of the output take. Two declarations of one type name do not
+ * compile (TS2300, TS2567), or merge into one type without an error (two enums, two interfaces).
+ */
+
+/**
+ * A declaration at the start of a line of raw text: the helper types, the `--read-write-markers`
+ * types, `inject` text and footer nodes from user code. A `const` lives in the value namespace.
+ */
+const RAW_TYPE_DECLARATION_RE =
+  /^(?:export\s+)?(?:declare\s+)?(?:type|interface|enum|const\s+enum|class)\s+([A-Za-z_$][\w$]*)/gm;
+
+/** The type names that raw declaration text declares. */
+export function typeNamesInText(text: string): string[] {
+  return [...text.matchAll(RAW_TYPE_DECLARATION_RE)].map((match) => match[1] ?? "");
+}
+
+function typeNamesOf(declaration: IrDeclaration): readonly string[] {
+  switch (declaration.kind) {
+    case "rawDeclaration":
+      return declaration.name === undefined
+        ? typeNamesInText(declaration.text)
+        : [declaration.name];
+    case "constArray":
+      return [];
+    default:
+      return [declaration.name];
+  }
+}
+
+/** Every type name the declarations take; `--enum-values` arrays are values, so they take none. */
+export function typeNamesDeclaredBy(declarations: readonly IrDeclaration[]): Set<string> {
+  return new Set(declarations.flatMap(typeNamesOf));
+}

package/src/application/transform/document/defs-root.ts

@@ -1,7 +1,7 @@
 import { irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrObjectType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { Schema } from "../../../domain/openapi/schema-object.js";
 import { transformSchema } from "../schema/schema-transform.js";
 import type { TransformContext } from "../transform-context.js";
@@ -17,7 +17,7 @@ export function defsRootType(
   context: TransformContext,
 ): IrObjectType {
   const members = Object.entries(defs).map(([name, schema]) => {
-    const location = { path: createRef(["$defs", name]), schema };
+    const location = { path: appendPointer(ROOT_POINTER, ["$defs", name]), schema };
     const type = transformSchema(schema, location, context);
     return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
   });

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

@@ -1,3 +1,4 @@
+import { appendAll } from "../../../domain/append-all.js";
 import { irKeyword, irObject, irRecord } from "../../../domain/ir/constructors.js";
 import type {
   IrDeclaration,
@@ -20,10 +21,10 @@ import { apiPathsEnumDeclaration } from "./paths-enum.js";
 import { webhooksType } from "./webhooks.js";
 
 /** The root types, in output order. */
-const ROOT_KEYS = Object.freeze(["paths", "webhooks", "components", "$defs"] as const);
+export const ROOT_KEYS = Object.freeze(["paths", "webhooks", "components", "$defs"] as const);
 type RootKey = (typeof ROOT_KEYS)[number];
 
-const OPERATIONS_NAME = "operations";
+export const OPERATIONS_NAME = "operations";
 /** The type of a root without members: `Record<string, never>`. */
 const EMPTY_ROOT_TYPE = irRecord(irKeyword("string"), irKeyword("never"));
 
@@ -191,7 +192,7 @@ export function documentBody(
   if (inject !== "") {
     declarations.push({ kind: "rawDeclaration", text: inject });
   }
-  declarations.push(...rootsDeclarations(document, context, footer));
+  appendAll(declarations, rootsDeclarations(document, context, footer));
   return declarations;
 }