openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/domain/ir/constructors.ts

@@ -0,0 +1,137 @@
+import type {
+  IrArrayType,
+  IrBooleanLiteralType,
+  IrComment,
+  IrIndexedAccessType,
+  IrIndexSignature,
+  IrIntersectionType,
+  IrKeyword,
+  IrKeywordType,
+  IrMember,
+  IrNumberLiteralType,
+  IrObjectType,
+  IrPropertyName,
+  IrPropertySignature,
+  IrRawType,
+  IrReadonlyType,
+  IrReferenceType,
+  IrStringEncoding,
+  IrStringLiteralType,
+  IrTupleElement,
+  IrTupleType,
+  IrType,
+  IrUnionType,
+} from "./nodes.js";
+
+/**
+ * Constructors of IR nodes. They build exactly the node asked for: no flattening, de-duplication or
+ * sorting happens here (ENGINEERING_PLAN §4.2). Callers that need those call the functions in
+ * `normalize.ts` explicitly, at the same places the original generator does.
+ */
+
+export function irKeyword(keyword: IrKeyword): IrKeywordType {
+  return { kind: "keyword", keyword };
+}
+
+export function irString(value: string, encoding: IrStringEncoding): IrStringLiteralType {
+  return { kind: "stringLiteral", value, encoding };
+}
+
+/** Throws on NaN and infinities: they have no literal type. */
+export function irNumber(value: number): IrNumberLiteralType {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`A number literal type needs a finite number, got ${value}`);
+  }
+  return { kind: "numberLiteral", value };
+}
+
+export function irBoolean(value: boolean): IrBooleanLiteralType {
+  return { kind: "booleanLiteral", value };
+}
+
+export function irReference(name: string, typeArguments: readonly IrType[] = []): IrReferenceType {
+  return { kind: "reference", name, typeArguments };
+}
+
+export function irArray(element: IrType): IrArrayType {
+  return { kind: "array", element };
+}
+
+export function irTuple(elements: readonly IrTupleElement[]): IrTupleType {
+  return { kind: "tuple", elements };
+}
+
+export function irTupleElement(type: IrType, isRest = false): IrTupleElement {
+  return { type, isRest };
+}
+
+export function irUnion(types: readonly IrType[]): IrUnionType {
+  return { kind: "union", types };
+}
+
+export function irIntersection(types: readonly IrType[]): IrIntersectionType {
+  return { kind: "intersection", types };
+}
+
+export function irObject(members: readonly IrMember[]): IrObjectType {
+  return { kind: "object", members };
+}
+
+export function irIndexedAccess(object: IrType, index: IrType): IrIndexedAccessType {
+  return { kind: "indexedAccess", object, index };
+}
+
+export function irReadonly(type: IrType): IrReadonlyType {
+  return { kind: "readonly", type };
+}
+
+/**
+ * Type text printed as is. The original builds some types from text (template literal path keys,
+ * root type aliases); keeping them as text keeps their exact spelling.
+ */
+export function irRaw(text: string, origin?: unknown): IrRawType {
+  return origin === undefined ? { kind: "raw", text } : { kind: "raw", text, origin };
+}
+
+/** Options of a property signature; omitted flags are false and there are no comments. */
+export interface IrPropertyOptions {
+  readonly isOptional?: boolean;
+  readonly isReadonly?: boolean;
+  readonly comments?: readonly IrComment[];
+}
+
+export function irProperty(
+  name: IrPropertyName,
+  type: IrType,
+  options: IrPropertyOptions = {},
+): IrPropertySignature {
+  return {
+    kind: "property",
+    name,
+    type,
+    isOptional: options.isOptional ?? false,
+    isReadonly: options.isReadonly ?? false,
+    comments: options.comments ?? [],
+  };
+}
+
+/** `[name: string]: type` (a `string` key, the only kind the generator writes). */
+export function irStringIndexSignature(
+  parameterName: string,
+  type: IrType,
+  isReadonly = false,
+): IrIndexSignature {
+  return {
+    kind: "indexSignature",
+    parameterName,
+    parameterType: irKeyword("string"),
+    type,
+    isReadonly,
+    comments: [],
+  };
+}
+
+/** `Record<key, value>`. */
+export function irRecord(key: IrType, value: IrType): IrReferenceType {
+  return irReference("Record", [key, value]);
+}

package/src/domain/ir/identifier-text.ts

@@ -0,0 +1,49 @@
+import { NEWER_IDENTIFIER_PART, NEWER_IDENTIFIER_START } from "./newer-identifier-ranges.js";
+
+/**
+ * Identifier rules of ECMAScript (Unicode `ID_Start` / `ID_Continue`, plus `$`, `_`, ZWNJ and
+ * ZWJ), for names built from document text, without the characters that TypeScript's scanner
+ * does not know yet. Node.js follows a newer Unicode version than TypeScript's identifier tables,
+ * so a name such as `꟒Name` (Unicode 17) passed here and failed to parse with "Invalid
+ * character" (ADR-019). Removing the newer characters also gives the same names on every
+ * supported Node.js version.
+ */
+
+const IDENTIFIER_START_RE = new RegExp(
+  `^[[\\p{ID_Start}$_]--[${NEWER_IDENTIFIER_START.join("")}]]`,
+  "v",
+);
+const INVALID_IDENTIFIER_PART_RE = new RegExp(
+  `[^[\\p{ID_Continue}$\\u{200C}\\u{200D}]--[${NEWER_IDENTIFIER_PART.join("")}]]`,
+  "gv",
+);
+
+/** Whether the text starts with a character that may start an identifier. */
+export function hasIdentifierStart(text: string): boolean {
+  return IDENTIFIER_START_RE.test(text);
+}
+
+/** The text with each character that cannot be part of an identifier replaced by `_`. */
+export function withIdentifierParts(text: string): string {
+  return text.replace(INVALID_IDENTIFIER_PART_RE, "_");
+}
+
+/**
+ * The names TypeScript does not accept as a type alias name: reserved words, strict mode and
+ * module reserved words, and predefined type names (`void`, `string`, …). Checked with the
+ * TypeScript 6.0 compiler on `export type <name> = 1;` in a module.
+ */
+const RESERVED_TYPE_NAMES: ReadonlySet<string> = new Set(
+  (
+    "any as await bigint boolean break case catch class const continue debugger default delete " +
+    "do else enum export extends false finally for function if implements import in instanceof " +
+    "interface let never new null number object package private protected public return static " +
+    "string super switch symbol this throw true try typeof undefined unknown var void while with " +
+    "yield"
+  ).split(" "),
+);
+
+/** Whether TypeScript rejects the text as the name of a type alias. */
+export function isReservedTypeName(text: string): boolean {
+  return RESERVED_TYPE_NAMES.has(text);
+}

package/src/domain/ir/newer-identifier-ranges.ts

@@ -0,0 +1,109 @@
+// Generated by scripts/identifier-ranges.ts (Node.js 26.0.0, Unicode
+// 17.0, TypeScript 5.9.3). Do not edit.
+
+/** `ID_Start` code points that TypeScript's scanner does not accept, as regex class items. */
+export const NEWER_IDENTIFIER_START: readonly string[] = [
+  "\\u{88F}",
+  "\\u{C5C}",
+  "\\u{CDC}",
+  "\\u{1C89}-\\u{1C8A}",
+  "\\u{A7CB}-\\u{A7CF}",
+  "\\u{A7D2}",
+  "\\u{A7D4}",
+  "\\u{A7DA}-\\u{A7DC}",
+  "\\u{A7F1}",
+  "\\u{105C0}-\\u{105F3}",
+  "\\u{10940}-\\u{10959}",
+  "\\u{10D4A}-\\u{10D65}",
+  "\\u{10D6F}-\\u{10D85}",
+  "\\u{10EC2}-\\u{10EC7}",
+  "\\u{11380}-\\u{11389}",
+  "\\u{1138B}",
+  "\\u{1138E}",
+  "\\u{11390}-\\u{113B5}",
+  "\\u{113B7}",
+  "\\u{113D1}",
+  "\\u{113D3}",
+  "\\u{11BC0}-\\u{11BE0}",
+  "\\u{11DB0}-\\u{11DDB}",
+  "\\u{13460}-\\u{143FA}",
+  "\\u{16100}-\\u{1611D}",
+  "\\u{16D40}-\\u{16D6C}",
+  "\\u{16EA0}-\\u{16EB8}",
+  "\\u{16EBB}-\\u{16ED3}",
+  "\\u{16FF2}-\\u{16FF6}",
+  "\\u{187F8}-\\u{187FF}",
+  "\\u{18CFF}",
+  "\\u{18D09}-\\u{18D1E}",
+  "\\u{18D80}-\\u{18DF2}",
+  "\\u{1E5D0}-\\u{1E5ED}",
+  "\\u{1E5F0}",
+  "\\u{1E6C0}-\\u{1E6DE}",
+  "\\u{1E6E0}-\\u{1E6E2}",
+  "\\u{1E6E4}-\\u{1E6E5}",
+  "\\u{1E6E7}-\\u{1E6ED}",
+  "\\u{1E6F0}-\\u{1E6F4}",
+  "\\u{1E6FE}-\\u{1E6FF}",
+  "\\u{2B73A}-\\u{2B73F}",
+  "\\u{2CEA2}-\\u{2CEAD}",
+  "\\u{323B0}-\\u{33479}",
+];
+
+/** `ID_Continue` code points that TypeScript's scanner does not accept, as regex class items. */
+export const NEWER_IDENTIFIER_PART: readonly string[] = [
+  "\\u{88F}",
+  "\\u{897}",
+  "\\u{C5C}",
+  "\\u{CDC}",
+  "\\u{1ACF}-\\u{1ADD}",
+  "\\u{1AE0}-\\u{1AEB}",
+  "\\u{1C89}-\\u{1C8A}",
+  "\\u{A7CB}-\\u{A7CF}",
+  "\\u{A7D2}",
+  "\\u{A7D4}",
+  "\\u{A7DA}-\\u{A7DC}",
+  "\\u{A7F1}",
+  "\\u{105C0}-\\u{105F3}",
+  "\\u{10940}-\\u{10959}",
+  "\\u{10D40}-\\u{10D65}",
+  "\\u{10D69}-\\u{10D6D}",
+  "\\u{10D6F}-\\u{10D85}",
+  "\\u{10EC2}-\\u{10EC7}",
+  "\\u{10EFA}-\\u{10EFC}",
+  "\\u{11380}-\\u{11389}",
+  "\\u{1138B}",
+  "\\u{1138E}",
+  "\\u{11390}-\\u{113B5}",
+  "\\u{113B7}-\\u{113C0}",
+  "\\u{113C2}",
+  "\\u{113C5}",
+  "\\u{113C7}-\\u{113CA}",
+  "\\u{113CC}-\\u{113D3}",
+  "\\u{113E1}-\\u{113E2}",
+  "\\u{116D0}-\\u{116E3}",
+  "\\u{11B60}-\\u{11B67}",
+  "\\u{11BC0}-\\u{11BE0}",
+  "\\u{11BF0}-\\u{11BF9}",
+  "\\u{11DB0}-\\u{11DDB}",
+  "\\u{11DE0}-\\u{11DE9}",
+  "\\u{11F5A}",
+  "\\u{13460}-\\u{143FA}",
+  "\\u{16100}-\\u{16139}",
+  "\\u{16D40}-\\u{16D6C}",
+  "\\u{16D70}-\\u{16D79}",
+  "\\u{16EA0}-\\u{16EB8}",
+  "\\u{16EBB}-\\u{16ED3}",
+  "\\u{16FF2}-\\u{16FF6}",
+  "\\u{187F8}-\\u{187FF}",
+  "\\u{18CFF}",
+  "\\u{18D09}-\\u{18D1E}",
+  "\\u{18D80}-\\u{18DF2}",
+  "\\u{1CCF0}-\\u{1CCF9}",
+  "\\u{1E5D0}-\\u{1E5FA}",
+  "\\u{1E6C0}-\\u{1E6DE}",
+  "\\u{1E6E0}-\\u{1E6F5}",
+  "\\u{1E6FE}-\\u{1E6FF}",
+  "\\u{2B73A}-\\u{2B73F}",
+  "\\u{2CEA2}-\\u{2CEAD}",
+  "\\u{323B0}-\\u{33479}",
+];

package/src/domain/ir/nodes.ts

@@ -0,0 +1,224 @@
+/**
+ * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
+ * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
+ * discriminator; every consumer dispatches with an exhaustive `switch`, so a new kind breaks the
+ * build wherever it must be handled.
+ *
+ * Utility types (`Omit`, `Record`, `WithRequired`, `Extract`) are `reference` nodes with type
+ * arguments, built by named constructors: the printer has nothing special to do for them.
+ */
+
+/** Keyword types. `null` is a keyword here; TypeScript models it as a literal type. */
+export type IrKeyword =
+  | "string"
+  | "number"
+  | "boolean"
+  | "null"
+  | "undefined"
+  | "unknown"
+  | "never";
+
+/**
+ * How a string literal is written.
+ * - `json`: `JSON.stringify` text, non-ASCII kept as is. The original writes literal types this way
+ *   to keep UTF-8 readable (TypeScript issue 36174).
+ * - `escaped`: TypeScript printer escaping, non-ASCII as `\uXXXX`. The original writes
+ *   indexed-access keys and quoted property names this way.
+ */
+export type IrStringEncoding = "json" | "escaped";
+
+export interface IrKeywordType {
+  readonly kind: "keyword";
+  readonly keyword: IrKeyword;
+}
+
+export interface IrStringLiteralType {
+  readonly kind: "stringLiteral";
+  readonly value: string;
+  readonly encoding: IrStringEncoding;
+}
+
+/** Finite number; a negative value prints with a leading minus sign. */
+export interface IrNumberLiteralType {
+  readonly kind: "numberLiteral";
+  readonly value: number;
+}
+
+export interface IrBooleanLiteralType {
+  readonly kind: "booleanLiteral";
+  readonly value: boolean;
+}
+
+/** A named type, optionally with type arguments: `components`, `Record<string, never>`. */
+export interface IrReferenceType {
+  readonly kind: "reference";
+  readonly name: string;
+  readonly typeArguments: readonly IrType[];
+}
+
+export interface IrArrayType {
+  readonly kind: "array";
+  readonly element: IrType;
+}
+
+/** A tuple element; `isRest` prints `...T`. */
+export interface IrTupleElement {
+  readonly type: IrType;
+  readonly isRest: boolean;
+}
+
+export interface IrTupleType {
+  readonly kind: "tuple";
+  readonly elements: readonly IrTupleElement[];
+}
+
+export interface IrUnionType {
+  readonly kind: "union";
+  readonly types: readonly IrType[];
+}
+
+export interface IrIntersectionType {
+  readonly kind: "intersection";
+  readonly types: readonly IrType[];
+}
+
+export interface IrObjectType {
+  readonly kind: "object";
+  readonly members: readonly IrMember[];
+}
+
+/** `object[index]`, for example `components["schemas"]`. */
+export interface IrIndexedAccessType {
+  readonly kind: "indexedAccess";
+  readonly object: IrType;
+  readonly index: IrType;
+}
+
+/** `readonly T` (the only type operator the generator emits). */
+export interface IrReadonlyType {
+  readonly kind: "readonly";
+  readonly type: IrType;
+}
+
+/**
+ * Text printed as is. Escape hatch for types that come from outside the IR, for example output of
+ * legacy `ts.Node` callbacks converted by the type-AST bridge (ENGINEERING_PLAN 6.3). The text is
+ * written as if it started at column 0: each line after the first gets the indentation of the
+ * position where the type is printed. Known limit: this also indents the continuation lines of a
+ * template literal that spans lines, which TypeScript keeps verbatim (ADR-004).
+ */
+export interface IrRawType {
+  readonly kind: "raw";
+  readonly text: string;
+  /**
+   * The outside node the text was printed from, opaque to the IR. While the Node API still
+   * returns `ts.Node`s (until Phase 6), the bridge hands this node back unchanged, exactly as the
+   * original did. Removed with the reverse bridge in Phase 6.
+   */
+  readonly origin?: unknown;
+}
+
+export type IrType =
+  | IrKeywordType
+  | IrStringLiteralType
+  | IrNumberLiteralType
+  | IrBooleanLiteralType
+  | IrReferenceType
+  | IrArrayType
+  | IrTupleType
+  | IrUnionType
+  | IrIntersectionType
+  | IrObjectType
+  | IrIndexedAccessType
+  | IrReadonlyType
+  | IrRawType;
+
+/** A comment printed on its own line before a node; a node may have several, printed in order. */
+export type IrComment =
+  /** `/*text*\/`: `text` is the comment body, for example `* @description Hello `. */
+  | { readonly kind: "block"; readonly text: string }
+  /** `//text`. */
+  | { readonly kind: "line"; readonly text: string };
+
+/** Property key: identifier, quoted string, or number, as decided by `toPropertyName`. */
+export type IrPropertyName =
+  | { readonly kind: "identifier"; readonly text: string }
+  | { readonly kind: "string"; readonly value: string }
+  | { readonly kind: "number"; readonly text: string };
+
+export interface IrPropertySignature {
+  readonly kind: "property";
+  readonly name: IrPropertyName;
+  readonly type: IrType;
+  readonly isOptional: boolean;
+  readonly isReadonly: boolean;
+  readonly comments: readonly IrComment[];
+}
+
+/** `[parameterName: parameterType]: type`. */
+export interface IrIndexSignature {
+  readonly kind: "indexSignature";
+  readonly parameterName: string;
+  readonly parameterType: IrType;
+  readonly type: IrType;
+  readonly isReadonly: boolean;
+  readonly comments: readonly IrComment[];
+}
+
+export type IrMember = IrPropertySignature | IrIndexSignature;
+
+export interface IrInterfaceDeclaration {
+  readonly kind: "interface";
+  readonly name: string;
+  readonly isExported: boolean;
+  readonly members: readonly IrMember[];
+  readonly comments: readonly IrComment[];
+}
+
+export interface IrTypeAliasDeclaration {
+  readonly kind: "typeAlias";
+  readonly name: string;
+  readonly isExported: boolean;
+  readonly type: IrType;
+  readonly comments: readonly IrComment[];
+}
+
+/** `name` is printed as given (already sanitized or quoted by the enum naming rules). */
+export interface IrEnumMember {
+  readonly name: string;
+  readonly value: string | number;
+  readonly comments: readonly IrComment[];
+}
+
+export interface IrEnumDeclaration {
+  readonly kind: "enum";
+  readonly name: string;
+  readonly isExported: boolean;
+  readonly members: readonly IrEnumMember[];
+  readonly comments: readonly IrComment[];
+}
+
+/** `const name: type = [values];` (the `--enum-values` and `--make-paths-enum` arrays). */
+export interface IrConstArrayDeclaration {
+  readonly kind: "constArray";
+  readonly name: string;
+  readonly isExported: boolean;
+  readonly type: IrType;
+  readonly values: readonly (string | number)[];
+  readonly comments: readonly IrComment[];
+}
+
+/** A declaration printed as is: footer helpers and injected code. */
+export interface IrRawDeclaration {
+  readonly kind: "rawDeclaration";
+  readonly text: string;
+  /** The type name the text declares, when known (helper types), so the footer can find it. */
+  readonly name?: string;
+}
+
+export type IrDeclaration =
+  | IrInterfaceDeclaration
+  | IrTypeAliasDeclaration
+  | IrEnumDeclaration
+  | IrConstArrayDeclaration
+  | IrRawDeclaration;

package/src/domain/ir/normalize.ts

@@ -0,0 +1,51 @@
+import type { IrKeyword, IrType } from "./nodes.js";
+
+/**
+ * Keywords that `dedupeTypes` removes when repeated. The original (`tsDedupe`) treats these as
+ * primitives; `unknown` is not one of them and is kept even when repeated.
+ */
+const DEDUPLICATED_KEYWORDS: ReadonlySet<IrKeyword> = new Set([
+  "boolean",
+  "never",
+  "null",
+  "number",
+  "string",
+  "undefined",
+]);
+
+/**
+ * Remove repeated primitive keywords from a union or intersection member list, keeping the first
+ * occurrence and the order. Literals, references and object types are never removed, even when
+ * equal: this matches the original `tsDedupe`, which compares only node kinds of primitives.
+ */
+export function dedupeTypes(types: readonly IrType[]): IrType[] {
+  const seenKeywords = new Set<IrKeyword>();
+  const kept: IrType[] = [];
+  for (const type of types) {
+    if (type.kind === "keyword" && DEDUPLICATED_KEYWORDS.has(type.keyword)) {
+      if (seenKeywords.has(type.keyword)) {
+        continue;
+      }
+      seenKeywords.add(type.keyword);
+    }
+    kept.push(type);
+  }
+  return kept;
+}
+
+/**
+ * The collation the original `getEntries` uses for `alphabetize`. Natural order: `a2` sorts before
+ * `a10`. It is locale-based on purpose, to stay byte-compatible with the original output.
+ */
+const ALPHABETIZE_COLLATOR = new Intl.Collator("en-us", { numeric: true });
+
+/**
+ * Sort `[key, value]` entries by key like the original `alphabetize` option (ENGINEERING_PLAN 4.1
+ * `sortMembers`). The original sorts source entries before it builds members, so transformers call
+ * this on entries, not on finished IR members. The sort is stable and returns a new array.
+ */
+export function sortEntriesByKey<T>(entries: readonly (readonly [string, T])[]): [string, T][] {
+  return entries
+    .map(([key, value]): [string, T] => [key, value])
+    .sort(([left], [right]) => ALPHABETIZE_COLLATOR.compare(left, right));
+}

package/src/domain/ir/property-name.ts

@@ -0,0 +1,28 @@
+import type { IrPropertyName } from "./nodes.js";
+
+/** A name that can be written without quotes. */
+export const JS_PROPERTY_INDEX_RE = /^[A-Za-z_$][A-Za-z_$0-9]*$/;
+
+function isNonNegativeNumberText(index: string): boolean {
+  return String(Number(index)) === index && index[0] !== "-";
+}
+
+/**
+ * Choose how a property key is written, following the original `tsPropertyIndex`: non-negative
+ * numbers (and strings that are exactly such a number) unquoted, valid identifiers unquoted,
+ * everything else as a quoted string. Negative numbers become strings because `-1` is not a valid
+ * property key.
+ */
+export function toPropertyName(index: string | number): IrPropertyName {
+  if (typeof index === "number") {
+    return index < 0
+      ? { kind: "string", value: String(index) }
+      : { kind: "number", text: String(index) };
+  }
+  if (isNonNegativeNumberText(index)) {
+    return { kind: "number", text: index };
+  }
+  return JS_PROPERTY_INDEX_RE.test(index)
+    ? { kind: "identifier", text: index }
+    : { kind: "string", value: index };
+}

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