openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/package.json

@@ -1,6 +1,117 @@
 {
   "name": "openapi-typesafe",
-  "version": "0.0.0",
-  "description": "Reserved for openapi-typesafe. Contains no code.",
-  "license": "MIT"
-}
+  "description": "Convert OpenAPI 3.0 & 3.1 schemas to TypeScript",
+  "version": "1.0.0-rc.1",
+  "author": {
+    "name": "Fedor Chishchin",
+    "url": "https://github.com/fedorello"
+  },
+  "contributors": [
+    {
+      "name": "Drew Powers",
+      "email": "drew@pow.rs"
+    }
+  ],
+  "license": "MIT",
+  "bin": {
+    "openapi-typesafe": "bin/cli.js"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": "./dist/index.mjs"
+    },
+    "./*.js": "./*.mjs",
+    "./*": "./*"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "homepage": "https://github.com/openapi-typesafe/openapi-typesafe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openapi-typesafe/openapi-typesafe.git",
+    "directory": "packages/openapi-typesafe"
+  },
+  "keywords": [
+    "swagger",
+    "typescript",
+    "ts",
+    "dts",
+    "openapi",
+    "codegen",
+    "generation",
+    "openapi 3",
+    "node"
+  ],
+  "bugs": {
+    "url": "https://github.com/openapi-typesafe/openapi-typesafe/issues"
+  },
+  "peerDependencies": {
+    "@typescript/typescript6": "^6.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@typescript/typescript6": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@redocly/openapi-core": "^1.34.22",
+    "ansi-colors": "^4.1.3",
+    "change-case": "^5.4.4",
+    "parse-json": "^8.3.0",
+    "scule": "^1.3.0",
+    "supports-color": "^11.0.0",
+    "yargs-parser": "^22.0.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/yargs-parser": "21.0.3",
+    "@typescript/typescript6": "6.0.2",
+    "degit": "3.10.1",
+    "dependency-cruiser": "18.7.0",
+    "execa": "^10.2.1",
+    "fast-check": "4.10.2",
+    "strip-ansi": "7.2.0",
+    "typescript": "^6.0.3",
+    "vite-node": "6.0.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "download:schemas": "vite-node ./scripts/download-schemas.ts",
+    "format": "biome format . --write",
+    "lint": "pnpm run lint:js && pnpm run lint:ts && pnpm run lint:deps && pnpm run lint:sizes",
+    "lint:js": "biome check .",
+    "lint:ts": "tsc --noEmit && tsc -p tsconfig.strict.json",
+    "test": "pnpm run test:js && pnpm run test:examples && pnpm run test:exports",
+    "test:js": "vitest run",
+    "test:exports": "pnpm run build && ../../scripts/check-exports.sh",
+    "test:examples": "tsc -p tsconfig.examples.json --noEmit",
+    "update:examples": "pnpm run build && pnpm run download:schemas && vite-node ./scripts/update-examples.ts",
+    "prepublish": "pnpm run build",
+    "version": "pnpm run build",
+    "lint:deps": "depcruise src --config .dependency-cruiser.cjs",
+    "test:coverage": "vitest run --coverage",
+    "lint:sizes": "vite-node scripts/size-rules/check-sizes.ts src"
+  }
+}

package/src/adapters/node-file-system/node-file-system.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { FileReader, FileWriter } from "../../application/ports/file-system.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/** The file ports on Node's `fs`, with the failures as typed errors (ADR-011). */
+
+function causeMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+class NodeFileSystem implements FileReader, FileWriter {
+  readText(file: URL): string {
+    try {
+      return fs.readFileSync(file, "utf8");
+    } catch (cause) {
+      throw new OpenAPITypesafeError({
+        code: ERROR_CODES.OUTPUT_READ_FAILED,
+        message: `Cannot read ${fileURLToPath(file)}: ${causeMessage(cause)}`,
+        details: { file: fileURLToPath(file) },
+        cause,
+      });
+    }
+  }
+
+  writeText(file: URL, contents: string): void {
+    try {
+      fs.mkdirSync(new URL(".", file), { recursive: true });
+      fs.writeFileSync(file, contents, "utf8");
+    } catch (cause) {
+      throw new OpenAPITypesafeError({
+        code: ERROR_CODES.OUTPUT_WRITE_FAILED,
+        message: `Cannot write ${fileURLToPath(file)}: ${causeMessage(cause)}`,
+        details: { file: fileURLToPath(file) },
+        cause,
+      });
+    }
+  }
+}
+
+/** File access for the CLI. */
+export function createNodeFileSystem(): FileReader & FileWriter {
+  return new NodeFileSystem();
+}

package/src/adapters/redocly-loader/alias-limit.ts

@@ -0,0 +1,20 @@
+import {
+  ALIAS_EXPANSION_MAX_RATIO,
+  countNodes,
+  isAliasExpansionExcessive,
+} from "../../domain/openapi/alias-expansion.js";
+
+/**
+ * The reason a parsed YAML document is refused, if its aliases expand it too far. The check runs
+ * right after parsing, before Redocly or the generator walk the document (pre-beta test plan 10.2).
+ */
+export function aliasExpansionFailure(parsed: unknown): Error | undefined {
+  const counts = countNodes(parsed);
+  if (!isAliasExpansionExcessive(counts)) {
+    return undefined;
+  }
+  return new Error(
+    `YAML aliases expand the document from ${counts.stored} to ${counts.expanded} nodes, ` +
+      `more than ${ALIAS_EXPANSION_MAX_RATIO} times its size`,
+  );
+}

package/src/adapters/redocly-loader/allowed-hosts.ts

@@ -0,0 +1,62 @@
+/**
+ * Matching URLs against the `--remote-ref-hosts` list (threat model R2, ADR-017). Both sides are
+ * compared as the WHATWG URL parser writes hosts (lower case, Punycode, dotted IPv4, compressed
+ * IPv6 in brackets), so `bücher.example`, `::1` and `api.example.com.` match the hosts they name.
+ */
+
+const DEFAULT_PORTS: Readonly<Record<string, string>> = { "http:": "80", "https:": "443" };
+const FULLY_QUALIFIED_DOT = /\.$/;
+const PORT_SUFFIX = /:(\d+)$/;
+/** Characters that end a host in a URL: an entry with them would match a different host. */
+const NOT_A_HOST = /[/?#@\\]/;
+
+interface HostEntry {
+  readonly hostname: string;
+  /** Undefined when the entry allows any port. */
+  readonly port: string | undefined;
+}
+
+/** A bare IPv6 address has two colons or more and cannot carry a port; brackets add one. */
+function withBrackets(entry: string): string {
+  const isBareIPv6 = !entry.startsWith("[") && entry.split(":").length > 2;
+  return isBareIPv6 ? `[${entry}]` : entry;
+}
+
+function hostnameOf(url: URL): string {
+  return url.hostname.replace(FULLY_QUALIFIED_DOT, "");
+}
+
+function portOf(url: URL): string {
+  return url.port === "" ? (DEFAULT_PORTS[url.protocol] ?? "") : url.port;
+}
+
+/** The written port without leading zeros, as the URL parser writes it; undefined when none. */
+function writtenPort(entry: string): string | undefined {
+  const match = PORT_SUFFIX.exec(entry);
+  return match === null ? undefined : String(Number(match[1]));
+}
+
+/** The entry as the URL parser reads it, or undefined when it is not a bare host or host:port. */
+function parseHostEntry(entry: string): HostEntry | undefined {
+  const written = withBrackets(entry.trim());
+  const candidate = `http://${written}`;
+  if (written === "" || NOT_A_HOST.test(written) || !URL.canParse(candidate)) {
+    return undefined;
+  }
+  // The port is read from the text: the parser drops a default port (`:80`), which must still
+  // limit the entry to that port.
+  return { hostname: hostnameOf(new URL(candidate)), port: writtenPort(written) };
+}
+
+/** Whether the URL's host is listed, by host name alone (any port) or with its port. */
+export function isHostAllowed(url: URL, hosts: readonly string[]): boolean {
+  const hostname = hostnameOf(url);
+  if (hostname === "") {
+    return false;
+  }
+  const port = portOf(url);
+  return hosts.map(parseHostEntry).some((entry) => {
+    const isAnyPort = entry?.port === undefined;
+    return entry?.hostname === hostname && (isAnyPort || entry.port === port);
+  });
+}

package/src/adapters/redocly-loader/bundled-ref-repair.ts

@@ -0,0 +1,65 @@
+import { escapePointerSegment, parseRefPointer } from "../../domain/openapi/json-pointer.js";
+import { findRefHolders } from "./ref-holders.js";
+
+/**
+ * Redocly 1.x bundles an external `$ref` into a component named after the raw segment of the
+ * original pointer (`a~0b`, `50%`), and writes the new local `$ref` without escaping it. Read as a
+ * JSON Pointer, `#/components/schemas/a~0b` names the key `a~b`, which does not exist, and
+ * `#/components/schemas/50%` is malformed, so the generator failed on it. This rewrites every
+ * local `$ref` that does not resolve as a pointer but does resolve segment by segment as written.
+ */
+
+const LOCAL_REF_PREFIX = "#/";
+
+function isContainer(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+function childAt(node: unknown, segment: string): unknown {
+  if (!isContainer(node) || !Object.hasOwn(node, segment)) {
+    return undefined;
+  }
+  return (node as Record<string, unknown>)[segment];
+}
+
+function resolves(document: unknown, segments: readonly string[]): boolean {
+  return segments.reduce<unknown>(childAt, document) !== undefined;
+}
+
+/** The pointer's segments, or null when the pointer has a malformed percent escape. */
+function decodedSegments(ref: string): string[] | null {
+  try {
+    return parseRefPointer(ref);
+  } catch (error) {
+    if (error instanceof URIError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/** The repaired `$ref`, or null when the ref resolves already or cannot be repaired. */
+function repairedRef(document: unknown, ref: string): string | null {
+  const decoded = decodedSegments(ref);
+  if (decoded && resolves(document, decoded)) {
+    return null;
+  }
+  const raw = ref.slice(LOCAL_REF_PREFIX.length).split("/").filter(Boolean);
+  if (!resolves(document, raw)) {
+    return null;
+  }
+  return `${LOCAL_REF_PREFIX}${raw.map(escapePointerSegment).join("/")}`;
+}
+
+/** Repair the local `$ref`s of a bundled document in place, as Redocly's bundle edits it. */
+export function repairBundledRefs(document: unknown): void {
+  for (const { node } of findRefHolders(document)) {
+    if (!node.$ref.startsWith(LOCAL_REF_PREFIX)) {
+      continue;
+    }
+    const repaired = repairedRef(document, node.$ref);
+    if (repaired !== null) {
+      node.$ref = repaired;
+    }
+  }
+}

package/src/adapters/redocly-loader/malformed-refs.ts

@@ -0,0 +1,61 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import { parseRefPointer } from "../../domain/openapi/json-pointer.js";
+import { findRefHolders } from "./ref-holders.js";
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/**
+ * Redocly percent-decodes every JSON Pointer in a `$ref` and throws a bare `URIError` for a
+ * malformed escape such as `#/components/schemas/50%` (`%` must be written `%25`). The loader
+ * looks for these refs only after Redocly threw, and names them.
+ */
+
+/** Enough refs in the message to act on; `details.refs` has all of them. */
+const REFS_IN_MESSAGE = 5;
+
+/** A `$ref` whose pointer has a malformed percent escape, and where it is. */
+export interface MalformedRef {
+  readonly ref: string;
+  readonly pointer: string;
+  readonly source: string;
+}
+
+function isMalformed(ref: string): boolean {
+  try {
+    parseRefPointer(ref);
+    return false;
+  } catch (error) {
+    if (error instanceof URIError) {
+      return true;
+    }
+    throw error;
+  }
+}
+
+/** Every malformed `$ref` of the given documents. */
+export function findMalformedRefs(documents: readonly LoadedDocument[]): MalformedRef[] {
+  return documents.flatMap((document) =>
+    findRefHolders(document.parsed)
+      .filter(({ node }) => isMalformed(node.$ref))
+      .map(({ node, pointer }) => ({ ref: node.$ref, pointer, source: document.source })),
+  );
+}
+
+function describeRef(found: MalformedRef): string {
+  return `"${found.ref}" at ${found.pointer} in ${found.source}`;
+}
+
+/** The typed error for Redocly's `URIError`; `cause` is that error. */
+export function malformedRefsError(
+  refs: readonly MalformedRef[],
+  cause: unknown,
+): OpenAPITypesafeError {
+  const listed = refs.slice(0, REFS_IN_MESSAGE).map(describeRef);
+  const more = refs.length > REFS_IN_MESSAGE ? ` and ${refs.length - REFS_IN_MESSAGE} more` : "";
+  const where = listed.length === 0 ? "" : `: ${listed.join(", ")}${more}`;
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_REF_INVALID,
+    message: `A $ref has a malformed percent escape; write "%" as "%25" in a JSON Pointer${where}.`,
+    details: { reason: "malformed", refs: refs.map((found) => ({ ...found })) },
+    cause,
+  });
+}

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

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createConfig, findConfig, IGNORE_FILE, loadConfig } from "@redocly/openapi-core";
+import type {
+  RedoclyConfig,
+  RedoclyConfigSource,
+} from "../../application/ports/redocly-config-source.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/**
+ * The first line of a failure, with the error's name: a YAML error goes on with a snippet of the
+ * file, and the name tells a YAML error from a file system one.
+ */
+function reasonOf(error: unknown): string {
+  return String(error).replace(/\n[\s\S]*$/, "");
+}
+
+/**
+ * The config, or `CLI_CONFIG_INVALID`. Redocly reads the config file and the lint-ignore file
+ * next to it (or in the working directory); either can be malformed, and its error does not
+ * always name the file, so the message names both.
+ */
+async function loadedConfig(
+  load: () => Promise<RedoclyConfig>,
+  configPath: string | undefined,
+): Promise<RedoclyConfig> {
+  try {
+    return await load();
+  } catch (error) {
+    const config =
+      configPath === undefined ? "the default Redocly config" : `the Redocly config ${configPath}`;
+    const where = configPath === undefined ? "in the working directory" : "next to it";
+    throw new OpenAPITypesafeError({
+      code: ERROR_CODES.CLI_CONFIG_INVALID,
+      message: `Cannot load ${config} or the ${IGNORE_FILE} ${where}: ${reasonOf(error)}`,
+      details: { configPath },
+      cause: error,
+    });
+  }
+}
+
+/** The Redocly config port on `@redocly/openapi-core`, resolving paths from `cwd`. */
+class RedoclyConfigFiles implements RedoclyConfigSource {
+  readonly #cwd: string;
+
+  constructor(cwd: string) {
+    this.#cwd = cwd;
+  }
+
+  find(explicitPath: string | undefined): string | undefined {
+    if (!explicitPath) {
+      return findConfig(this.#cwd);
+    }
+    const resolved = path.resolve(this.#cwd, explicitPath);
+    if (!fs.existsSync(resolved)) {
+      return undefined;
+    }
+    return fs.statSync(resolved).isDirectory() ? findConfig(resolved) : resolved;
+  }
+
+  load(configPath: string): Promise<RedoclyConfig> {
+    return loadedConfig(() => loadConfig({ configPath }), configPath);
+  }
+
+  createDefault(): Promise<RedoclyConfig> {
+    const create = () =>
+      createConfig(
+        { rules: { "operation-operationId-unique": { severity: "warn" } } },
+        { extends: ["minimal"] },
+      );
+    return loadedConfig(create, undefined);
+  }
+}
+
+/** Find and load `redocly.yaml` relative to the directory `cwd`. */
+export function createRedoclyConfigSource(cwd: string): RedoclyConfigSource {
+  return new RedoclyConfigFiles(cwd);
+}