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

package/dist/index.mjs

@@ -9,6 +9,7 @@ export { default as transformSchema } from './api/transform-schema.mjs';
 export { BOOLEAN, FALSE, NEVER, NULL, NUMBER, STRING, TRUE, UNDEFINED, UNKNOWN, oapiRef, tsIntersection, tsLiteral, tsNullable, tsOmit, tsRecord, tsUnion, tsWithRequired } from './api/type-helpers.mjs';
 export { ERROR_CODES, OpenAPITypesafeError, isOpenAPITypesafeError } from './domain/errors.mjs';
 export { ALL_OUTPUT_FIXES, OUTPUT_FIXES, OutputFix } from './domain/output-fixes.mjs';
+export { WARNING_CODES } from './domain/warnings.mjs';
 export { default as transformComponentsObject } from './transform/components-object.mjs';
 export { default as transformHeaderObject } from './transform/header-object.mjs';
 export { default as transformMediaTypeObject } from './transform/media-type-object.mjs';

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/transform/components-object.cjs

@@ -4,10 +4,11 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 const transformContext = require('../api/transform-context.cjs');
 const components = require('../application/transform/document/components.cjs');
+const rootTypeAliases = require('../application/transform/document/root-type-aliases.cjs');
 
 function transformComponentsObject(componentsObject, ctx) {
   const { type, rootTypes } = components.componentsType(componentsObject, transformContext.createTransformContext(ctx));
-  return [type, ...rootTypes];
+  return [type, ...rootTypeAliases.renameTakenAliases(rootTypes, [])];
 }
 
 exports.default = transformComponentsObject;

package/dist/transform/components-object.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"components-object.cjs","sources":["../../src/transform/components-object.ts"],"sourcesContent":["import { createTransformContext } from \"../api/transform-context.js\";\nimport { componentsType } from \"../application/transform/document/components.js\";\nimport type { IrType, IrTypeAliasDeclaration } from \"../domain/ir/nodes.js\";\nimport { isEnumSchema, singularizeComponentKind } from \"../domain/openapi/components-object.js\";\nimport type { ComponentsObject, GlobalContext } from \"../types.js\";\n\nexport { isEnumSchema };\n\n/** `requestBodies` → `requestBody`; other keys drop the final `s`. */\nexport const singularizeComponentKey = singularizeComponentKind;\n\n/**\n * Transform the ComponentsObject (4.8.7)\n * @see https://spec.openapis.org/oas/latest.html#components-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 6). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API: the `components` type, then the root type aliases.\n */\nexport default function transformComponentsObject(\n  componentsObject: ComponentsObject,\n  ctx: GlobalContext,\n): (IrType | IrTypeAliasDeclaration)[] {\n  const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));\n  return [type, ...rootTypes];\n}\n"],"names":["componentsType","createTransformContext"],"mappings":";;;;;;;AAkBA,SAAwB,yBAAA,CACtB,kBACA,GAAA,EACqC;AACrC,EAAA,MAAM,EAAE,MAAM,SAAA,EAAU,GAAIA,0BAAe,gBAAA,EAAkBC,uCAAA,CAAuB,GAAG,CAAC,CAAA;AACxF,EAAA,OAAO,CAAC,IAAA,EAAM,GAAG,SAAS,CAAA;AAC5B;;"}
+{"version":3,"file":"components-object.cjs","sources":["../../src/transform/components-object.ts"],"sourcesContent":["import { createTransformContext } from \"../api/transform-context.js\";\nimport { componentsType } from \"../application/transform/document/components.js\";\nimport { renameTakenAliases } from \"../application/transform/document/root-type-aliases.js\";\nimport type { IrType, IrTypeAliasDeclaration } from \"../domain/ir/nodes.js\";\nimport { isEnumSchema, singularizeComponentKind } from \"../domain/openapi/components-object.js\";\nimport type { ComponentsObject, GlobalContext } from \"../types.js\";\n\nexport { isEnumSchema };\n\n/** `requestBodies` → `requestBody`; other keys drop the final `s`. */\nexport const singularizeComponentKey = singularizeComponentKind;\n\n/**\n * Transform the ComponentsObject (4.8.7)\n * @see https://spec.openapis.org/oas/latest.html#components-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 6). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API: the `components` type, then the root type aliases.\n */\nexport default function transformComponentsObject(\n  componentsObject: ComponentsObject,\n  ctx: GlobalContext,\n): (IrType | IrTypeAliasDeclaration)[] {\n  const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));\n  // No footer here: only the aliases the `root-type-numbering` fix keeps get numbers.\n  return [type, ...renameTakenAliases(rootTypes, [])];\n}\n"],"names":["componentsType","createTransformContext","renameTakenAliases"],"mappings":";;;;;;;;AAmBA,SAAwB,yBAAA,CACtB,kBACA,GAAA,EACqC;AACrC,EAAA,MAAM,EAAE,MAAM,SAAA,EAAU,GAAIA,0BAAe,gBAAA,EAAkBC,uCAAA,CAAuB,GAAG,CAAC,CAAA;AAExF,EAAA,OAAO,CAAC,IAAA,EAAM,GAAGC,mCAAmB,SAAA,EAAW,EAAE,CAAC,CAAA;AACpD;;"}

package/dist/transform/components-object.mjs

@@ -1,9 +1,10 @@
 import { createTransformContext } from '../api/transform-context.mjs';
 import { componentsType } from '../application/transform/document/components.mjs';
+import { renameTakenAliases } from '../application/transform/document/root-type-aliases.mjs';
 
 function transformComponentsObject(componentsObject, ctx) {
   const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));
-  return [type, ...rootTypes];
+  return [type, ...renameTakenAliases(rootTypes, [])];
 }
 
 export { transformComponentsObject as default };

package/dist/transform/components-object.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"components-object.mjs","sources":["../../src/transform/components-object.ts"],"sourcesContent":["import { createTransformContext } from \"../api/transform-context.js\";\nimport { componentsType } from \"../application/transform/document/components.js\";\nimport type { IrType, IrTypeAliasDeclaration } from \"../domain/ir/nodes.js\";\nimport { isEnumSchema, singularizeComponentKind } from \"../domain/openapi/components-object.js\";\nimport type { ComponentsObject, GlobalContext } from \"../types.js\";\n\nexport { isEnumSchema };\n\n/** `requestBodies` → `requestBody`; other keys drop the final `s`. */\nexport const singularizeComponentKey = singularizeComponentKind;\n\n/**\n * Transform the ComponentsObject (4.8.7)\n * @see https://spec.openapis.org/oas/latest.html#components-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 6). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API: the `components` type, then the root type aliases.\n */\nexport default function transformComponentsObject(\n  componentsObject: ComponentsObject,\n  ctx: GlobalContext,\n): (IrType | IrTypeAliasDeclaration)[] {\n  const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));\n  return [type, ...rootTypes];\n}\n"],"names":[],"mappings":";;;AAkBA,SAAwB,yBAAA,CACtB,kBACA,GAAA,EACqC;AACrC,EAAA,MAAM,EAAE,MAAM,SAAA,EAAU,GAAI,eAAe,gBAAA,EAAkB,sBAAA,CAAuB,GAAG,CAAC,CAAA;AACxF,EAAA,OAAO,CAAC,IAAA,EAAM,GAAG,SAAS,CAAA;AAC5B;;"}
+{"version":3,"file":"components-object.mjs","sources":["../../src/transform/components-object.ts"],"sourcesContent":["import { createTransformContext } from \"../api/transform-context.js\";\nimport { componentsType } from \"../application/transform/document/components.js\";\nimport { renameTakenAliases } from \"../application/transform/document/root-type-aliases.js\";\nimport type { IrType, IrTypeAliasDeclaration } from \"../domain/ir/nodes.js\";\nimport { isEnumSchema, singularizeComponentKind } from \"../domain/openapi/components-object.js\";\nimport type { ComponentsObject, GlobalContext } from \"../types.js\";\n\nexport { isEnumSchema };\n\n/** `requestBodies` → `requestBody`; other keys drop the final `s`. */\nexport const singularizeComponentKey = singularizeComponentKind;\n\n/**\n * Transform the ComponentsObject (4.8.7)\n * @see https://spec.openapis.org/oas/latest.html#components-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 6). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API: the `components` type, then the root type aliases.\n */\nexport default function transformComponentsObject(\n  componentsObject: ComponentsObject,\n  ctx: GlobalContext,\n): (IrType | IrTypeAliasDeclaration)[] {\n  const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));\n  // No footer here: only the aliases the `root-type-numbering` fix keeps get numbers.\n  return [type, ...renameTakenAliases(rootTypes, [])];\n}\n"],"names":[],"mappings":";;;;AAmBA,SAAwB,yBAAA,CACtB,kBACA,GAAA,EACqC;AACrC,EAAA,MAAM,EAAE,MAAM,SAAA,EAAU,GAAI,eAAe,gBAAA,EAAkB,sBAAA,CAAuB,GAAG,CAAC,CAAA;AAExF,EAAA,OAAO,CAAC,IAAA,EAAM,GAAG,mBAAmB,SAAA,EAAW,EAAE,CAAC,CAAA;AACpD;;"}

package/dist/transform/path-item-object.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"path-item-object.cjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { HttpMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\nexport type Method = HttpMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":["pathItem","createTransformContext","pathItemType","schemaLocation"],"mappings":";;;;;AAeA,SAAwB,uBAAA,CACtBA,YACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAUC,uCAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAOC,qBAAA,CAAaF,UAAA,EAAUG,+BAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}
+{"version":3,"file":"path-item-object.cjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { PathItemMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\n/**\n * The operation methods of a path item: openapi-typescript's eight, plus the OpenAPI 3.2 `query`\n * (ADR-020), as `HttpMethod` of openapi-typesafe-helpers lists them.\n */\nexport type Method = PathItemMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":["pathItem","createTransformContext","pathItemType","schemaLocation"],"mappings":";;;;;AAmBA,SAAwB,uBAAA,CACtBA,YACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAUC,uCAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAOC,qBAAA,CAAaF,UAAA,EAAUG,+BAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}

package/dist/transform/path-item-object.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"path-item-object.mjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { HttpMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\nexport type Method = HttpMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":[],"mappings":";;;AAeA,SAAwB,uBAAA,CACtB,UACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAU,sBAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAO,YAAA,CAAa,QAAA,EAAU,cAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}
+{"version":3,"file":"path-item-object.mjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { PathItemMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\n/**\n * The operation methods of a path item: openapi-typescript's eight, plus the OpenAPI 3.2 `query`\n * (ADR-020), as `HttpMethod` of openapi-typesafe-helpers lists them.\n */\nexport type Method = PathItemMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":[],"mappings":";;;AAmBA,SAAwB,uBAAA,CACtB,UACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAU,sBAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAO,YAAA,CAAa,QAAA,EAAU,cAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-typesafe",
-  "description": "Convert OpenAPI 3.0 & 3.1 schemas to TypeScript",
-  "version": "1.0.0-rc.0",
+  "description": "Convert OpenAPI 3.0, 3.1 & 3.2 schemas to TypeScript",
+  "version": "1.0.0-rc.2",
   "author": {
     "name": "Fedor Chishchin",
     "url": "https://github.com/fedorello"
@@ -72,7 +72,7 @@
     }
   },
   "dependencies": {
-    "@redocly/openapi-core": "^1.34.22",
+    "@redocly/openapi-core": "^1.34.23",
     "ansi-colors": "^4.1.3",
     "change-case": "^5.4.4",
     "parse-json": "^8.3.0",
@@ -81,15 +81,16 @@
     "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",
+    "dependency-cruiser": "18.7.2",
     "execa": "^10.2.1",
     "fast-check": "4.10.2",
     "strip-ansi": "7.2.0",
     "typescript": "^6.0.3",
+    "typescript-5.4": "npm:typescript@5.4.5",
+    "typescript-7.0": "npm:typescript@7.0.2",
     "vite-node": "6.0.0"
   },
   "engines": {

package/src/adapters/redocly-loader/configured-headers.ts

@@ -0,0 +1,65 @@
+import { type Config as RedoclyConfig, readFileFromUrl } from "@redocly/openapi-core";
+
+/**
+ * Which `resolve.http.headers` of the Redocly config go with a request (threat model T4a). The
+ * headers often carry credentials, so they are chosen again for every request and every redirect,
+ * from the parsed URL, and never sent over plain HTTP to another machine unless the pattern asks
+ * for it.
+ */
+
+/** One `resolve.http.headers` entry: a name, a value or an environment variable, a pattern. */
+export type ConfiguredHeader = RedoclyConfig["resolve"]["http"]["headers"][number];
+
+/** Redocly matches the protocol only when the pattern starts with one; the same test. */
+const EXPLICIT_HTTP_PATTERN = /^http:\/\//;
+
+/** Hosts that never leave the machine: plain HTTP to them cannot be read on the network. */
+const LOOPBACK_HOSTNAMES: ReadonlySet<string> = new Set(["localhost", "[::1]"]);
+// The URL parser has already turned every IPv4 form (`2130706433`, `0x7f.1`) into dotted decimal.
+const LOOPBACK_IPV4 = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+function isLoopback(url: URL): boolean {
+  return LOOPBACK_HOSTNAMES.has(url.hostname) || LOOPBACK_IPV4.test(url.hostname);
+}
+
+/**
+ * A header goes over HTTPS, over HTTP to this machine (a local dev server), or over HTTP to
+ * another machine when its pattern names `http://` itself.
+ */
+function isProtocolAllowed(header: ConfiguredHeader, url: URL): boolean {
+  return (
+    url.protocol === "https:" ||
+    (url.protocol === "http:" && isLoopback(url)) ||
+    EXPLICIT_HTTP_PATTERN.test(header.matches)
+  );
+}
+
+/**
+ * The URL as a pattern sees it: protocol, host and path. User info, query and fragment are left
+ * out, so a `*` in the pattern cannot match across `?`, `#` or `@` into another host's URL.
+ */
+function matchedText(url: URL): string {
+  return `${url.protocol}//${url.host}${url.pathname}`;
+}
+
+/**
+ * The headers configured for this URL. The patterns are matched by Redocly's own matcher, which
+ * also reads `envVariable` values, so a pattern means here what it means in Redocly; its fetch
+ * only records the headers it would send and sends nothing.
+ */
+export async function headersFor(
+  url: URL,
+  configured: readonly ConfiguredHeader[],
+): Promise<Record<string, string>> {
+  const candidates = configured.filter((header) => isProtocolAllowed(header, url));
+  let selected: Record<string, string> = {};
+  if (candidates.length === 0) {
+    return selected;
+  }
+  const recordHeaders = async (_input: string, init: { headers: Record<string, string> }) => {
+    selected = init.headers;
+    return new Response("");
+  };
+  await readFileFromUrl(matchedText(url), { headers: [...candidates], customFetch: recordHeaders });
+  return selected;
+}

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

@@ -1,10 +1,43 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createConfig, findConfig, loadConfig } from "@redocly/openapi-core";
+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 {
@@ -26,14 +59,16 @@ class RedoclyConfigFiles implements RedoclyConfigSource {
   }
 
   load(configPath: string): Promise<RedoclyConfig> {
-    return loadConfig({ configPath });
+    return loadedConfig(() => loadConfig({ configPath }), configPath);
   }
 
   createDefault(): Promise<RedoclyConfig> {
-    return createConfig(
-      { rules: { "operation-operationId-unique": { severity: "warn" } } },
-      { extends: ["minimal"] },
-    );
+    const create = () =>
+      createConfig(
+        { rules: { "operation-operationId-unique": { severity: "warn" } } },
+        { extends: ["minimal"] },
+      );
+    return loadedConfig(create, undefined);
   }
 }
 

package/src/adapters/redocly-loader/redocly-schema-loader.ts

@@ -10,11 +10,14 @@ import {
 import type { Logger } from "../../application/ports/logger.js";
 import type { SchemaLoader, SchemaLoadRequest } from "../../application/ports/schema-loader.js";
 import { withStackOverflowReportedAsync } from "../../application/stack-overflow.js";
+import { WARNING_CODES, warningText } from "../../domain/warnings.js";
 import type { OpenAPI3 } from "../../types.js";
 import { repairBundledRefs } from "./bundled-ref-repair.js";
 import { findMalformedRefs, malformedRefsError } from "./malformed-refs.js";
 import { RefAccessResolver } from "./ref-access.js";
-import { resolveConfigWithAccess } from "./remote-fetch.js";
+import { checkRefsResolve } from "./ref-resolution-check.js";
+import { REF_CYCLE_MESSAGE } from "./ref-resolution-steps.js";
+import { type RemoteDocumentLimits, resolveConfigWithAccess } from "./remote-fetch.js";
 import {
   loadFailedError,
   refCycleError,
@@ -39,6 +42,7 @@ export interface RedoclySchemaLoaderOptions {
   readonly now: () => number;
   /** Time limit of one remote fetch, unless the Redocly config brings its own `customFetch`. */
   readonly remoteRefTimeoutMs: number;
+  readonly remoteDocumentLimits: RemoteDocumentLimits;
 }
 
 const UNSUPPORTED_FORMAT_MESSAGE = "Unsupported schema format, expected `openapi: 3.x`";
@@ -74,12 +78,17 @@ function assertOpenAPI3(document: unknown): void {
   throw versionUnsupportedError(UNSUPPORTED_FORMAT_MESSAGE, parsed);
 }
 
-/** The base for relative `$ref`s: the source file or URL itself, else the working directory. */
+/**
+ * The name an inline source (a string, object, buffer or stream) gets inside the working
+ * directory. Redocly resolves relative `$ref`s against the directory of the document, so the
+ * document must be named as a file in the working directory, not as the directory itself.
+ */
+const INLINE_SOURCE_NAME = "inline-source";
+
+/** The base for relative `$ref`s: the source file or URL itself, else a file in the cwd. */
 function sourceAbsoluteRef(source: unknown, cwd: URL): string {
-  if (source instanceof URL) {
-    return source.protocol === "file:" ? sourceFilePath(source) : source.href;
-  }
-  return fileURLToPath(cwd);
+  const document = source instanceof URL ? source : new URL(INLINE_SOURCE_NAME, cwd);
+  return document.protocol === "file:" ? sourceFilePath(document) : document.href;
 }
 
 /**
@@ -98,9 +107,6 @@ function sourceFilePath(source: URL): string {
   }
 }
 
-/** Redocly throws a plain Error for a `$ref` chain that points back to itself. */
-const REF_CYCLE_MESSAGE = "Self-referencing circular pointer";
-
 /**
  * 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.
@@ -171,12 +177,16 @@ class RedoclySchemaLoader implements SchemaLoader {
   }
 
   #resolver(request: SchemaLoadRequest): RefAccessResolver {
-    const { redoc, remoteRefTimeoutMs } = this.#options;
+    const { redoc, remoteRefTimeoutMs, remoteDocumentLimits } = this.#options;
     const config = resolveConfigWithAccess(redoc.resolve, {
       timeoutMs: remoteRefTimeoutMs,
       access: request.refAccess,
+      maxParallelFetches: remoteDocumentLimits.maxParallelFetches,
+    });
+    return new RefAccessResolver(config, {
+      access: request.refAccess,
+      maxRemoteDocuments: remoteDocumentLimits.maxDocuments,
     });
-    return new RefAccessResolver(config, request.refAccess);
   }
 
   async #lintAndBundle(
@@ -185,6 +195,8 @@ class RedoclySchemaLoader implements SchemaLoader {
     shouldLint: boolean,
   ): Promise<OpenAPI3> {
     const rethrow = (error: unknown) => rethrowDocumentError(error, document, resolver);
+    // Redocly leaves unhandled rejections behind when a `$ref` fails in two documents (ADR-031).
+    await checkRefsResolve(document, resolver, this.#options.redoc.styleguide).catch(rethrow);
     if (shouldLint) {
       await this.#lint(document, resolver).catch(rethrow);
     }
@@ -217,16 +229,27 @@ class RedoclySchemaLoader implements SchemaLoader {
     return bundled.bundle.parsed;
   }
 
-  /** Report every problem; then throw if any of them is an error. */
+  /**
+   * Report every problem; then throw if any of them is an error. A problem that the Redocly
+   * config's `.redocly.lint-ignore.yaml` lists is left out, as `redocly lint` leaves it out
+   * (upstream #2189).
+   */
   #report(problems: readonly NormalizedProblem[]): void {
     const errorMessages: string[] = [];
     for (const problem of problems) {
+      if (problem.ignored === true) {
+        this.#options.logger.debug(
+          `Ignored by the lint ignore file: ${problemMessage(problem)}`,
+          "lint",
+        );
+        continue;
+      }
       const message = problemMessage(problem);
       if (problem.severity === "error") {
         errorMessages.push(message);
         this.#options.logger.error(message);
       } else {
-        this.#options.logger.warn(message);
+        this.#options.logger.warn(lintWarningText(problem));
       }
     }
     if (errorMessages.length > 0) {
@@ -235,6 +258,14 @@ class RedoclySchemaLoader implements SchemaLoader {
   }
 }
 
+/** A lint warning names its rule, which `redocly.yaml` can turn off, and ends with its code. */
+function lintWarningText(problem: NormalizedProblem): string {
+  return warningText(
+    `${problemMessage(problem)}, rule ${problem.ruleId}`,
+    WARNING_CODES.LINT_PROBLEM,
+  );
+}
+
 function problemMessage(problem: NormalizedProblem): string {
   const location = problem.location?.[0]?.pointer;
   return location ? `${problem.message} at ${location}` : problem.message;

package/src/adapters/redocly-loader/ref-access.ts

@@ -10,6 +10,7 @@ import {
 } from "@redocly/openapi-core";
 import type { RefAccess } from "../../application/ports/schema-loader.js";
 import { ERROR_CODES, type OpenAPITypesafeError } from "../../domain/errors.js";
+import { redactUrlCredentials } from "../../domain/url-credentials.js";
 import { aliasExpansionFailure } from "./alias-limit.js";
 import { isHostAllowed } from "./allowed-hosts.js";
 import { refForbiddenError } from "./schema-load-errors.js";
@@ -79,20 +80,45 @@ export async function refusalOf(
   });
 }
 
+/**
+ * A remote document may refer only to other URLs (threat model T3). Redocly resolves a `$ref`
+ * against a URL base with `new URL()`, so `C:/x` becomes `c:/x` and `file:///x` stays as it is;
+ * Redocly then reads either from disk, and on Windows a drive letter is an absolute path.
+ */
+function localFromRemoteRefusal(
+  base: string,
+  absoluteRef: string,
+): OpenAPITypesafeError | undefined {
+  if (!isRemoteRef(base) || isRemoteRef(absoluteRef)) {
+    return undefined;
+  }
+  const shownBase = redactUrlCredentials(base);
+  return refForbiddenError(absoluteRef, { reason: "local-ref-from-remote", base: shownBase });
+}
+
+/** The limits one resolver checks; each load gets its own resolver. */
+export interface RefAccessLimits {
+  readonly access: RefAccess;
+  /** Remote documents one load may fetch, the root included (threat model T2). */
+  readonly maxRemoteDocuments: number;
+}
+
 /**
  * A Redocly resolver that checks each document before it loads it. Redocly turns a failed load
  * into an unresolved-`$ref` problem, so the refusals are also kept for the loader to report as
  * the typed error.
  */
 export class RefAccessResolver extends BaseResolver {
-  readonly #access: RefAccess;
+  readonly #limits: RefAccessLimits;
   readonly #refusals: OpenAPITypesafeError[] = [];
   /** The root document's ref: it is chosen by the developer, so it is not limited. */
   #rootRef: string | undefined;
+  /** Remote documents asked for so far; Redocly caches each one, so each is counted once. */
+  #remoteDocumentCount = 0;
 
-  constructor(config: ResolveConfig, access: RefAccess) {
+  constructor(config: ResolveConfig, limits: RefAccessLimits) {
     super(config);
-    this.#access = access;
+    this.#limits = limits;
   }
 
   /** The first document that was refused, if any. */
@@ -108,6 +134,12 @@ export class RefAccessResolver extends BaseResolver {
     if (isRoot) {
       this.#rootRef = this.resolveExternalRef(base, ref);
     }
+    const refusal =
+      base === null ? undefined : localFromRemoteRefusal(base, this.resolveExternalRef(base, ref));
+    if (refusal !== undefined) {
+      this.#refusals.push(refusal);
+      return Promise.reject(refusal);
+    }
     return super.resolveDocument(base, ref, isRoot);
   }
 
@@ -122,8 +154,7 @@ export class RefAccessResolver extends BaseResolver {
   }
 
   override async loadExternalRef(absoluteRef: string): Promise<Source> {
-    const refusal =
-      absoluteRef === this.#rootRef ? undefined : await refusalOf(absoluteRef, this.#access);
+    const refusal = this.#countRefusal(absoluteRef) ?? (await this.#accessRefusal(absoluteRef));
     if (refusal !== undefined) {
       this.#refusals.push(refusal);
       throw refusal;
@@ -139,6 +170,30 @@ export class RefAccessResolver extends BaseResolver {
       throw error;
     }
   }
+
+  #accessRefusal(absoluteRef: string): Promise<OpenAPITypesafeError | undefined> {
+    return absoluteRef === this.#rootRef
+      ? Promise.resolve(undefined)
+      : refusalOf(absoluteRef, this.#limits.access);
+  }
+
+  /**
+   * A document that changes all its URLs can fan out without end: 150 `$ref`s per document, three
+   * levels deep, made 16,212 requests and exhausted the local ports (audit B2, F4).
+   */
+  #countRefusal(absoluteRef: string): OpenAPITypesafeError | undefined {
+    if (!isRemoteRef(absoluteRef)) {
+      return undefined;
+    }
+    this.#remoteDocumentCount += 1;
+    const { maxRemoteDocuments } = this.#limits;
+    return this.#remoteDocumentCount > maxRemoteDocuments
+      ? refForbiddenError(absoluteRef, {
+          reason: "too-many-remote-documents",
+          maxDocuments: maxRemoteDocuments,
+        })
+      : undefined;
+  }
 }
 
 function isRefusal(value: unknown): value is OpenAPITypesafeError {