@kubb/adapter-oas 5.0.0-beta.35 → 5.0.0-beta.37

package/dist/index.d.ts

@@ -466,9 +466,9 @@ type AdapterOasOptions = {
   serverVariables?: Record<string, string>;
   /**
    * How the `discriminator` field on `oneOf`/`anyOf` schemas is interpreted.
-   * - `'strict'` — child schemas stay exactly as written; the discriminator
+   * - `'strict'` child schemas stay exactly as written. The discriminator
    *   narrows types at the call site but child shapes are not modified.
-   * - `'inherit'` — Kubb propagates the discriminator property as a literal
+   * - `'inherit'` Kubb propagates the discriminator property as a literal
    *   value into each child schema, so each branch's discriminator field is
    *   precisely typed.
    *
@@ -479,9 +479,9 @@ type AdapterOasOptions = {
    * Collapse structurally identical schemas and enums into a single shared definition.
    *
    * Duplicated inline shapes (especially enums repeated across many properties) are hoisted
-   * into one named schema; every other occurrence — and any structurally identical top-level
-   * component — becomes a `ref` to it. Equality is shape-only: documentation such as
-   * `description` and `example` is ignored. Enabled by default; set to `false` to keep every
+   * into one named schema. Every other occurrence, and any structurally identical top-level
+   * component, becomes a `ref` to it. Equality is shape-only: documentation such as
+   * `description` and `example` is ignored. Enabled by default. Set to `false` to keep every
    * occurrence inline and produce byte-for-byte identical output to earlier versions.
    *
    * @default true

package/dist/index.js

@@ -1,6 +1,7 @@
 import "./chunk-C0LytTxp.js";
+import { access } from "node:fs/promises";
 import path from "node:path";
-import { ast, createAdapter } from "@kubb/core";
+import { DiagnosticError, Diagnostics, ast, createAdapter, diagnosticCode } from "@kubb/core";
 import BaseOas from "oas";
 import { bundle, loadConfig } from "@redocly/openapi-core";
 import OASNormalize from "oas-normalize";
@@ -71,6 +72,23 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/fs.ts
+/**
+* Resolves to `true` when the file or directory at `path` exists.
+* Uses `Bun.file().exists()` when running under Bun, `fs.access` otherwise.
+*
+* @example
+* ```ts
+* if (await exists('./kubb.config.ts')) {
+*   const content = await read('./kubb.config.ts')
+* }
+* ```
+*/
+async function exists(path) {
+	if (typeof Bun !== "undefined") return Bun.file(path).exists();
+	return access(path).then(() => true, () => false);
+}
+//#endregion
 //#region ../../internals/utils/src/object.ts
 /**
 * Returns `true` when `value` is a plain (non-null, non-array) object.
@@ -461,6 +479,18 @@ const structuralKeys = new Set([
 * formatMap['float']  // 'number'
 * ```
 */
+/**
+* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+* `int64` and the date/time family. Keep this in sync with the `convertFormat`
+* special-cases in `parser.ts`. `isHandledFormat` reads it so the
+* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+*/
+const specialCasedFormats = new Set([
+	"int64",
+	"date-time",
+	"date",
+	"time"
+]);
 const formatMap = {
 	uuid: "uuid",
 	email: "email",
@@ -608,7 +638,13 @@ async function mergeDocuments(pathOrApi) {
 		enablePaths: false,
 		canBundle: false
 	})));
-	if (documents.length === 0) throw new Error("No OAS documents provided for merging.");
+	if (documents.length === 0) throw new DiagnosticError({
+		code: diagnosticCode.inputRequired,
+		severity: "error",
+		message: "No OAS documents were provided for merging.",
+		help: "Pass at least one path or document to `input.path`.",
+		location: { kind: "config" }
+	});
 	const seed = {
 		openapi: MERGE_OPENAPI_VERSION,
 		info: {
@@ -624,9 +660,9 @@ async function mergeDocuments(pathOrApi) {
 * Creates a `Document` from an `AdapterSource`.
 *
 * Handles all three source types:
-* - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
-* - `{ type: 'paths' }` — merges multiple file paths into a single document.
-* - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+* - `{ type: 'path' }` resolves and bundles a local file path or remote URL.
+* - `{ type: 'paths' }` merges multiple file paths into a single document.
+* - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object.
 *
 * @example
 * ```ts
@@ -634,14 +670,31 @@ async function mergeDocuments(pathOrApi) {
 * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
 * ```
 */
-function parseFromConfig(source) {
+async function parseFromConfig(source) {
 	if (source.type === "data") {
 		if (typeof source.data === "object") return parseDocument(structuredClone(source.data));
 		return parseDocument(source.data, { canBundle: false });
 	}
 	if (source.type === "paths") return mergeDocuments(source.paths);
 	if (new URLPath(source.path).isURL) return parseDocument(source.path);
-	return parseDocument(path.resolve(path.dirname(source.path), source.path));
+	const resolved = path.resolve(path.dirname(source.path), source.path);
+	await assertInputExists(resolved);
+	return parseDocument(resolved);
+}
+/**
+* Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+* its parse error instead.
+*/
+async function assertInputExists(input) {
+	if (new URLPath(input).isURL) return;
+	if (!await exists(input)) throw new DiagnosticError({
+		code: diagnosticCode.inputNotFound,
+		severity: "error",
+		message: `Cannot read the file set in \`input.path\` (or via \`kubb generate PATH\`): ${input}`,
+		help: "Check that the path exists and is readable, then set it in `input.path` or pass it as `kubb generate PATH`.",
+		location: { kind: "config" }
+	});
 }
 /**
 * Validates an OpenAPI document using `oas-normalize` with colorized error output.
@@ -688,7 +741,21 @@ function resolveRef(document, $ref) {
 	}
 	if (docCache.has($ref)) return docCache.get($ref);
 	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
-	if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
+	if (!current) {
+		const diagnostic = {
+			code: diagnosticCode.refNotFound,
+			severity: "error",
+			message: `Could not find a definition for ${origRef}.`,
+			help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
+			location: {
+				kind: "schema",
+				pointer: origRef,
+				ref: origRef
+			}
+		};
+		Diagnostics.report(diagnostic);
+		return null;
+	}
 	docCache.set($ref, current);
 	return current;
 }
@@ -715,13 +782,13 @@ function dereferenceWithRef(document, schema) {
 //#endregion
 //#region src/dialect.ts
 /**
-* The OpenAPI / Swagger dialect — the default used by `@kubb/adapter-oas`.
+* The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
 *
 * Implements the spec-agnostic {@link ast.SchemaDialect} contract: it isolates the
 * decisions that differ between specs (nullability, `$ref`, discriminator, binary,
 * ref resolution) so the converter pipeline and dispatch rules stay shared. A
-* future adapter (e.g. AsyncAPI) ships its own dialect — `type: ['null', …]`
-* nullability, no discriminator object, binary via `contentEncoding` — and reuses
+* future adapter (e.g. AsyncAPI) ships its own dialect, `type: ['null', …]`
+* nullability, no discriminator object, binary via `contentEncoding` and reuses
 * the rest unchanged.
 *
 * Formats (`uuid`, `email`, dates, …) are intentionally NOT here: they are shared
@@ -763,7 +830,16 @@ function resolveServerUrl(server, overrides) {
 	for (const [key, variable] of Object.entries(server.variables)) {
 		const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : void 0);
 		if (value === void 0) continue;
-		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new Error(`Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`);
+		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new DiagnosticError({
+			code: diagnosticCode.invalidServerVariable,
+			severity: "error",
+			message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`,
+			help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
+			location: {
+				kind: "document",
+				pointer: "#/servers"
+			}
+		});
 		url = url.replaceAll(`{${key}}`, value);
 	}
 	return url;
@@ -776,6 +852,15 @@ function getSchemaType(format) {
 	return formatMap[format] ?? null;
 }
 /**
+* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
+* `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
+* base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+* diagnostic in step with the parser as `formatMap` grows.
+*/
+function isHandledFormat(format) {
+	return getSchemaType(format) !== null || specialCasedFormats.has(format);
+}
+/**
 * Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
 * Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
 */
@@ -872,7 +957,7 @@ function getRequestSchema(document, operation, options = {}) {
 /**
 * Flattens a keyword-only `allOf` into its parent schema.
 *
-* Only flattens when every member is a plain fragment — no `$ref` and no structural keywords
+* Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
 * (see `structuralKeys`). Outer schema values take precedence over fragment values.
 * Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
 *
@@ -882,7 +967,7 @@ function getRequestSchema(document, operation, options = {}) {
 * // { type: 'object', properties: {}, description: 'A pet' }
 *
 * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
-* // returned unchanged — contains a $ref
+* // returned unchanged, contains a $ref
 * ```
 */
 /**
@@ -908,7 +993,7 @@ function flattenSchema(schema) {
 /**
 * Extracts the inline schema from a media-type `content` map.
 *
-* Prefers `preferredContentType` when given; otherwise uses the first key in the map.
+* Prefers `preferredContentType` when given, otherwise uses the first key in the map.
 * Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
 *
 * @example
@@ -1100,9 +1185,9 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 /**
 * Returns all request body content type keys for an operation.
 *
-* The requestBody is dereferenced **in-place** when it is a `$ref` — the same mutation
-* that `getRequestSchema` already performs — so that the returned list accurately reflects
-* the available content types even for referenced bodies.
+* The requestBody is dereferenced in place when it is a `$ref` (the same mutation that
+* `getRequestSchema` already performs), so the returned list accurately reflects the
+* available content types even for referenced bodies.
 *
 * @example
 * ```ts
@@ -1119,7 +1204,7 @@ function getRequestBodyContentTypes(document, operation) {
 /**
 * Returns all response content type keys for an operation at a given status code.
 *
-* Response `$ref`s are resolved in-place first — the same mutation `getResponseSchema` performs —
+* Response `$ref`s are resolved in place first (the same mutation `getResponseSchema` performs),
 * so the returned list reflects the available content types even for referenced responses.
 *
 * @example
@@ -1179,16 +1264,12 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	*/
 	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
-	* Cache of already-resolved `$ref` schemas within this parser instance.
-	*
-	* Without this, the same referenced schema (e.g. `customer`) is fully re-expanded
-	* every time it appears as a `$ref` in a different parent schema. In heavily
-	* cross-referenced specs like Stripe (~1 400 schemas), this causes exponential
-	* blowup — `customer` alone may be referenced from dozens of top-level schemas,
-	* each triggering a fresh recursive expansion of its entire sub-tree.
+	* Cache of `$ref` schemas already resolved in this parser instance, keyed by ref path.
 	*
-	* Memoizing by `$ref` path reduces the overall work from O(2^depth) to O(N)
-	* where N is the number of unique schema names.
+	* Without it, a shared schema (e.g. `customer`) is re-expanded for every `$ref` that points at
+	* it. In cross-referenced specs like Stripe (~1400 schemas) that becomes exponential blowup,
+	* since one schema can be referenced from dozens of parents, each re-walking its whole subtree.
+	* Memoizing by ref path drops the work from O(2^depth) to O(N) unique schema names.
 	*/
 	const resolvedRefCache = /* @__PURE__ */ new Map();
 	/**
@@ -1726,7 +1807,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	/**
 	* Ordered schema-dispatch table. Order is significant: composition keywords (`$ref`, `allOf`,
 	* `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
-	* `type`. The first matching rule that produces a node wins; see {@link SchemaRule} for the
+	* `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
 	* match/convert/fall-through contract.
 	*/
 	const schemaRules = [
@@ -2071,6 +2152,50 @@ function patchDiscriminatorNode(node, entry) {
 	};
 }
 //#endregion
+//#region src/schemaDiagnostics.ts
+/**
+* Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one
+* top-level schema. Walks the node the parser produced during `preScan`, threading the RFC 6901
+* pointer as it descends so a nested field reports against its full path
+* (`#/components/schemas/Pet/properties/owner/properties/name`). Refs are not followed, so the
+* resolved schema is reported under its own walk. Reports land in the active build run, are a
+* no-op outside one, and repeats are deduped by the build.
+*/
+function reportSchemaDiagnostics({ node, name }) {
+	visit(node, `#/components/schemas/${name}`);
+}
+function visit(node, pointer) {
+	if (node.deprecated) Diagnostics.report({
+		code: diagnosticCode.deprecated,
+		severity: "info",
+		message: "This schema is marked as deprecated.",
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (typeof node.format === "string" && !isHandledFormat(node.format)) Diagnostics.report({
+		code: diagnosticCode.unsupportedFormat,
+		severity: "warning",
+		message: `Kubb does not map the format "${node.format}" to a specific type, so it falls back to the base type.`,
+		help: `Use a format Kubb supports, or handle "${node.format}" with a custom parser or plugin.`,
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (node.type === "object") {
+		for (const property of node.properties) visit(property.schema, `${pointer}/properties/${property.name}`);
+		if (node.additionalProperties && typeof node.additionalProperties === "object") visit(node.additionalProperties, `${pointer}/additionalProperties`);
+		return;
+	}
+	if (node.type === "array" || node.type === "tuple") {
+		for (const item of node.items ?? []) visit(item, `${pointer}/items`);
+		return;
+	}
+	if (node.type === "union" || node.type === "intersection") for (const member of node.members ?? []) visit(member, pointer);
+}
+//#endregion
 //#region src/stream.ts
 /**
 * Builds the deduplication plan from the already-parsed top-level schema nodes plus a
@@ -2130,7 +2255,7 @@ function resolveBaseUrl({ document, serverIndex, serverVariables }) {
 * After this call, only `refAliasMap` and `discriminatorChildMap` stay alive in the adapter closure.
 * Both are proportional to the number of aliases or discriminator parents, not total schema count.
 *
-* Each schema is parsed again during the streaming pass — this is intentional.
+* Each schema is parsed again during the streaming pass. This is intentional.
 * Holding the parsed nodes in memory here would defeat the streaming memory benefit.
 *
 * @example
@@ -2154,6 +2279,10 @@ function preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions,
 			name
 		}, parserOptions);
 		allNodes.push(node);
+		reportSchemaDiagnostics({
+			node,
+			name
+		});
 		if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
 		if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) enumNames.push(node.name);
 		if (discriminator === "inherit" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
@@ -2370,6 +2499,7 @@ const adapterOas = createAdapter((options) => {
 			return parsedDocument;
 		},
 		async validate(input, options) {
+			await assertInputExists(input);
 			await validateDocument(await parseDocument(input), options);
 		},
 		getImports(node, resolve) {