openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,151 @@
+import { Readable } from "node:stream";
+import { text } from "node:stream/consumers";
+import { fileURLToPath } from "node:url";
+import {
+  type BaseResolver,
+  type Document,
+  makeDocumentFromString,
+  ResolveError,
+  Source,
+  YamlParseError,
+} from "@redocly/openapi-core";
+import parseJson from "parse-json";
+import { aliasExpansionFailure } from "./alias-limit.js";
+import {
+  loadFailedError,
+  parseFailedError,
+  pathStringError,
+  sourceEmptyError,
+  sourceInvalidError,
+} from "./schema-load-errors.js";
+
+/** Parse a schema source of any supported type into a Redocly document (ENGINEERING_PLAN 4.5). */
+
+export interface ParseSchemaOptions {
+  absoluteRef: string;
+  resolver: BaseResolver;
+}
+
+/**
+ * Read a stream to the end as UTF-8 text, trimmed. A stream that fails rejects with
+ * SCHEMA_LOAD_FAILED; listening only for `data` and `end` left the promise pending forever.
+ */
+async function readStream(stream: Readable, absoluteRef: string): Promise<string> {
+  try {
+    return (await text(stream)).trim();
+  } catch (error) {
+    throw loadFailedError(absoluteRef, error);
+  }
+}
+
+const URL_PREFIXES = ["http://", "https://", "file://"] as const;
+
+/** A string is a URL, JSON (starts with `{`) or YAML. */
+function parseSchemaText(
+  schema: string,
+  options: ParseSchemaOptions,
+): Promise<Document> | Document {
+  if (URL_PREFIXES.some((prefix) => schema.startsWith(prefix))) {
+    const url = new URL(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);
+}
+
+function parseJsonText(text: string, absoluteRef: string): Document {
+  try {
+    return { source: new Source(absoluteRef, text, "application/json"), parsed: parseJson(text) };
+  } catch (cause) {
+    throw parseFailedError("json", absoluteRef, cause);
+  }
+}
+
+function parseYamlText(text: string, absoluteRef: string): Document {
+  let document: Document;
+  try {
+    document = makeDocumentFromString(text, absoluteRef);
+  } catch (cause) {
+    throw parseFailedError("yaml", absoluteRef, cause);
+  }
+  // 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);
+  }
+  const failure = aliasExpansionFailure(document.parsed);
+  if (failure !== undefined) {
+    throw parseFailedError("yaml", absoluteRef, failure);
+  }
+  return document;
+}
+
+/** The resolver throws for some failures (a missing file) and returns an error for others. */
+async function resolveSchemaURL(options: ParseSchemaOptions): Promise<Document> {
+  const result = await options.resolver
+    .resolveDocument(null, options.absoluteRef, true)
+    .catch((cause: unknown) => {
+      throw cause instanceof YamlParseError
+        ? fileParseFailedError(options.absoluteRef, cause)
+        : loadFailedError(options.absoluteRef, readerError(cause));
+    });
+  if ("parsed" in result) {
+    return result;
+  }
+  throw loadFailedError(options.absoluteRef, readerError(result));
+}
+
+/**
+ * Redocly wraps a failed read in `ResolveError`, which keeps the reader's error in
+ * `originalError`, not in `cause`. Unwrapped, the cause keeps the network reason (refused, DNS).
+ */
+function readerError(error: unknown): unknown {
+  let current = error;
+  while (current instanceof ResolveError) {
+    current = current.originalError;
+  }
+  return current;
+}
+
+/**
+ * The resolver parses JSON files with its YAML parser too, so the format comes from the file
+ * name. Some parser messages (a second YAML document) do not name the file; the error adds it.
+ */
+function fileParseFailedError(absoluteRef: string, error: YamlParseError): Error {
+  const format = absoluteRef.toLowerCase().endsWith(".json") ? "json" : "yaml";
+  const cause = error.message.includes(absoluteRef)
+    ? error
+    : new Error(`${error.message} in "${absoluteRef}"`, { cause: error });
+  return parseFailedError(format, absoluteRef, cause);
+}
+
+function parseSchemaObject(schema: unknown, absoluteRef: string): Document {
+  if (typeof schema === "object" && !Array.isArray(schema)) {
+    return {
+      source: new Source(absoluteRef, JSON.stringify(schema), "application/json"),
+      parsed: schema,
+    };
+  }
+  throw sourceInvalidError(schema);
+}
+
+/** Parse any supported source: URL, stream, buffer, URL or document text, or a plain object. */
+export async function parseSchema(schema: unknown, options: ParseSchemaOptions): Promise<Document> {
+  if (!schema) {
+    throw sourceEmptyError("Can’t parse empty schema");
+  }
+  if (schema instanceof URL) {
+    return resolveSchemaURL(options);
+  }
+  if (schema instanceof Readable) {
+    return parseSchema(await readStream(schema, options.absoluteRef), options);
+  }
+  if (schema instanceof Buffer) {
+    return parseSchema(schema.toString("utf8"), options);
+  }
+  if (typeof schema === "string") {
+    return parseSchemaText(schema, options);
+  }
+  return parseSchemaObject(schema, options.absoluteRef);
+}

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

@@ -0,0 +1,102 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/**
+ * Keys Redocly 1.34 cannot walk. It looks up the type of every key with `type.properties[key]`,
+ * which also finds inherited `Object.prototype` members; it then calls a found function with no
+ * `this`, and these methods throw a `TypeError` for that. Redocly 2.x looks up own keys only
+ * (ADR-005 keeps 1.34). `toString` and `constructor` do not throw, and load as they should.
+ *
+ * Redocly does not walk every value (`default` and `const` are data), so a document with such a
+ * key is not rejected up front: the loader looks for them only after Redocly threw a `TypeError`.
+ */
+export const UNSUPPORTED_KEYS: ReadonlySet<string> = new Set([
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+  "toLocaleString",
+  "valueOf",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__",
+]);
+
+/** Enough found keys in the message to act on; `details.keys` has all of them. */
+const KEYS_IN_MESSAGE = 5;
+
+/** A parsed document and where it was loaded from. */
+export interface LoadedDocument {
+  readonly source: string;
+  readonly parsed: unknown;
+}
+
+/** An unsupported key: its JSON pointer and the document that has it. */
+export interface UnsupportedKey {
+  readonly key: string;
+  readonly pointer: string;
+  readonly source: string;
+}
+
+interface PendingNode {
+  readonly value: object;
+  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
+ * once.
+ */
+function unsupportedKeysOf(document: LoadedDocument): UnsupportedKey[] {
+  const found: UnsupportedKey[] = [];
+  const visited = new WeakSet<object>();
+  const pending: PendingNode[] = [];
+  const enqueue = (value: unknown, pointer: string): void => {
+    if (typeof value === "object" && value !== null && !visited.has(value)) {
+      visited.add(value);
+      pending.push({ value, pointer });
+    }
+  };
+  enqueue(document.parsed, "#");
+  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)}`;
+      if (UNSUPPORTED_KEYS.has(key)) {
+        found.push({ key, pointer, source: document.source });
+      }
+      enqueue(child, pointer);
+    }
+  }
+  return found;
+}
+
+/** Every unsupported key of the given documents. */
+export function findUnsupportedKeys(documents: readonly LoadedDocument[]): UnsupportedKey[] {
+  return documents.flatMap(unsupportedKeysOf);
+}
+
+function describeKey(found: UnsupportedKey): string {
+  return `"${found.key}" at ${found.pointer} in ${found.source}`;
+}
+
+/** The typed error for the keys the schema loader failed on; `cause` is Redocly's `TypeError`. */
+export function unsupportedKeysError(
+  keys: readonly UnsupportedKey[],
+  cause: unknown,
+): OpenAPITypesafeError {
+  const listed = keys.slice(0, KEYS_IN_MESSAGE).map(describeKey);
+  const more = keys.length > KEYS_IN_MESSAGE ? ` and ${keys.length - KEYS_IN_MESSAGE} more` : "";
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_KEY_UNSUPPORTED,
+    message:
+      "The schema loader (Redocly 1.x) failed on a key named like a built-in object method. " +
+      `Rename it: ${listed.join(", ")}${more}.`,
+    details: { keys: keys.map((found) => ({ ...found })) },
+    cause,
+  });
+}

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);
+  }
+}