openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/application/ports/schema-loader.ts

@@ -0,0 +1,32 @@
+import type { OpenAPI3, SchemaSource } from "../../types.js";
+
+/**
+ * Where `$ref` documents may be loaded from (threat model R1 and R2, ADR-017). An unset limit
+ * allows everything, as in openapi-typescript; the root document is never limited.
+ */
+export interface RefAccess {
+  /** Local `$ref` files must be in this directory or below it (a `file:` URL). */
+  readonly localRoot?: URL;
+  /** Remote `$ref` documents must come from these hosts (`name` or `name:port`); `[]`: none. */
+  readonly remoteHosts?: readonly string[];
+}
+
+export interface SchemaLoadRequest {
+  readonly source: SchemaSource;
+  /** The base for relative `$ref`s of a source that is not a URL (a directory URL). */
+  readonly cwd: URL;
+  /** Lint with the Redocly config before bundling; off with the `lint: false` option. */
+  readonly shouldLint: boolean;
+  readonly refAccess: RefAccess;
+}
+
+/**
+ * Read, validate and bundle an OpenAPI 3 document into one document (ENGINEERING_PLAN 4.5).
+ * Fails with a typed error (ADR-011): `SCHEMA_SOURCE_*`, `SCHEMA_LOAD_FAILED`,
+ * `SCHEMA_REF_FORBIDDEN`,
+ * `SCHEMA_PARSE_FAILED`, `SCHEMA_VERSION_UNSUPPORTED`, `SCHEMA_INVALID`, `SCHEMA_REF_INVALID`,
+ * `SCHEMA_TOO_DEEP` or `SCHEMA_KEY_UNSUPPORTED`.
+ */
+export interface SchemaLoader {
+  load(request: SchemaLoadRequest): Promise<OpenAPI3>;
+}

package/src/application/print/comment-writer.ts

@@ -0,0 +1,91 @@
+import { assertNever } from "../../domain/assert-never.js";
+import type { IrComment } from "../../domain/ir/nodes.js";
+import { isLineBreak, type TextWriter } from "./text-writer.js";
+
+const LINE_FEED = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+
+/** Single-line white space as the TypeScript scanner defines it (`isWhiteSpaceSingleLine`). */
+const SINGLE_LINE_WHITESPACE = new Set([
+  0x20, 0x09, 0x0b, 0x0c, 0xa0, 0x85, 0x1680, 0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005,
+  0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x200b, 0x202f, 0x205f, 0x3000, 0xfeff,
+]);
+const TAB = 0x09;
+
+/** Start offsets of every line, splitting at CR LF, CR, LF, U+2028 and U+2029 like TypeScript. */
+function computeLineStarts(text: string): number[] {
+  const starts = [0];
+  for (let position = 0; position < text.length; position++) {
+    const code = text.charCodeAt(position);
+    if (code === CARRIAGE_RETURN && text.charCodeAt(position + 1) === LINE_FEED) {
+      position++;
+    }
+    if (isLineBreak(code)) {
+      starts.push(position + 1);
+    }
+  }
+  return starts;
+}
+
+/** Leading white space width of `text[start, end)`, counting a tab up to the next tab stop. */
+function measureIndent(text: string, start: number, end: number, tabSize: number): number {
+  let width = 0;
+  for (
+    let position = start;
+    position < end && SINGLE_LINE_WHITESPACE.has(text.charCodeAt(position));
+    position++
+  ) {
+    width += text.charCodeAt(position) === TAB ? tabSize - (width % tabSize) : 1;
+  }
+  return width;
+}
+
+/** Write the line `text[start, end)` trimmed; a blank line becomes a bare line break. */
+function writeTrimmedLine(writer: TextWriter, text: string, start: number, end: number): void {
+  const lineEnd = Math.min(text.length, end - 1);
+  const line = text.substring(start, lineEnd).trim();
+  if (line.length === 0) {
+    writer.rawWrite(writer.options.newLine);
+    return;
+  }
+  writer.write(line);
+  if (lineEnd !== text.length) {
+    writer.writeLine();
+  }
+}
+
+/**
+ * Write a `/*...*\/` comment the way the TypeScript printer writes a synthesized one: every line
+ * after the first is re-indented to the current level plus the line's own leading white space, and
+ * every line is trimmed. (TypeScript only does this for comments whose second character is `*`,
+ * which is always true for a synthesized block comment, so there is no other branch.)
+ */
+function writeBlockComment(writer: TextWriter, body: string): void {
+  const text = `/*${body}*/`;
+  const lineStarts = computeLineStarts(text);
+  const { indentSize } = writer.options;
+  lineStarts.forEach((start, line) => {
+    const end = line + 1 === lineStarts.length ? text.length + 1 : (lineStarts[line + 1] as number);
+    if (line > 0) {
+      const spaces = writer.indent * indentSize + measureIndent(text, start, end, indentSize);
+      writer.rawWrite(" ".repeat(spaces));
+    }
+    writeTrimmedLine(writer, text, start, end);
+  });
+}
+
+/** Write a comment on its own line before the node it belongs to. */
+export function writeLeadingComment(writer: TextWriter, comment: IrComment): void {
+  switch (comment.kind) {
+    case "block":
+      writeBlockComment(writer, comment.text);
+      break;
+    case "line":
+      writer.writeLine();
+      writer.write(`//${comment.text}`);
+      break;
+    default:
+      assertNever(comment);
+  }
+  writer.writeLine();
+}

package/src/application/print/declaration-printer.ts

@@ -0,0 +1,100 @@
+import { assertNever } from "../../domain/assert-never.js";
+import type {
+  IrComment,
+  IrConstArrayDeclaration,
+  IrDeclaration,
+  IrEnumDeclaration,
+  IrEnumMember,
+  IrInterfaceDeclaration,
+  IrTypeAliasDeclaration,
+} from "../../domain/ir/nodes.js";
+import { writeLeadingComment } from "./comment-writer.js";
+import { printEscapedString, printNumberLiteral } from "./literal-text.js";
+import type { TextWriter } from "./text-writer.js";
+import { writeMember, writeMultiLineList, writeType } from "./type-printer.js";
+
+/** Enum initializers and array elements are expressions: strings use printer escaping. */
+function printValue(value: string | number): string {
+  return typeof value === "number" ? printNumberLiteral(value) : printEscapedString(value);
+}
+
+function writeHead(
+  writer: TextWriter,
+  declaration: { comments: readonly IrComment[]; isExported: boolean },
+): void {
+  for (const comment of declaration.comments) {
+    writeLeadingComment(writer, comment);
+  }
+  if (declaration.isExported) {
+    writer.write("export ");
+  }
+}
+
+function writeInterface(writer: TextWriter, declaration: IrInterfaceDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`interface ${declaration.name} {`);
+  writeMultiLineList(
+    writer,
+    declaration.members,
+    { delimiter: "", isLineBreakWhenEmpty: true },
+    (member) => writeMember(writer, member),
+  );
+  writer.write("}");
+}
+
+function writeTypeAlias(writer: TextWriter, declaration: IrTypeAliasDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`type ${declaration.name} = `);
+  writeType(writer, declaration.type);
+  writer.write(";");
+}
+
+function writeEnumMember(writer: TextWriter, member: IrEnumMember): void {
+  for (const comment of member.comments) {
+    writeLeadingComment(writer, comment);
+  }
+  writer.write(`${member.name} = ${printValue(member.value)}`);
+}
+
+function writeEnum(writer: TextWriter, declaration: IrEnumDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`enum ${declaration.name} {`);
+  writeMultiLineList(
+    writer,
+    declaration.members,
+    { delimiter: ",", isLineBreakWhenEmpty: true },
+    (member) => writeEnumMember(writer, member),
+  );
+  writer.write("}");
+}
+
+function writeConstArray(writer: TextWriter, declaration: IrConstArrayDeclaration): void {
+  writeHead(writer, declaration);
+  writer.write(`const ${declaration.name}: `);
+  writeType(writer, declaration.type);
+  writer.write(` = [${declaration.values.map(printValue).join(", ")}];`);
+}
+
+/** Write one top-level declaration, starting on a new line. */
+export function writeDeclaration(writer: TextWriter, declaration: IrDeclaration): void {
+  writer.writeLine();
+  switch (declaration.kind) {
+    case "interface":
+      writeInterface(writer, declaration);
+      break;
+    case "typeAlias":
+      writeTypeAlias(writer, declaration);
+      break;
+    case "enum":
+      writeEnum(writer, declaration);
+      break;
+    case "constArray":
+      writeConstArray(writer, declaration);
+      break;
+    case "rawDeclaration":
+      writer.write(declaration.text);
+      break;
+    default:
+      assertNever(declaration);
+  }
+}

package/src/application/print/literal-text.ts

@@ -0,0 +1,62 @@
+import type { IrStringEncoding } from "../../domain/ir/nodes.js";
+
+/**
+ * Escapes TypeScript's printer uses inside a double-quoted string literal (its `escapeString`).
+ * Other characters below U+0020 use `\uXXXX`; so does every non-ASCII code unit
+ * (`escapeNonAsciiString`).
+ */
+const NAMED_ESCAPES: ReadonlyMap<number, string> = new Map([
+  [0x09, "\\t"],
+  [0x0b, "\\v"],
+  [0x0c, "\\f"],
+  [0x08, "\\b"],
+  [0x0d, "\\r"],
+  [0x0a, "\\n"],
+  [0x5c, "\\\\"],
+  [0x22, '\\"'],
+]);
+const NULL_CODE = 0x00;
+const FIRST_PRINTABLE_ASCII = 0x20;
+const LAST_ASCII = 0x7f;
+const DIGIT_ZERO = 0x30;
+const DIGIT_NINE = 0x39;
+
+function toUtf16Escape(code: number): string {
+  return `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+
+function isDigit(code: number): boolean {
+  return code >= DIGIT_ZERO && code <= DIGIT_NINE;
+}
+
+/** `\0` must not be followed by a digit, or it would read as an octal escape. */
+function escapeCodeUnit(code: number, nextCode: number): string {
+  if (code === NULL_CODE) {
+    return isDigit(nextCode) ? "\\x00" : "\\0";
+  }
+  const named = NAMED_ESCAPES.get(code);
+  if (named !== undefined) {
+    return named;
+  }
+  const isPlainAscii = code >= FIRST_PRINTABLE_ASCII && code <= LAST_ASCII;
+  return isPlainAscii ? String.fromCharCode(code) : toUtf16Escape(code);
+}
+
+/** A double-quoted string literal as the TypeScript printer writes a synthesized one. */
+export function printEscapedString(value: string): string {
+  let escaped = "";
+  for (let index = 0; index < value.length; index++) {
+    escaped += escapeCodeUnit(value.charCodeAt(index), value.charCodeAt(index + 1));
+  }
+  return `"${escaped}"`;
+}
+
+/** A string literal in the given encoding (see `IrStringEncoding`). */
+export function printStringLiteral(value: string, encoding: IrStringEncoding): string {
+  return encoding === "json" ? JSON.stringify(value) : printEscapedString(value);
+}
+
+/** A number as the original writes it: the absolute value's `String()` text, with a minus sign. */
+export function printNumberLiteral(value: number): string {
+  return value < 0 ? `-${String(Math.abs(value))}` : String(value);
+}

package/src/application/print/print-nodes.ts

@@ -0,0 +1,62 @@
+import type { IrDeclaration, IrMember, IrType } from "../../domain/ir/nodes.js";
+import { writeDeclaration } from "./declaration-printer.js";
+import { DEFAULT_PRINT_OPTIONS, type PrintOptions } from "./print-options.js";
+import { TextWriter } from "./text-writer.js";
+import { writeMember, writeType } from "./type-printer.js";
+
+/**
+ * Print declarations as a TypeScript file body: one declaration per line, a line break at the end,
+ * and nothing for an empty list. Pure and deterministic (ENGINEERING_PLAN §4.3).
+ */
+export function printNodes(
+  declarations: readonly IrDeclaration[],
+  options: PrintOptions = DEFAULT_PRINT_OPTIONS,
+): string {
+  const writer = new TextWriter(options);
+  for (const declaration of declarations) {
+    writeDeclaration(writer, declaration);
+  }
+  writer.writeLine();
+  return writer.text;
+}
+
+/** Anything the IR printer can print at the top level of a file. */
+export type IrPrintable = IrDeclaration | IrMember | IrType;
+
+const DECLARATION_KINDS: ReadonlySet<string> = new Set<IrDeclaration["kind"]>([
+  "interface",
+  "typeAlias",
+  "enum",
+  "constArray",
+  "rawDeclaration",
+]);
+const MEMBER_KINDS: ReadonlySet<string> = new Set<IrMember["kind"]>(["property", "indexSignature"]);
+
+function writePrintable(writer: TextWriter, node: IrPrintable): void {
+  if (DECLARATION_KINDS.has(node.kind)) {
+    writeDeclaration(writer, node as IrDeclaration);
+    return;
+  }
+  writer.writeLine();
+  if (MEMBER_KINDS.has(node.kind)) {
+    writeMember(writer, node as IrMember);
+  } else {
+    writeType(writer, node as IrType);
+  }
+}
+
+/**
+ * Print declarations, members or types, one per line, as the TypeScript printer prints such nodes
+ * placed in a file (the original `astToString` accepted any node).
+ */
+export function printFragments(
+  nodes: readonly IrPrintable[],
+  options: PrintOptions = DEFAULT_PRINT_OPTIONS,
+): string {
+  const writer = new TextWriter(options);
+  for (const node of nodes) {
+    writePrintable(writer, node);
+  }
+  writer.writeLine();
+  return writer.text;
+}

package/src/application/print/print-options.ts

@@ -0,0 +1,11 @@
+/**
+ * Formatting rules of the printer as data (ENGINEERING_PLAN §4.3). The defaults reproduce the
+ * TypeScript printer that the original generator used: 4-space indentation and LF line endings.
+ */
+export interface PrintOptions {
+  /** Columns per indentation level; also the tab width used when re-indenting comment lines. */
+  readonly indentSize: number;
+  readonly newLine: string;
+}
+
+export const DEFAULT_PRINT_OPTIONS: PrintOptions = { indentSize: 4, newLine: "\n" };

package/src/application/print/text-writer.ts

@@ -0,0 +1,83 @@
+import type { PrintOptions } from "./print-options.js";
+
+const LINE_FEED = 0x0a;
+const CARRIAGE_RETURN = 0x0d;
+const LINE_SEPARATOR = 0x2028;
+const PARAGRAPH_SEPARATOR = 0x2029;
+
+/** Line breaks as the TypeScript scanner defines them (`isLineBreak`). */
+export function isLineBreak(code: number): boolean {
+  return (
+    code === LINE_FEED ||
+    code === CARRIAGE_RETURN ||
+    code === LINE_SEPARATOR ||
+    code === PARAGRAPH_SEPARATOR
+  );
+}
+
+/**
+ * Output buffer with indentation, modeled on the TypeScript printer's text writer: `write` indents
+ * text that starts a line, `rawWrite` never does, and `writeLine` does nothing at the start of a
+ * line. Matching these rules is what makes comment re-indentation byte-identical to the original.
+ */
+export class TextWriter {
+  readonly #options: PrintOptions;
+  #output = "";
+  #indent = 0;
+  #isAtLineStart = true;
+
+  constructor(options: PrintOptions) {
+    this.#options = options;
+  }
+
+  get indent(): number {
+    return this.#indent;
+  }
+
+  get options(): PrintOptions {
+    return this.#options;
+  }
+
+  get text(): string {
+    return this.#output;
+  }
+
+  increaseIndent(): void {
+    this.#indent++;
+  }
+
+  decreaseIndent(): void {
+    this.#indent--;
+  }
+
+  /** Write text, indenting it first when it starts a line. */
+  write(text: string): void {
+    if (text.length === 0) {
+      return;
+    }
+    const prefix = this.#isAtLineStart ? this.indentString(this.#indent) : "";
+    this.rawWrite(prefix + text);
+  }
+
+  /** Write text exactly as given. */
+  rawWrite(text: string): void {
+    this.#output += text;
+    this.#updateLineStart(text);
+  }
+
+  /** End the current line; does nothing when nothing has been written on it yet. */
+  writeLine(): void {
+    if (!this.#isAtLineStart) {
+      this.rawWrite(this.#options.newLine);
+    }
+  }
+
+  indentString(level: number): string {
+    return " ".repeat(level * this.#options.indentSize);
+  }
+
+  // Like TypeScript: any write leaves the writer mid-line unless the text ends with a line break.
+  #updateLineStart(text: string): void {
+    this.#isAtLineStart = text.length > 0 && isLineBreak(text.charCodeAt(text.length - 1));
+  }
+}