openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/domain/ir/raw-text-escapes.ts

@@ -0,0 +1,37 @@
+/**
+ * Escapes for document text that the transformer writes into raw type text (threat model,
+ * docs/security/threat-model.md). Without them, a name or path from the document could end the
+ * literal early and add its own code to the generated file. Only the characters that would end or
+ * change the literal are escaped, so output for every other name stays byte-identical.
+ */
+
+/** Line terminators end a single-quoted string; TypeScript reads U+2028 and U+2029 as such too. */
+const SINGLE_QUOTED_ESCAPES: ReadonlyMap<string, string> = new Map([
+  ["\\", "\\\\"],
+  ["'", "\\'"],
+  ["\n", "\\n"],
+  ["\r", "\\r"],
+  ["\u2028", "\\u2028"],
+  ["\u2029", "\\u2029"],
+]);
+const SINGLE_QUOTED_SPECIAL_RE = /[\\'\n\r\u2028\u2029]/g;
+
+/** The text between the quotes of a single-quoted string literal with this value. */
+export function escapeSingleQuotedText(value: string): string {
+  return value.replace(SINGLE_QUOTED_SPECIAL_RE, (char) => SINGLE_QUOTED_ESCAPES.get(char) ?? char);
+}
+
+/**
+ * A backslash, a backtick, or the `${` that would start a placeholder. A raw carriage return is
+ * read as a line feed inside a template literal, so it is written as an escape.
+ */
+const TEMPLATE_SPECIAL_RE = /\\|`|\$\{|\r/g;
+
+function escapeTemplateSpecial(special: string): string {
+  return special === "\r" ? "\\r" : `\\${special}`;
+}
+
+/** Template literal text (between placeholders) that reads back as exactly this value. */
+export function escapeTemplateText(value: string): string {
+  return value.replace(TEMPLATE_SPECIAL_RE, escapeTemplateSpecial);
+}

package/src/domain/openapi/admitted-values.ts

@@ -0,0 +1,113 @@
+import { parseRefPointer } from "./json-pointer.js";
+
+/**
+ * The values a schema admits when it admits only finitely many (`enum`, `const`, and `allOf` /
+ * `anyOf` / `oneOf` of those), read from the document. Null means "any value" as far as this
+ * reading goes: a schema of any other shape, or a `$ref` it cannot follow, is never assumed to
+ * exclude a value.
+ */
+
+export type AdmittedValue = string | number | boolean | null;
+/** A finite set of values, or null for every value. */
+export type AdmittedValues = ReadonlySet<AdmittedValue> | null;
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+/** How deep `$ref`s and compositions are followed; deeper schemas admit every value. */
+const MAX_DEPTH = 16;
+const LOCAL_REF_PREFIX = "#/";
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The node at a local `$ref` (`#/...`) of the document, or undefined. */
+export function resolveLocalRef(document: unknown, ref: string): unknown {
+  if (!ref.startsWith(LOCAL_REF_PREFIX)) {
+    return undefined;
+  }
+  let node: unknown = document;
+  for (const segment of parseRefPointer(ref)) {
+    node = isObject(node) || Array.isArray(node) ? (node as JsonObject)[segment] : undefined;
+  }
+  return node;
+}
+
+function intersect(left: AdmittedValues, right: AdmittedValues): AdmittedValues {
+  if (left === null || right === null) {
+    return left ?? right;
+  }
+  return new Set([...left].filter((value) => right.has(value)));
+}
+
+function unite(sets: readonly AdmittedValues[]): AdmittedValues {
+  return sets.some((set) => set === null) ? null : new Set(sets.flatMap((set) => [...(set ?? [])]));
+}
+
+function isAdmittedValue(value: unknown): value is AdmittedValue {
+  return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+
+interface Walk {
+  readonly document: unknown;
+  readonly depth: number;
+  /** `$ref`s whose targets are left out: they add nothing to the generated type here. */
+  readonly skipped: ReadonlySet<string>;
+}
+
+function follow(node: unknown, walk: Walk): unknown {
+  if (!isObject(node) || typeof node.$ref !== "string") {
+    return node;
+  }
+  return walk.skipped.has(node.$ref) ? undefined : resolveLocalRef(walk.document, node.$ref);
+}
+
+function members(node: JsonObject, keyword: string): readonly unknown[] {
+  const list = node[keyword];
+  return Array.isArray(list) ? list : [];
+}
+
+/** `enum` and `const` of the schema itself, before its compositions. */
+function ownValues(node: JsonObject): AdmittedValues {
+  const listed = Array.isArray(node.enum) ? node.enum.filter(isAdmittedValue) : null;
+  const constant = "const" in node && isAdmittedValue(node.const) ? new Set([node.const]) : null;
+  return intersect(listed === null ? null : new Set(listed), constant);
+}
+
+function schemaValues(schema: unknown, walk: Walk): AdmittedValues {
+  const node = follow(schema, walk);
+  if (!isObject(node) || walk.depth > MAX_DEPTH) {
+    return null;
+  }
+  const next = { ...walk, depth: walk.depth + 1 };
+  const parts = members(node, "allOf").map((part) => schemaValues(part, next));
+  const variants = [...members(node, "anyOf"), ...members(node, "oneOf")];
+  const union = variants.length === 0 ? null : unite(variants.map((v) => schemaValues(v, next)));
+  return [...parts, union].reduce<AdmittedValues>(intersect, ownValues(node));
+}
+
+function propertyValues(schema: unknown, key: string, walk: Walk): AdmittedValues {
+  const node = follow(schema, walk);
+  if (!isObject(node) || walk.depth > MAX_DEPTH) {
+    return null;
+  }
+  const next = { ...walk, depth: walk.depth + 1 };
+  const properties = isObject(node.properties) ? node.properties : {};
+  const own = Object.hasOwn(properties, key) ? schemaValues(properties[key], next) : null;
+  const parts = members(node, "allOf").map((part) => propertyValues(part, key, next));
+  return parts.reduce<AdmittedValues>(intersect, own);
+}
+
+/**
+ * The values property `key` of an object schema admits: the intersection over the schema's own
+ * `properties` and its `allOf` parts (followed through `$ref`s, except `skipped` ones); null for
+ * every value.
+ */
+export function admittedPropertyValues(
+  schema: unknown,
+  key: string,
+  document: unknown,
+  skipped: ReadonlySet<string> = new Set(),
+): AdmittedValues {
+  return propertyValues(schema, key, { document, depth: 0, skipped });
+}

package/src/domain/openapi/alias-expansion.ts

@@ -0,0 +1,72 @@
+/**
+ * YAML aliases (`*name`) make the parsed document share objects. A "billion laughs" document,
+ * where each level refers to the previous one ten times, parses into a few hundred objects that
+ * every walk over the document (Redocly's resolver, the generator) visits as 10^9 nodes: the run
+ * took minutes and ended with "RangeError: Set maximum size exceeded" (pre-beta test plan 10.2).
+ * A document is refused when its aliases expand it far beyond what it stores.
+ */
+
+/** Expansion below this many nodes is allowed whatever the ratio: large real documents pass. */
+export const ALIAS_EXPANSION_MIN_NODES = 1_000_000;
+/** Real documents reuse anchors a few times; a bomb multiplies its size by orders of magnitude. */
+export const ALIAS_EXPANSION_MAX_RATIO = 100;
+
+export interface NodeCounts {
+  /** Nodes of the document as written: each object once, with its entries. */
+  readonly stored: number;
+  /** Nodes a walk visits when it follows every shared object again. */
+  readonly expanded: number;
+}
+
+function childrenOf(node: object): unknown[] {
+  return Array.isArray(node) ? node : Object.values(node);
+}
+
+function isContainer(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** The expanded size of `node`, whose container children are all sized (or in a cycle). */
+function sizeOf(node: object, sizes: ReadonlyMap<object, number>): number {
+  return childrenOf(node).reduce<number>(
+    (total, child) => total + (isContainer(child) ? (sizes.get(child) ?? 1) : 1),
+    1,
+  );
+}
+
+/**
+ * Count stored and expanded nodes without recursion (documents can be thousands of levels deep)
+ * and without expanding: each shared object is sized once. A cycle counts its back edge once.
+ */
+export function countNodes(root: unknown): NodeCounts {
+  if (!isContainer(root)) {
+    return { stored: 1, expanded: 1 };
+  }
+  const sizes = new Map<object, number>();
+  const entered = new Set<object>();
+  const stack: object[] = [root];
+  while (stack.length > 0) {
+    const node = stack[stack.length - 1] as object;
+    const isFirstVisit = !entered.has(node);
+    entered.add(node);
+    const pending = isFirstVisit
+      ? childrenOf(node).filter((child) => isContainer(child) && !entered.has(child))
+      : [];
+    if (pending.length > 0) {
+      stack.push(...(pending as object[]));
+      continue;
+    }
+    stack.pop();
+    sizes.set(node, sizeOf(node, sizes));
+  }
+  let stored = 0;
+  for (const node of sizes.keys()) {
+    stored += 1 + childrenOf(node).filter((child) => !isContainer(child)).length;
+  }
+  return { stored, expanded: sizes.get(root) ?? 1 };
+}
+
+/** Whether the aliases of a parsed document expand it beyond the limits above. */
+export function isAliasExpansionExcessive({ stored, expanded }: NodeCounts): boolean {
+  return expanded > Math.max(ALIAS_EXPANSION_MIN_NODES, stored * ALIAS_EXPANSION_MAX_RATIO);
+}

package/src/domain/openapi/binary-content.ts

@@ -0,0 +1,74 @@
+import type { SchemaObject } from "./schema-object.js";
+
+/**
+ * Which string schemas describe raw binary data, following "Working with Binary Data" of the
+ * OpenAPI specification (3.1): `format: binary` in 3.0, a `contentMediaType` without a
+ * `contentEncoding` in 3.1. `--binary-as-blob` types these as `Blob`.
+ * https://spec.openapis.org/oas/v3.1.1.html#working-with-binary-data
+ */
+
+/** The OpenAPI 3.0 format of unencoded octets (`byte` is base64 text). */
+const BINARY_FORMAT = "binary";
+
+/** The top-level media type whose contents are always text (RFC 2046). */
+const TEXT_TOP_LEVEL_TYPE = "text";
+
+/** The top-level media type of the text formats in `TEXT_APPLICATION_SUBTYPES`. */
+const APPLICATION_TOP_LEVEL_TYPE = "application";
+
+/**
+ * Text syntaxes, as a subtype (`application/json`) or a structured syntax suffix
+ * (`application/problem+json`, `image/svg+xml`; RFC 6839, RFC 9512).
+ */
+const TEXT_STRUCTURED_SYNTAXES: ReadonlySet<string> = new Set(["json", "xml", "yaml"]);
+
+/** Other text formats under `application/`, registered or in common use. */
+const TEXT_APPLICATION_SUBTYPES: ReadonlySet<string> = new Set([
+  "ecmascript",
+  "graphql",
+  "javascript",
+  "json-seq",
+  "jsonl",
+  "sql",
+  "x-ndjson",
+  "x-www-form-urlencoded",
+  "x-yaml",
+]);
+
+const PARAMETER_SEPARATOR = ";";
+const SUBTYPE_SEPARATOR = "/";
+const SUFFIX_SEPARATOR = "+";
+
+/**
+ * Whether a media type's contents are text, so a string schema with it holds the text itself.
+ * Parameters (`; charset=utf-8`) and case are ignored; a value without a subtype is not text.
+ */
+export function isTextualMediaType(mediaType: string): boolean {
+  const essence = (mediaType.split(PARAMETER_SEPARATOR)[0] ?? "").trim().toLowerCase();
+  const [topLevelType, subtype] = essence.split(SUBTYPE_SEPARATOR);
+  if (topLevelType === undefined || subtype === undefined) {
+    return false;
+  }
+  if (topLevelType === TEXT_TOP_LEVEL_TYPE) {
+    return true;
+  }
+  const suffix = subtype.slice(subtype.lastIndexOf(SUFFIX_SEPARATOR) + 1);
+  if (TEXT_STRUCTURED_SYNTAXES.has(subtype) || TEXT_STRUCTURED_SYNTAXES.has(suffix)) {
+    return true;
+  }
+  return topLevelType === APPLICATION_TOP_LEVEL_TYPE && TEXT_APPLICATION_SUBTYPES.has(subtype);
+}
+
+/**
+ * Whether a schema describes raw (unencoded) binary data. Any `contentEncoding` means the value
+ * is encoded text, so it wins over `format: binary`.
+ */
+export function isRawBinarySchema(schema: SchemaObject): boolean {
+  if (schema.contentEncoding !== undefined) {
+    return false;
+  }
+  if (schema.format === BINARY_FORMAT) {
+    return true;
+  }
+  return schema.contentMediaType !== undefined && !isTextualMediaType(schema.contentMediaType);
+}

package/src/domain/openapi/components-object.ts

@@ -0,0 +1,52 @@
+import { MEDIA_TYPES_COMPONENT_KIND } from "./media-type-object.js";
+
+/**
+ * The component maps the generator always writes, in output order (OpenAPI 3.1 §4.8.7); a kind the
+ * document lacks is `never`.
+ */
+export const COMPONENT_KINDS = Object.freeze([
+  "schemas",
+  "responses",
+  "parameters",
+  "requestBodies",
+  "headers",
+  "pathItems",
+] as const);
+
+/**
+ * OpenAPI 3.2 component maps, written after `COMPONENT_KINDS` and only when the document has them,
+ * so documents without them keep their output (ADR-020).
+ */
+export const DECLARED_COMPONENT_KINDS = Object.freeze([MEDIA_TYPES_COMPONENT_KIND] as const);
+
+export type ComponentKind =
+  | (typeof COMPONENT_KINDS)[number]
+  | (typeof DECLARED_COMPONENT_KINDS)[number];
+
+/** Components by kind and name; entries are read by each kind's transformer. */
+export type ComponentsObject = {
+  readonly [kind in ComponentKind]?: Readonly<Record<string, unknown>>;
+};
+
+/** `requestBodies` → `requestBody`; other kinds drop the final `s`. */
+export function singularizeComponentKind(kind: ComponentKind | `x-${string}`): string {
+  return kind === "requestBodies" ? "requestBody" : kind.slice(0, -1);
+}
+
+/**
+ * Whether a schema is an enum that `--enum` turns into a TypeScript enum. With `--root-types`
+ * such schemas get no root alias, because the enum is already exported under that name.
+ */
+export function isEnumSchema(schema: unknown): boolean {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    return false;
+  }
+  const record = schema as Record<string, unknown>;
+  return (
+    "enum" in record &&
+    Array.isArray(record.enum) &&
+    (!("type" in record) || record.type !== "object") &&
+    !("properties" in record) &&
+    !("additionalProperties" in record)
+  );
+}

package/src/domain/openapi/discriminated-union.ts

@@ -0,0 +1,109 @@
+import { escapePointerSegment } from "./json-pointer.js";
+import type { Schema, SchemaObject } from "./schema-object.js";
+
+/**
+ * A discriminator owner is either a parent that its members `allOf` (an object with the
+ * discriminator property) or a union (`oneOf` / `anyOf` of the members). The generated type of a
+ * union is a TypeScript union, so it cannot be used like a parent: `Omit<Union, "kind">` keeps
+ * only the keys that every member has, and a member that intersects the union it belongs to
+ * refers to itself (TS2502, upstream #1665).
+ */
+
+/** Resolves a `$ref` of the document; `undefined` when it points nowhere. */
+export type ResolveSchemaRef = (ref: string) => unknown;
+
+const UNION_KEYWORDS = ["oneOf", "anyOf"] as const;
+const COMPOSITION_KEYWORDS = ["allOf", ...UNION_KEYWORDS] as const;
+
+function isSchemaObject(value: unknown): value is SchemaObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function keywordItems(schema: SchemaObject, keywords: readonly string[]): readonly Schema[] {
+  const record = schema as Readonly<Record<string, unknown>>;
+  return keywords.flatMap((keyword) => {
+    const items = record[keyword];
+    return Array.isArray(items) ? (items as readonly Schema[]) : [];
+  });
+}
+
+/** The `oneOf` and `anyOf` members of a schema; empty when it is not a union. */
+export function unionMembers(schema: unknown): readonly Schema[] {
+  return isSchemaObject(schema) ? keywordItems(schema, UNION_KEYWORDS) : [];
+}
+
+/** The schema at `ref` when it is a union (has `oneOf` or `anyOf` members), else undefined. */
+export function unionAt(ref: string, resolve: ResolveSchemaRef): SchemaObject | undefined {
+  const schema = resolve(ref);
+  return isSchemaObject(schema) && unionMembers(schema).length > 0 ? schema : undefined;
+}
+
+/** What one search for a `$ref` has seen, so that a `$ref` cycle ends. */
+interface Search {
+  readonly target: string;
+  readonly resolve: ResolveSchemaRef;
+  readonly visited: Set<string>;
+}
+
+function reaches(schema: Schema, search: Search): boolean {
+  if (!isSchemaObject(schema)) {
+    return false;
+  }
+  const ref = (schema as { readonly $ref?: unknown }).$ref;
+  if (typeof ref === "string") {
+    if (ref === search.target) {
+      return true;
+    }
+    if (search.visited.has(ref)) {
+      return false;
+    }
+    search.visited.add(ref);
+    return reaches(search.resolve(ref) as Schema, search);
+  }
+  return keywordItems(schema, COMPOSITION_KEYWORDS).some((item) => reaches(item, search));
+}
+
+/**
+ * Whether the type of `union` contains the schema at `target` without an object in between: one
+ * of its members is a `$ref` to it, or `allOf` / `oneOf` / `anyOf` such a `$ref`, at any depth.
+ * Such a reference is resolved at once by TypeScript, unlike one in a property or an array.
+ */
+export function unionReaches(
+  union: SchemaObject,
+  target: string,
+  resolve: ResolveSchemaRef,
+): boolean {
+  const search = { target, resolve, visited: new Set<string>() };
+  return unionMembers(union).some((member) => reaches(member, search));
+}
+
+const COMPONENT_SCHEMAS = "#/components/schemas/";
+
+/** A mapping value as a `$ref`: a bare name is a component schema's name. */
+function mappingRef(target: unknown): string | undefined {
+  if (typeof target !== "string") {
+    return undefined;
+  }
+  return target.startsWith("#") ? target : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
+}
+
+/** Whether the discriminator `mapping` of `union` names the schema at `target`. */
+export function unionMaps(union: SchemaObject, target: string): boolean {
+  const mapping = (union.discriminator as { readonly mapping?: unknown } | undefined)?.mapping;
+  if (!isSchemaObject(mapping)) {
+    return false;
+  }
+  return Object.values(mapping).some((value) => mappingRef(value) === target);
+}
+
+/**
+ * Whether the schema at `target` is a member of `union`: the union's type contains it, or the
+ * discriminator `mapping` names it, which gives it a value of the union as a member does.
+ */
+export function isUnionMember(
+  union: SchemaObject,
+  target: string,
+  resolve: ResolveSchemaRef,
+): boolean {
+  return unionMaps(union, target) || unionReaches(union, target, resolve);
+}