openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,223 @@
+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);
+  if (element.isOptional) {
+    return ts.factory.createOptionalTypeNode(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);
+}