openapi-typesafe 0.0.0 → 1.0.0-rc.0

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

@@ -0,0 +1,98 @@
+import colors from "ansi-colors";
+import type { DebugGroup, Logger } from "../../application/ports/logger.js";
+
+/**
+ * The Logger port on a terminal, with the original output format: ` ⚠  ` warnings, ` ✘  `
+ * errors, and `openapi-ts:<group>` debug lines filtered by `DEBUG` (ENGINEERING_PLAN 4.5).
+ */
+
+/** Where the lines go: `console` in production, a recording sink in tests. */
+export interface TerminalSink {
+  debug(line: string): void;
+  warn(line: string): void;
+  error(line: string): void;
+}
+
+export interface TerminalLoggerOptions {
+  /** Drop warnings (errors and debug lines are still written). */
+  readonly silent: boolean;
+  /** The value of `DEBUG`: `*`, `openapi-ts:*` or `openapi-ts:<group>` turn debug lines on. */
+  readonly debugFilter: string | undefined;
+  readonly useColors: boolean;
+  readonly sink: TerminalSink;
+}
+
+type Colors = ReturnType<typeof colors.create>;
+
+const MILLISECONDS_PER_SECOND = 1000;
+const MILLISECONDS_PER_MINUTE = 60_000;
+
+/** A duration as the original prints it: one decimal, in ms, s or m. */
+export function formatDuration(milliseconds: number): string {
+  if (milliseconds < MILLISECONDS_PER_SECOND) {
+    return `${Math.round(10 * milliseconds) / 10}ms`;
+  }
+  if (milliseconds < MILLISECONDS_PER_MINUTE) {
+    return `${Math.round(milliseconds / 100) / 10}s`;
+  }
+  return `${Math.round(milliseconds / 6000) / 10}m`;
+}
+
+function groupColor(palette: Colors, group: DebugGroup | undefined): (text: string) => string {
+  const byGroup: Readonly<Partial<Record<DebugGroup, (text: string) => string>>> = {
+    redoc: palette.cyanBright,
+    lint: palette.yellowBright,
+    bundle: palette.magentaBright,
+    ts: palette.blueBright,
+  };
+  return (group && byGroup[group]) || palette.whiteBright;
+}
+
+/** Whether `DEBUG` asks for this group (the original check, case-insensitive for the group). */
+export function isDebugEnabled(filter: string | undefined, group: DebugGroup | undefined): boolean {
+  if (!filter) {
+    return false;
+  }
+  return (
+    !group ||
+    filter === "*" ||
+    filter === "openapi-ts:*" ||
+    filter.toLocaleLowerCase() === `openapi-ts:${group.toLocaleLowerCase()}`
+  );
+}
+
+class TerminalLogger implements Logger {
+  readonly #options: TerminalLoggerOptions;
+  readonly #palette: Colors;
+
+  constructor(options: TerminalLoggerOptions) {
+    this.#options = options;
+    this.#palette = colors.create();
+    this.#palette.enabled = options.useColors;
+  }
+
+  debug(message: string, group?: DebugGroup, durationMs?: number): void {
+    if (!isDebugEnabled(this.#options.debugFilter, group)) {
+      return;
+    }
+    const name = groupColor(this.#palette, group)(`openapi-ts:${group ?? "info"}`);
+    const time =
+      durationMs === undefined ? "" : this.#palette.green(` ${formatDuration(durationMs)} `);
+    this.#options.sink.debug(`  ${this.#palette.bold(name)}${time}${message}`);
+  }
+
+  warn(message: string): void {
+    if (!this.#options.silent) {
+      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${message}`));
+    }
+  }
+
+  error(message: string): void {
+    this.#options.sink.error(this.#palette.red(` ✘  ${message}`));
+  }
+}
+
+/** A Logger that writes to a terminal sink. */
+export function createTerminalLogger(options: TerminalLoggerOptions): Logger {
+  return new TerminalLogger(options);
+}

package/src/adapters/type-ast-bridge/footer-nodes.ts

@@ -0,0 +1,38 @@
+import type ts from "typescript";
+import type { IrPropertySignature } from "../../domain/ir/nodes.js";
+import { toPropertySignature } from "./ir-to-typescript.js";
+import type { TypeScriptModule } from "./load-typescript.js";
+
+/**
+ * TypeScript nodes that user code adds to the footer (`ctx.injectFooter`). The generator's own
+ * footer entries are IR; these functions are the only places that read or change a user's node.
+ */
+
+/** Whether the node is a type alias with this name (the original's helper check). */
+export function isTypeAliasNamed(ts: TypeScriptModule, node: ts.Node, name: string): boolean {
+  return ts.isTypeAliasDeclaration(node) && node.name.text === name;
+}
+
+/** The node as an interface with this name, or null. */
+export function asInterfaceNamed(
+  ts: TypeScriptModule,
+  node: ts.Node,
+  name: string,
+): ts.InterfaceDeclaration | null {
+  return ts.isInterfaceDeclaration(node) && node.name.text === name ? node : null;
+}
+
+/**
+ * Add a member to a user's interface in place, as the original `injectOperationObject` did:
+ * other references to the node see the member.
+ */
+export function appendMember(
+  ts: TypeScriptModule,
+  node: ts.InterfaceDeclaration,
+  member: IrPropertySignature,
+): void {
+  (node as { members: ts.NodeArray<ts.TypeElement> }).members = ts.factory.createNodeArray([
+    ...node.members,
+    toPropertySignature(ts, member),
+  ]);
+}

package/src/adapters/type-ast-bridge/ir-declarations-to-typescript.ts

@@ -0,0 +1,100 @@
+import type ts from "typescript";
+import { assertNever } from "../../domain/assert-never.js";
+import type { IrDeclaration } from "../../domain/ir/nodes.js";
+import { toTypeElement, toTypeNode, toValueExpression, withComments } from "./ir-to-typescript.js";
+import type { TypeScriptModule } from "./load-typescript.js";
+
+/**
+ * Convert IR declarations to TypeScript statements, with the factory calls the original makes
+ * (see `ir-to-typescript.ts` for types and members).
+ */
+
+function exportModifiers(ts: TypeScriptModule, isExported: boolean): ts.Modifier[] | undefined {
+  return isExported ? [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)] : undefined;
+}
+
+function toConstArrayStatement(
+  ts: TypeScriptModule,
+  declaration: Extract<IrDeclaration, { kind: "constArray" }>,
+): ts.Statement {
+  const initializer = ts.factory.createArrayLiteralExpression(
+    declaration.values.map((value) => toValueExpression(ts, value)),
+  );
+  const variable = ts.factory.createVariableDeclaration(
+    declaration.name,
+    undefined,
+    toTypeNode(ts, declaration.type),
+    initializer,
+  );
+  const list = ts.factory.createVariableDeclarationList([variable], ts.NodeFlags.Const);
+  return ts.factory.createVariableStatement(exportModifiers(ts, declaration.isExported), list);
+}
+
+/** Parse source text into statements, like the original's `stringToAST`. */
+export function parseStatements(ts: TypeScriptModule, text: string): readonly ts.Statement[] {
+  return ts.createSourceFile("raw.ts", text, ts.ScriptTarget.ESNext).statements;
+}
+
+/** Convert one IR declaration; a raw declaration gives every statement its text holds. */
+export function toStatements(ts: TypeScriptModule, declaration: IrDeclaration): ts.Statement[] {
+  return declaration.kind === "rawDeclaration"
+    ? [...parseStatements(ts, declaration.text)]
+    : [toStatement(ts, declaration)];
+}
+
+function toEnumStatement(
+  ts: TypeScriptModule,
+  declaration: Extract<IrDeclaration, { kind: "enum" }>,
+): ts.Statement {
+  const members = declaration.members.map((member) =>
+    withComments(
+      ts,
+      ts.factory.createEnumMember(member.name, toValueExpression(ts, member.value)),
+      member.comments,
+    ),
+  );
+  const modifiers = exportModifiers(ts, declaration.isExported);
+  return ts.factory.createEnumDeclaration(modifiers, declaration.name, members);
+}
+
+function toInterfaceStatement(
+  ts: TypeScriptModule,
+  declaration: Extract<IrDeclaration, { kind: "interface" }>,
+): ts.Statement {
+  const members = declaration.members.map((member) => toTypeElement(ts, member));
+  const modifiers = exportModifiers(ts, declaration.isExported);
+  return ts.factory.createInterfaceDeclaration(
+    modifiers,
+    declaration.name,
+    undefined,
+    undefined,
+    members,
+  );
+}
+
+function toTypeAliasStatement(
+  ts: TypeScriptModule,
+  declaration: Extract<IrDeclaration, { kind: "typeAlias" }>,
+): ts.Statement {
+  const type = toTypeNode(ts, declaration.type);
+  const modifiers = exportModifiers(ts, declaration.isExported);
+  return ts.factory.createTypeAliasDeclaration(modifiers, declaration.name, undefined, type);
+}
+
+/** Convert one IR declaration. A raw declaration is parsed, like the original's `stringToAST`. */
+export function toStatement(ts: TypeScriptModule, declaration: IrDeclaration): ts.Statement {
+  switch (declaration.kind) {
+    case "interface":
+      return withComments(ts, toInterfaceStatement(ts, declaration), declaration.comments);
+    case "typeAlias":
+      return withComments(ts, toTypeAliasStatement(ts, declaration), declaration.comments);
+    case "enum":
+      return withComments(ts, toEnumStatement(ts, declaration), declaration.comments);
+    case "constArray":
+      return withComments(ts, toConstArrayStatement(ts, declaration), declaration.comments);
+    case "rawDeclaration":
+      return parseStatements(ts, declaration.text)[0] as ts.Statement;
+    default:
+      return assertNever(declaration);
+  }
+}

package/src/adapters/type-ast-bridge/ir-to-typescript.ts

@@ -0,0 +1,220 @@
+import type ts from "typescript";
+import { assertNever } from "../../domain/assert-never.js";
+import type {
+  IrComment,
+  IrKeyword,
+  IrMember,
+  IrPropertyName,
+  IrPropertySignature,
+  IrTupleElement,
+  IrType,
+} from "../../domain/ir/nodes.js";
+import type { TypeScriptModule } from "./load-typescript.js";
+
+/**
+ * Convert IR to TypeScript AST nodes with the same factory calls the original generator makes.
+ * Printing the result with the TypeScript printer gives the original output, which is how the
+ * printer parity tests (ENGINEERING_PLAN 4.3) define "byte-identical". Every function takes the
+ * TypeScript module to build with (ADR-004, decision 4): the nodes must come from the same module
+ * that later reads or prints them.
+ */
+
+type KeywordName = Exclude<IrKeyword, "null">;
+
+function keywordKind(ts: TypeScriptModule, keyword: KeywordName): ts.KeywordTypeSyntaxKind {
+  const kinds: Readonly<Record<KeywordName, ts.KeywordTypeSyntaxKind>> = {
+    string: ts.SyntaxKind.StringKeyword,
+    number: ts.SyntaxKind.NumberKeyword,
+    boolean: ts.SyntaxKind.BooleanKeyword,
+    undefined: ts.SyntaxKind.UndefinedKeyword,
+    unknown: ts.SyntaxKind.UnknownKeyword,
+    never: ts.SyntaxKind.NeverKeyword,
+  };
+  return kinds[keyword];
+}
+
+function toKeywordType(ts: TypeScriptModule, keyword: IrKeyword): ts.TypeNode {
+  return keyword === "null"
+    ? ts.factory.createLiteralTypeNode(ts.factory.createNull())
+    : ts.factory.createKeywordTypeNode(keywordKind(ts, keyword));
+}
+
+/**
+ * Numbers as the original writes them: a negative value is a prefix minus on its absolute value.
+ */
+function toNumberExpression(
+  ts: TypeScriptModule,
+  value: number,
+): ts.PrefixUnaryExpression | ts.NumericLiteral {
+  return value < 0
+    ? ts.factory.createPrefixUnaryExpression(
+        ts.SyntaxKind.MinusToken,
+        ts.factory.createNumericLiteral(Math.abs(value)),
+      )
+    : ts.factory.createNumericLiteral(value);
+}
+
+/** An enum member or array element value, written as the original writes it. */
+export function toValueExpression(ts: TypeScriptModule, value: string | number): ts.Expression {
+  return typeof value === "number"
+    ? toNumberExpression(ts, value)
+    : ts.factory.createStringLiteral(value);
+}
+
+/** The original writes JSON-encoded literal types as identifiers to keep UTF-8 readable. */
+function toStringLiteralType(
+  ts: TypeScriptModule,
+  value: string,
+  encoding: "json" | "escaped",
+): ts.TypeNode {
+  return encoding === "json"
+    ? (ts.factory.createIdentifier(JSON.stringify(value)) as unknown as ts.TypeNode)
+    : ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral(value));
+}
+
+function toTupleElement(ts: TypeScriptModule, element: IrTupleElement): ts.TypeNode {
+  const type = toTypeNode(ts, element.type);
+  return element.isRest ? ts.factory.createRestTypeNode(type) : type;
+}
+
+type LeafType = Extract<
+  IrType,
+  { kind: "keyword" | "stringLiteral" | "numberLiteral" | "booleanLiteral" | "raw" }
+>;
+
+function toLeafTypeNode(ts: TypeScriptModule, type: LeafType): ts.TypeNode {
+  switch (type.kind) {
+    case "keyword":
+      return toKeywordType(ts, type.keyword);
+    case "stringLiteral":
+      return toStringLiteralType(ts, type.value, type.encoding);
+    case "numberLiteral":
+      return ts.factory.createLiteralTypeNode(toNumberExpression(ts, type.value));
+    case "booleanLiteral":
+      return ts.factory.createLiteralTypeNode(
+        type.value ? ts.factory.createTrue() : ts.factory.createFalse(),
+      );
+    case "raw":
+      // A node read from TypeScript goes back as it was, so the TypeScript printer indents it.
+      return (
+        (type.origin as ts.TypeNode | undefined) ??
+        (ts.factory.createIdentifier(type.text) as unknown as ts.TypeNode)
+      );
+    default:
+      return assertNever(type);
+  }
+}
+
+function toReferenceNode(
+  ts: TypeScriptModule,
+  type: Extract<IrType, { kind: "reference" }>,
+): ts.TypeNode {
+  const typeArguments =
+    type.typeArguments.length > 0
+      ? type.typeArguments.map((argument) => toTypeNode(ts, argument))
+      : undefined;
+  return ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(type.name), typeArguments);
+}
+
+/** Convert one IR type. */
+export function toTypeNode(ts: TypeScriptModule, type: IrType): ts.TypeNode {
+  const convert = (inner: IrType) => toTypeNode(ts, inner);
+  const { factory } = ts;
+  switch (type.kind) {
+    case "keyword":
+    case "stringLiteral":
+    case "numberLiteral":
+    case "booleanLiteral":
+    case "raw":
+      return toLeafTypeNode(ts, type);
+    case "reference":
+      return toReferenceNode(ts, type);
+    case "array":
+      return factory.createArrayTypeNode(convert(type.element));
+    case "tuple":
+      return factory.createTupleTypeNode(
+        type.elements.map((element) => toTupleElement(ts, element)),
+      );
+    case "union":
+      return factory.createUnionTypeNode(type.types.map(convert));
+    case "intersection":
+      return factory.createIntersectionTypeNode(type.types.map(convert));
+    case "object":
+      return factory.createTypeLiteralNode(type.members.map((member) => toTypeElement(ts, member)));
+    case "indexedAccess":
+      return factory.createIndexedAccessTypeNode(convert(type.object), convert(type.index));
+    case "readonly":
+      return factory.createTypeOperatorNode(ts.SyntaxKind.ReadonlyKeyword, convert(type.type));
+    default:
+      return assertNever(type);
+  }
+}
+
+/** Attach IR comments to a node as synthetic leading comments, as the original does. */
+export function withComments<T extends ts.Node>(
+  ts: TypeScriptModule,
+  node: T,
+  comments: readonly IrComment[],
+): T {
+  for (const comment of comments) {
+    const kind =
+      comment.kind === "block"
+        ? ts.SyntaxKind.MultiLineCommentTrivia
+        : ts.SyntaxKind.SingleLineCommentTrivia;
+    ts.addSyntheticLeadingComment(node, kind, comment.text, true);
+  }
+  return node;
+}
+
+function toPropertyName(ts: TypeScriptModule, name: IrPropertyName): ts.PropertyName {
+  switch (name.kind) {
+    case "identifier":
+      return ts.factory.createIdentifier(name.text);
+    case "string":
+      return ts.factory.createStringLiteral(name.value);
+    case "number":
+      return ts.factory.createNumericLiteral(name.text);
+    default:
+      return assertNever(name);
+  }
+}
+
+function readonlyModifiers(ts: TypeScriptModule, isReadonly: boolean): ts.Modifier[] | undefined {
+  return isReadonly ? [ts.factory.createModifier(ts.SyntaxKind.ReadonlyKeyword)] : undefined;
+}
+
+/** Convert one property signature (for callbacks that receive a `ts.PropertySignature`). */
+export function toPropertySignature(
+  ts: TypeScriptModule,
+  property: IrPropertySignature,
+): ts.PropertySignature {
+  const questionToken = property.isOptional
+    ? ts.factory.createToken(ts.SyntaxKind.QuestionToken)
+    : undefined;
+  const signature = ts.factory.createPropertySignature(
+    readonlyModifiers(ts, property.isReadonly),
+    toPropertyName(ts, property.name),
+    questionToken,
+    toTypeNode(ts, property.type),
+  );
+  return withComments(ts, signature, property.comments);
+}
+
+export function toTypeElement(ts: TypeScriptModule, member: IrMember): ts.TypeElement {
+  if (member.kind === "property") {
+    return toPropertySignature(ts, member);
+  }
+  const parameter = ts.factory.createParameterDeclaration(
+    undefined,
+    undefined,
+    member.parameterName,
+    undefined,
+    toTypeNode(ts, member.parameterType),
+  );
+  const signature = ts.factory.createIndexSignature(
+    readonlyModifiers(ts, member.isReadonly),
+    [parameter],
+    toTypeNode(ts, member.type),
+  );
+  return withComments(ts, signature, member.comments);
+}

package/src/adapters/type-ast-bridge/lazy-node.ts

@@ -0,0 +1,24 @@
+/**
+ * A TypeScript node that is created on first use (for the deprecated `QUESTION_TOKEN` export):
+ * the package must import without TypeScript installed (ADR-004, decision 4). Every property read,
+ * write and check goes to the node, so the TypeScript factory and printer see a normal node.
+ */
+export function lazyNode<T extends object>(create: () => T): T {
+  let node: T | undefined;
+  const target = (): T => {
+    node ??= create();
+    return node;
+  };
+  return new Proxy({} as T, {
+    get: (_, key) => Reflect.get(target(), key),
+    set: (_, key, value) => Reflect.set(target(), key, value),
+    has: (_, key) => Reflect.has(target(), key),
+    ownKeys: () => Reflect.ownKeys(target()),
+    getOwnPropertyDescriptor: (_, key) => {
+      const descriptor = Reflect.getOwnPropertyDescriptor(target(), key);
+      // A proxy may report a property only as configurable when its own (empty) target lacks it.
+      return descriptor === undefined ? undefined : { ...descriptor, configurable: true };
+    },
+    getPrototypeOf: () => Reflect.getPrototypeOf(target()),
+  });
+}

package/src/adapters/type-ast-bridge/load-typescript.ts

@@ -0,0 +1,84 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/**
+ * Load a TypeScript compiler module with the JavaScript API (ADR-004, decision 4). The bridge
+ * needs it only for legacy `ts.Node` callbacks and the deprecated `ts.Node` helpers, so it is
+ * loaded on first use, never at import time. TypeScript 7 has no JavaScript API: on such a project
+ * the user installs `@typescript/typescript6`.
+ */
+
+/** The `typescript` module of TypeScript 6 or earlier (or `@typescript/typescript6`). */
+export type TypeScriptModule = typeof import("typescript");
+
+/** Loads one package by name, like `require`. */
+export type ModuleRequire = (id: string) => unknown;
+
+/** The packages to try, in order: the project's own TypeScript first. */
+export const TYPESCRIPT_PACKAGES = ["typescript", "@typescript/typescript6"] as const;
+
+/** Error codes of a package that is missing or cannot be loaded with `require`. */
+const UNAVAILABLE_CODES = new Set([
+  "MODULE_NOT_FOUND",
+  "ERR_REQUIRE_ESM",
+  "ERR_PACKAGE_PATH_NOT_EXPORTED",
+]);
+
+export class TypeScriptNotFoundError extends OpenAPITypesafeError {
+  constructor() {
+    super({
+      code: ERROR_CODES.TYPESCRIPT_NOT_FOUND,
+      message:
+        "A callback or helper uses TypeScript compiler nodes, " +
+        "which needs the TypeScript JavaScript API. " +
+        'Install "typescript" version 6 or earlier, ' +
+        'or "@typescript/typescript6" on TypeScript 7, ' +
+        "or use IR callbacks (irCallbacks: true).",
+      details: { packages: [...TYPESCRIPT_PACKAGES] },
+    });
+    this.name = "TypeScriptNotFoundError";
+  }
+}
+
+/** Where to look: the current project, then this package's own location. */
+export function defaultModuleRequires(): readonly ModuleRequire[] {
+  return [createRequire(join(process.cwd(), "package.json")), createRequire(import.meta.url)];
+}
+
+function hasCompilerApi(value: unknown): value is TypeScriptModule {
+  const module = value as Partial<TypeScriptModule> | undefined;
+  return (
+    typeof module?.factory?.createTypeReferenceNode === "function" &&
+    typeof module.createPrinter === "function"
+  );
+}
+
+function tryRequire(load: ModuleRequire, id: string): unknown {
+  try {
+    return load(id);
+  } catch (error) {
+    if (UNAVAILABLE_CODES.has((error as { code?: string }).code ?? "")) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * The first package with the compiler API, trying each package name with each location. Node
+ * caches resolved modules, so repeated calls are cheap and return the same module.
+ */
+export function loadTypeScript(
+  requires: readonly ModuleRequire[] = defaultModuleRequires(),
+): TypeScriptModule {
+  for (const id of TYPESCRIPT_PACKAGES) {
+    for (const load of requires) {
+      const module = tryRequire(load, id);
+      if (hasCompilerApi(module)) {
+        return module;
+      }
+    }
+  }
+  throw new TypeScriptNotFoundError();
+}

package/src/adapters/type-ast-bridge/print-typescript.ts

@@ -0,0 +1,33 @@
+import type ts from "typescript";
+import type { TypeScriptModule } from "./load-typescript.js";
+
+/** Options of `astToString` for the TypeScript printer, as in the original. */
+export interface AstToStringOptions {
+  fileName?: string;
+  sourceText?: string;
+  formatOptions?: ts.PrinterOptions;
+}
+
+/** Print TypeScript nodes as the original `astToString` did. */
+export function printWithTypeScript(
+  ts: TypeScriptModule,
+  nodes: readonly ts.Node[],
+  options?: AstToStringOptions,
+): string {
+  const sourceFile = ts.createSourceFile(
+    options?.fileName ?? "openapi-ts.ts",
+    options?.sourceText ?? "",
+    ts.ScriptTarget.ESNext,
+    false,
+    ts.ScriptKind.TS,
+  );
+  // The source file is new and not shared, so its statements can be set once.
+  (sourceFile as { statements: ts.NodeArray<ts.Statement> }).statements =
+    ts.factory.createNodeArray(nodes as readonly ts.Statement[]);
+  const printer = ts.createPrinter({
+    newLine: ts.NewLineKind.LineFeed,
+    removeComments: false,
+    ...options?.formatOptions,
+  });
+  return printer.printFile(sourceFile);
+}

package/src/adapters/type-ast-bridge/typescript-raw-text.ts

@@ -0,0 +1,49 @@
+import type ts from "typescript";
+import { irRaw } from "../../domain/ir/constructors.js";
+import type { IrType } from "../../domain/ir/nodes.js";
+import { toTypeNode } from "./ir-to-typescript.js";
+import type { TypeScriptModule } from "./load-typescript.js";
+
+/**
+ * Callback nodes that the IR cannot model exactly are kept as text, printed the way the original
+ * printed them (ADR-004, decision 3).
+ */
+
+/** IR nodes have a string `kind`; TypeScript nodes have a numeric one. */
+export function isIrNode(value: unknown): value is IrType {
+  return typeof (value as { kind?: unknown }).kind === "string";
+}
+
+/** Replace IR nodes nested in a TypeScript tree, so the TypeScript printer can print it. */
+function withoutIrNodes<T extends ts.Node>(ts: TypeScriptModule, node: T): T {
+  const visit = (child: ts.Node): ts.Node =>
+    isIrNode(child) ? toTypeNode(ts, child) : ts.visitEachChild(child, visit, undefined);
+  return visit(node) as T;
+}
+
+function printPlainNode(ts: TypeScriptModule, node: ts.Node): string {
+  const source = ts.createSourceFile("openapi-ts.ts", "", ts.ScriptTarget.ESNext, false);
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+  return printer.printNode(ts.EmitHint.Unspecified, node, source);
+}
+
+/** Print as the original did: the TypeScript printer with an empty source file and LF. */
+export function printTypeScriptNode(ts: TypeScriptModule, node: ts.Node): string {
+  return printPlainNode(ts, withoutIrNodes(ts, node));
+}
+
+/** The node as text, keeping the node itself for the way back to TypeScript (`toTypeNode`). */
+export function asRaw(ts: TypeScriptModule, node: ts.TypeNode): IrType {
+  const printable = withoutIrNodes(ts, node);
+  return irRaw(printPlainNode(ts, printable), printable);
+}
+
+function hasSyntheticComments(ts: TypeScriptModule, node: ts.Node): boolean {
+  const leading = ts.getSyntheticLeadingComments(node)?.length ?? 0;
+  return leading + (ts.getSyntheticTrailingComments(node)?.length ?? 0) > 0;
+}
+
+/** Parsed nodes print from their source text, and comments attach to text: keep both printed. */
+export function needsPrintedText(ts: TypeScriptModule, node: ts.Node): boolean {
+  return node.pos >= 0 || hasSyntheticComments(ts, node);
+}