openapi-typesafe 1.0.0-rc.2 → 1.0.0-rc.4

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

@@ -0,0 +1,138 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ClaimedFile } from "../../application/ports/file-system.js";
+import { creationPath, type FileNumber, type PathQueries } from "./file-identity.js";
+
+/**
+ * Claiming an output on Node's `fs` (ADR-043, decision 1): the file is opened for appending,
+ * which creates it when it is missing (also through a symbolic link) and never truncates it.
+ * The device and file number of the open file are its identity. A claim or a write that fails
+ * removes the directories it created.
+ */
+
+/**
+ * The directories that do not exist yet on the way to `directory`, deepest first: the ones a
+ * recursive `fs.mkdirSync` creates. They are listed before it runs, in the form of `directory`
+ * itself: on Windows the path that `fs.mkdirSync` returns did not match that form, so comparing
+ * with it found no new directory and a failed run left them behind.
+ */
+export function missingDirectories(
+  directory: string,
+  exists: (candidate: string) => boolean,
+): string[] {
+  const missing: string[] = [];
+  for (let current = directory; !exists(current); current = path.dirname(current)) {
+    missing.push(current);
+    if (path.dirname(current) === current) {
+      break;
+    }
+  }
+  return missing;
+}
+
+/**
+ * The identity of an open file: its device and file number, or its stored path on a file system
+ * that reports the file number 0 (FAT, some network shares), which proves nothing.
+ */
+export function claimIdentity(number: FileNumber, storedPath: () => string): string {
+  return number.file === 0n ? `path:${storedPath()}` : `${number.device}:${number.file}`;
+}
+
+function identityOf(descriptor: number, filePath: string): string {
+  const status = fs.fstatSync(descriptor, { bigint: true });
+  return claimIdentity({ device: status.dev, file: status.ino }, () =>
+    fs.realpathSync.native(filePath),
+  );
+}
+
+function errorCodeOf(error: unknown): unknown {
+  return error instanceof Error && "code" in error ? error.code : undefined;
+}
+
+/** Remove the new directories, deepest first, until one holds another file. */
+function removeDirectories(directories: readonly string[]): void {
+  for (const directory of directories) {
+    try {
+      fs.rmdirSync(directory);
+    } catch (error) {
+      const code = errorCodeOf(error);
+      // Another output or the user put a file there since: the directory and its parents stay.
+      if (code === "ENOTEMPTY" || code === "EEXIST") {
+        return;
+      }
+      // Removed since: nothing to remove, but its parents may still be empty. Windows also gives
+      // ENOENT for a file put in its place, which must fail like any other path it cannot remove.
+      if (code !== "ENOENT" || fs.lstatSync(directory, { throwIfNoEntry: false }) !== undefined) {
+        throw error;
+      }
+    }
+  }
+}
+
+/**
+ * Create `directory` and give the directories that this created. Through a link to a missing
+ * directory it creates the link's target, as a write through the link would, so the path to
+ * create and the new directories are real paths, where links are already followed. A recursive
+ * `mkdir` that fails part of the way (a directory name too long for the file system) keeps the
+ * directories above the failing one, so the ones that exist now are removed here.
+ */
+function createDirectory(directory: string, queries: PathQueries): string[] {
+  const target = creationPath(directory, queries);
+  const missing = missingDirectories(target, fs.existsSync);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+  } catch (error) {
+    removeDirectories(missing.filter((created) => fs.existsSync(created)));
+    throw error;
+  }
+  return missing;
+}
+
+/** Open `filePath` for appending, which creates it, and give its identity and whether it is new. */
+function openClaim(filePath: string): { identity: string; createdFile: string | undefined } {
+  const isCreated = !fs.existsSync(filePath);
+  const descriptor = fs.openSync(filePath, "a");
+  try {
+    const identity = identityOf(descriptor, filePath);
+    // A link to a missing file created its target: that file is what the claim removes.
+    return { identity, createdFile: isCreated ? fs.realpathSync.native(filePath) : undefined };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+/**
+ * Claim the file at `filePath`; the caller turns a failure into a typed error. A claim that fails
+ * after creating directories (a file name too long for the file system) removes them again.
+ */
+export function claimFileAt(filePath: string, queries: PathQueries): ClaimedFile {
+  const directories = createDirectory(path.dirname(filePath), queries);
+  let opened: ReturnType<typeof openClaim>;
+  try {
+    opened = openClaim(filePath);
+  } catch (error) {
+    removeDirectories(directories);
+    throw error;
+  }
+  const { identity, createdFile } = opened;
+  return {
+    identity,
+    release: () => {
+      if (createdFile !== undefined) {
+        fs.rmSync(createdFile, { force: true });
+      }
+      removeDirectories(directories);
+    },
+  };
+}
+
+/** Write `contents` to `filePath`, creating its directory; a failed write removes what it made. */
+export function writeFileAt(filePath: string, contents: string, queries: PathQueries): void {
+  const directories = createDirectory(path.dirname(filePath), queries);
+  try {
+    fs.writeFileSync(filePath, contents, "utf8");
+  } catch (error) {
+    removeDirectories(directories);
+    throw error;
+  }
+}

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

@@ -0,0 +1,137 @@
+import path from "node:path";
+
+/**
+ * The identity of a file path, also of one that does not exist yet (an output before the first
+ * run). Two paths are one file when their keys are equal: the real path of the nearest existing
+ * ancestor (links resolved, letter case as stored on disk) followed by the segments that do not
+ * exist yet, compared in the letter case rules of the file system that will hold them. Equal keys
+ * prove one file; different keys do not prove two (Unicode normalization, full case folding):
+ * the CLI claims every output before writing to decide those (ADR-043, decision 1).
+ */
+
+/** A device and a file number: one file, also through a hard link. */
+export interface FileNumber {
+  readonly device: bigint;
+  readonly file: bigint;
+}
+
+/** The file-system queries the identity needs; Node's `fs` in production, a fake in tests. */
+export interface PathQueries {
+  /** The file number of a path, following links; undefined when it cannot be read. */
+  status(filePath: string): FileNumber | undefined;
+  /** The path with every link resolved, in the letter case stored on disk. */
+  realPath(filePath: string): string;
+  /** The names in a directory; empty when it cannot be listed. */
+  entries(directory: string): readonly string[];
+  /** The target of a symbolic link as written in it; undefined for a path that is no link. */
+  linkTarget(filePath: string): string | undefined;
+}
+
+/**
+ * The most links followed for one path. Linux follows at most 40 (MAXSYMLINKS) and macOS 32
+ * before it fails with ELOOP; a longer chain is a loop, and the path is taken as missing.
+ */
+const MAX_LINK_HOPS = 40;
+
+/** Whether two file numbers name one file. */
+export function isSameFileNumber(left: FileNumber, right: FileNumber): boolean {
+  // Some file systems (FAT, some network shares) report no file number: 0 then proves nothing.
+  return left.file !== 0n && left.file === right.file && left.device === right.device;
+}
+
+function hasLetters(text: string): boolean {
+  return text.toLowerCase() !== text.toUpperCase();
+}
+
+function flipCase(text: string): string {
+  return [...text]
+    .map((character) => {
+      const upper = character.toUpperCase();
+      return character === upper ? character.toLowerCase() : upper;
+    })
+    .join("");
+}
+
+/** Whether a directory entry is also found under its name in the other letter case. */
+function isFoundInOtherCase(entryPath: string, queries: PathQueries): boolean | undefined {
+  const status = queries.status(entryPath);
+  if (!status) {
+    return undefined;
+  }
+  const flipped = path.join(path.dirname(entryPath), flipCase(path.basename(entryPath)));
+  const flippedStatus = queries.status(flipped);
+  return flippedStatus !== undefined && isSameFileNumber(status, flippedStatus);
+}
+
+/**
+ * Whether new names in `directory` ignore letter case. It is asked of the file system, not
+ * assumed from the OS: macOS and Windows volumes can be case-sensitive, and Linux mounts can
+ * ignore case. An entry of the directory is looked up in the other case; without one with
+ * letters, the directory itself is. With nothing to look up, names are taken as case-sensitive.
+ */
+function ignoresCase(directory: string, queries: PathQueries): boolean {
+  const candidates = [
+    ...queries
+      .entries(directory)
+      .filter(hasLetters)
+      .map((name) => path.join(directory, name)),
+    ...(hasLetters(path.basename(directory)) ? [directory] : []),
+  ];
+  for (const candidate of candidates) {
+    const answer = isFoundInOtherCase(candidate, queries);
+    if (answer !== undefined) {
+      return answer;
+    }
+  }
+  return false;
+}
+
+/**
+ * The nearest ancestor of `filePath` that exists (or the path itself), and the rest below it. A
+ * link to a missing file or directory is followed to its target, which a write would create: so
+ * `link/x.ts` with `link -> missing` is `missing/x.ts`. A relative target is read from the real
+ * directory of the link, as the system does: with `a -> real/sub` and
+ * `real/sub/link -> ../missing`, `a/link` is `real/missing`, not `missing`.
+ */
+function nearestExisting(filePath: string, queries: PathQueries): [string, string[]] {
+  const missing: string[] = [];
+  let current = path.resolve(filePath);
+  let hops = 0;
+  while (queries.status(current) === undefined) {
+    const target = hops < MAX_LINK_HOPS ? queries.linkTarget(current) : undefined;
+    if (target !== undefined) {
+      current = path.resolve(queries.realPath(path.dirname(current)), target);
+      hops += 1;
+      continue;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    missing.unshift(path.basename(current));
+    current = parent;
+  }
+  return [current, missing];
+}
+
+/**
+ * The path that a write to `filePath` creates, with links followed also where their target is
+ * missing: `link/x.ts` with `link -> missing` is the real path of `missing/x.ts`. `mkdir` does not
+ * follow a link to a missing directory on Linux and Windows, so the directories are created here.
+ */
+export function creationPath(filePath: string, queries: PathQueries): string {
+  const [existing, missing] = nearestExisting(filePath, queries);
+  return path.join(queries.realPath(existing), ...missing);
+}
+
+/** The key of a path: equal keys are one file, whether or not it exists yet. */
+export function fileIdentityKey(filePath: string, queries: PathQueries): string {
+  const [existing, missing] = nearestExisting(filePath, queries);
+  const realExisting = queries.realPath(existing);
+  if (missing.length === 0) {
+    return realExisting;
+  }
+  const isCaseIgnored = ignoresCase(realExisting, queries);
+  const rest = isCaseIgnored ? missing.map((segment) => segment.toLowerCase()) : missing;
+  return path.join(realExisting, ...rest);
+}

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

@@ -1,7 +1,21 @@
 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";
+import type {
+  ClaimedFile,
+  DirectoryCheck,
+  FileClaims,
+  FileIdentity,
+  FileReader,
+  FileWriter,
+} from "../../application/ports/file-system.js";
+import { ERROR_CODES, type ErrorCode, OpenAPITypesafeError } from "../../domain/errors.js";
+import { claimFileAt, writeFileAt } from "./file-claims.js";
+import {
+  type FileNumber,
+  fileIdentityKey,
+  isSameFileNumber,
+  type PathQueries,
+} from "./file-identity.js";
 
 /** The file ports on Node's `fs`, with the failures as typed errors (ADR-011). */
 
@@ -9,36 +23,149 @@ function causeMessage(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }
 
-class NodeFileSystem implements FileReader, FileWriter {
+/**
+ * The file number of a path, or undefined when it cannot be read. A missing output is the common
+ * case; any other failure (no access, a file used as a directory) is reported by the read or write
+ * that follows, so the identity check does not report it a second time.
+ */
+function statusOf(filePath: string): FileNumber | undefined {
+  try {
+    const status = fs.statSync(filePath, { bigint: true });
+    return { device: status.dev, file: status.ino };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The native `realpath` resolves symbolic links and returns the letter case stored on disk, which
+ * the JavaScript one does not do on a case-insensitive file system. A path that vanished since its
+ * status was read keeps its own spelling.
+ */
+function realPathOf(filePath: string): string {
+  try {
+    return fs.realpathSync.native(filePath);
+  } catch {
+    return filePath;
+  }
+}
+
+/** A directory that cannot be listed has no entry to tell its letter case rules by. */
+function entriesOf(directory: string): readonly string[] {
+  try {
+    return fs.readdirSync(directory);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The target of a symbolic link, as written in it; undefined for a path that is no link or cannot
+ * be read. The key then treats the path as missing, and the claim at write time decides.
+ */
+function linkTargetOf(filePath: string): string | undefined {
+  try {
+    return fs.readlinkSync(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+const NODE_PATH_QUERIES: PathQueries = {
+  status: statusOf,
+  realPath: realPathOf,
+  entries: entriesOf,
+  linkTarget: linkTargetOf,
+};
+
+/** The path of a `file:` URL, or undefined for a URL that names no file on this platform. */
+function localPathOf(file: URL): string | undefined {
+  try {
+    return fileURLToPath(file);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A failed read or write as a typed error. The location is named by its path, or by the URL when
+ * it names no local file: computing the path must not throw a second, untyped error here.
+ */
+function fileError(code: ErrorCode, verb: string, file: URL, cause: unknown): OpenAPITypesafeError {
+  const name = localPathOf(file) ?? file.href;
+  return new OpenAPITypesafeError({
+    code,
+    message: `Cannot ${verb} ${name}: ${causeMessage(cause)}`,
+    details: { file: name },
+    cause,
+  });
+}
+
+/** Run a step that writes `file`, with its failure as `OUTPUT_WRITE_FAILED`. */
+function typedWrite<T>(file: URL, step: () => T): T {
+  try {
+    return step();
+  } catch (cause) {
+    throw fileError(ERROR_CODES.OUTPUT_WRITE_FAILED, "write", file, cause);
+  }
+}
+
+class NodeFileSystem implements FileReader, FileWriter, FileIdentity, DirectoryCheck, FileClaims {
   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,
-      });
+      throw fileError(ERROR_CODES.OUTPUT_READ_FAILED, "read", file, cause);
     }
   }
 
   writeText(file: URL, contents: string): void {
     try {
-      fs.mkdirSync(new URL(".", file), { recursive: true });
-      fs.writeFileSync(file, contents, "utf8");
+      writeFileAt(fileURLToPath(file), contents, NODE_PATH_QUERIES);
     } catch (cause) {
-      throw new OpenAPITypesafeError({
-        code: ERROR_CODES.OUTPUT_WRITE_FAILED,
-        message: `Cannot write ${fileURLToPath(file)}: ${causeMessage(cause)}`,
-        details: { file: fileURLToPath(file) },
-        cause,
-      });
+      throw fileError(ERROR_CODES.OUTPUT_WRITE_FAILED, "write", file, cause);
+    }
+  }
+
+  claimFile(file: URL): ClaimedFile {
+    const claim = typedWrite(file, () => claimFileAt(fileURLToPath(file), NODE_PATH_QUERIES));
+    return {
+      identity: claim.identity,
+      release: () => typedWrite(file, () => claim.release()),
+    };
+  }
+
+  isDirectory(file: URL): boolean {
+    try {
+      return fs.statSync(file).isDirectory();
+    } catch {
+      // Missing or unreadable: not a directory; the write that follows reports a failure.
+      return false;
+    }
+  }
+
+  isSameFile(left: URL, right: URL): boolean {
+    const leftPath = fileURLToPath(left);
+    const rightPath = fileURLToPath(right);
+    if (leftPath === rightPath) {
+      return true;
+    }
+    const leftStatus = statusOf(leftPath);
+    const rightStatus = statusOf(rightPath);
+    if (leftStatus && rightStatus && isSameFileNumber(leftStatus, rightStatus)) {
+      return true;
     }
+    return (
+      fileIdentityKey(leftPath, NODE_PATH_QUERIES) === fileIdentityKey(rightPath, NODE_PATH_QUERIES)
+    );
   }
 }
 
 /** File access for the CLI. */
-export function createNodeFileSystem(): FileReader & FileWriter {
+export function createNodeFileSystem(): FileReader &
+  FileWriter &
+  FileIdentity &
+  DirectoryCheck &
+  FileClaims {
   return new NodeFileSystem();
 }

package/src/adapters/redocly-loader/bundled-mapping-copies.ts

@@ -0,0 +1,95 @@
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
+import { findRefHolders } from "./ref-holders.js";
+
+/**
+ * Redocly 1.x bundles every discriminator `mapping` value as if it were an external `$ref`: it
+ * stores the target schema under the raw last segment of the pointer. For a local schema whose
+ * key needs an escape (`a~b`, written `a~0b`; `c/d`, written `c~1d`) that segment is no existing
+ * key, so the bundle added `a~0b` and `c~1d` to `components.schemas` as copies of `a~b` and
+ * `c/d`, and the generator wrote each type twice. A copy is the very object of the schema it
+ * copies, so a key the bundle added whose value is the value of a key the document had is removed,
+ * and the mapping values and `$ref`s that name it point at the original.
+ */
+
+type Schemas = Record<string, unknown>;
+
+const SCHEMAS_POINTER = childPointer(childPointer(ROOT_POINTER, "components"), "schemas");
+
+function isContainer(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function schemasOf(document: unknown): Schemas | undefined {
+  const components = isContainer(document) ? document.components : undefined;
+  const schemas = isContainer(components) ? components.schemas : undefined;
+  return isContainer(schemas) ? schemas : undefined;
+}
+
+/** The keys of `components.schemas` before bundling: the bundle edits the document in place. */
+export function schemaKeysOf(document: unknown): ReadonlySet<string> {
+  return new Set(Object.keys(schemasOf(document) ?? {}));
+}
+
+/** Each key the bundle added as a copy, with the pointer of the schema it copies. */
+function copiesIn(schemas: Schemas, keysBefore: ReadonlySet<string>): Map<string, string> {
+  const originals = new Map<unknown, string>();
+  for (const key of keysBefore) {
+    if (Object.hasOwn(schemas, key) && !originals.has(schemas[key])) {
+      originals.set(schemas[key], key);
+    }
+  }
+  const copies = new Map<string, string>();
+  for (const [key, value] of Object.entries(schemas)) {
+    const original = keysBefore.has(key) ? undefined : originals.get(value);
+    if (original !== undefined) {
+      copies.set(`${SCHEMAS_POINTER}/${key}`, childPointer(SCHEMAS_POINTER, original));
+      delete schemas[key];
+    }
+  }
+  return copies;
+}
+
+/** Every `discriminator.mapping` object of the document; the walk has its own stack. */
+function mappingsOf(document: unknown): Record<string, unknown>[] {
+  const mappings: Record<string, unknown>[] = [];
+  const visited = new WeakSet<object>();
+  const pending: unknown[] = [document];
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    if (!isContainer(next) || visited.has(next)) {
+      continue;
+    }
+    visited.add(next);
+    const mapping = isContainer(next.discriminator) ? next.discriminator.mapping : undefined;
+    if (isContainer(mapping)) {
+      mappings.push(mapping);
+    }
+    // One push per child: spreading an array of millions of children overflows the stack.
+    for (const child of Object.values(next)) {
+      pending.push(child);
+    }
+  }
+  return mappings;
+}
+
+/** Remove the bundle's copies of the document's own schemas, in place. */
+export function removeBundledMappingCopies(
+  bundled: unknown,
+  keysBefore: ReadonlySet<string>,
+): void {
+  const schemas = schemasOf(bundled);
+  const copies = schemas === undefined ? new Map<string, string>() : copiesIn(schemas, keysBefore);
+  if (copies.size === 0) {
+    return;
+  }
+  for (const mapping of mappingsOf(bundled)) {
+    for (const [name, value] of Object.entries(mapping)) {
+      const original = typeof value === "string" ? copies.get(value) : undefined;
+      if (original !== undefined) {
+        mapping[name] = original;
+      }
+    }
+  }
+  for (const { node } of findRefHolders(bundled)) {
+    node.$ref = copies.get(node.$ref) ?? node.$ref;
+  }
+}

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

@@ -1,4 +1,4 @@
-import { escapePointerSegment, parseRefPointer } from "../../domain/openapi/json-pointer.js";
+import { childPointer, parseRefPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
 import { findRefHolders } from "./ref-holders.js";
 
 /**
@@ -48,7 +48,7 @@ function repairedRef(document: unknown, ref: string): string | null {
   if (!resolves(document, raw)) {
     return null;
   }
-  return `${LOCAL_REF_PREFIX}${raw.map(escapePointerSegment).join("/")}`;
+  return raw.reduce((pointer, key) => childPointer(pointer, key), ROOT_POINTER);
 }
 
 /** Repair the local `$ref`s of a bundled document in place, as Redocly's bundle edits it. */

package/src/adapters/redocly-loader/loaded-documents.ts

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { BaseResolver, Document } from "@redocly/openapi-core";
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/** The documents one load read, from the Redocly resolver's cache. */
+
+/**
+ * The root document and every other document the resolver loaded, as far as they parsed. A root
+ * read from a file or URL is in the resolver cache too, and is listed once. A `$ref` that failed
+ * to load leaves a rejected entry in the cache, also when bundling did not need it (an example's
+ * `$ref`): that entry is no document, and must not fail the listing.
+ */
+export async function loadedDocuments(
+  root: Document,
+  resolver: BaseResolver,
+): Promise<LoadedDocument[]> {
+  const settled = await Promise.allSettled(resolver.cache.values());
+  const cached = settled.flatMap((entry) => (entry.status === "fulfilled" ? [entry.value] : []));
+  const bySource = new Map<string, unknown>([[root.source.absoluteRef, root.parsed]]);
+  for (const document of cached) {
+    if ("parsed" in document && !bySource.has(document.source.absoluteRef)) {
+      bySource.set(document.source.absoluteRef, document.parsed);
+    }
+  }
+  return [...bySource].map(([source, parsed]) => ({ source, parsed }));
+}
+
+/**
+ * The local files the load read: the root, when it is a file, and every `$ref`'d file. Redocly
+ * names a local document by its absolute path and a remote one by its URL. An inline root (a
+ * string, object, buffer or stream) has a made-up path in the working directory, so it is left
+ * out unless it was read from a file.
+ */
+export async function localFilesRead(
+  root: Document,
+  resolver: BaseResolver,
+  isRootAFile: boolean,
+): Promise<URL[]> {
+  const documents = await loadedDocuments(root, resolver);
+  return documents
+    .map(({ source }) => source)
+    .filter((source) => path.isAbsolute(source))
+    .filter((source) => isRootAFile || source !== root.source.absoluteRef)
+    .map((source) => pathToFileURL(source));
+}