genoc 0.4.3 → 0.5.0

package/dist/parser/version/v3.0/validator.d.ts

@@ -9,5 +9,7 @@ import type { ValidationResult } from '../validate.js';
  * - Warns about 3.1-only features: `webhooks`, `$schema` in schemas, `type` as array
  * - Accepts `nullable` and `example` (valid in 3.0, not in 3.1)
  * - Errors on `items` as array (3.1-only tuple syntax)
+ * - Validates `components.securitySchemes` and `security` requirements (shared rules;
+ *   non-oauth2/openIdConnect scopes must be empty, `mutualTLS` rejected as 3.1-only)
  */
 export declare function validateSpec30(spec: unknown): ValidationResult;

package/dist/parser/version/v3.0/validator.js

@@ -1,3 +1,10 @@
+import { specViolation } from '../spec-links.js';
+import { validateSecurity } from '../validate-security.js';
+/**
+ * Every violation in this file belongs to the 3.0 dialect;
+ * bind it once so call sites stay key-and-message only.
+ */
+const violation = (key, message) => specViolation('3.0', key, message);
 /**
  * Validate a raw OpenAPI 3.0.x specification.
  *
@@ -8,39 +15,41 @@
  * - Warns about 3.1-only features: `webhooks`, `$schema` in schemas, `type` as array
  * - Accepts `nullable` and `example` (valid in 3.0, not in 3.1)
  * - Errors on `items` as array (3.1-only tuple syntax)
+ * - Validates `components.securitySchemes` and `security` requirements (shared rules;
+ *   non-oauth2/openIdConnect scopes must be empty, `mutualTLS` rejected as 3.1-only)
  */
 export function validateSpec30(spec) {
     const errors = [];
     if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
-        errors.push('Document must be an object');
+        errors.push(violation('document-root', 'Document must be an object'));
         return { valid: false, errors };
     }
     const s = spec;
     if (!s.openapi || typeof s.openapi !== 'string') {
-        errors.push("OpenAPI specification must have an 'openapi' field with string value");
+        errors.push(violation('openapi-field', "OpenAPI specification must have an 'openapi' field with string value"));
     }
     else if (!s.openapi.startsWith('3.0')) {
-        errors.push(`OpenAPI version must start with '3.0', got: ${s.openapi}`);
+        errors.push(violation('openapi-field', `OpenAPI version must start with '3.0', got: ${s.openapi}`));
     }
     if (!s.info || typeof s.info !== 'object' || Array.isArray(s.info)) {
-        errors.push("OpenAPI specification must have an 'info' field with object value");
+        errors.push(violation('info-object', "OpenAPI specification must have an 'info' field with object value"));
     }
     else {
         const info = s.info;
         if (!info.title || typeof info.title !== 'string') {
-            errors.push("Info object must have a 'title' field with string value");
+            errors.push(violation('info-title', "Info object must have a 'title' field with string value"));
         }
         if (!info.version || typeof info.version !== 'string') {
-            errors.push("Info object must have a 'version' field with string value");
+            errors.push(violation('info-version', "Info object must have a 'version' field with string value"));
         }
     }
     if (!s.paths || typeof s.paths !== 'object' || Array.isArray(s.paths)) {
-        errors.push("OpenAPI 3.0 specification must have a 'paths' field with object value");
+        errors.push(violation('paths-object', "OpenAPI 3.0 specification must have a 'paths' field with object value"));
     }
     if (s.paths && typeof s.paths === 'object' && !Array.isArray(s.paths)) {
         for (const [pathKey, pathItem] of Object.entries(s.paths)) {
             if (!pathItem || typeof pathItem !== 'object' || Array.isArray(pathItem)) {
-                errors.push(`Path item '${pathKey}' must be an object`);
+                errors.push(violation('path-item-object', `Path item '${pathKey}' must be an object`));
             }
         }
     }
@@ -48,13 +57,13 @@ export function validateSpec30(spec) {
         const components = s.components;
         if (components.schemas) {
             if (Array.isArray(components.schemas) || typeof components.schemas !== 'object') {
-                errors.push("'components.schemas' must be an object");
+                errors.push(violation('components-schemas', "'components.schemas' must be an object"));
             }
             else {
                 const schemas = components.schemas;
                 for (const [key, schema] of Object.entries(schemas)) {
                     if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-                        errors.push(`Schema '${key}' must be an object`);
+                        errors.push(violation('schema-object', `Schema '${key}' must be an object`));
                     }
                     else {
                         validateSchema30(schema, `components.schemas.${key}`, errors);
@@ -63,6 +72,7 @@ export function validateSpec30(spec) {
             }
         }
     }
+    validateSecurity(s, '3.0', errors);
     return {
         valid: errors.length === 0,
         errors,
@@ -78,13 +88,13 @@ function validateSchema30(schema, path, errors) {
     }
     const s = schema;
     if (Array.isArray(s.type)) {
-        errors.push(`Schema '${path}' uses 'type' as an array which is a 3.1-only feature`);
+        errors.push(violation('schema-object', `Schema '${path}' uses 'type' as an array which is a 3.1-only feature`));
     }
     if ('$schema' in s) {
-        errors.push(`Schema '${path}' uses '$schema' which is a 3.1-only feature`);
+        errors.push(violation('schema-object', `Schema '${path}' uses '$schema' which is a 3.1-only feature`));
     }
     if (s.items !== undefined && Array.isArray(s.items)) {
-        errors.push(`Schema '${path}' uses 'items' as an array (tuple syntax) which is a 3.1-only feature`);
+        errors.push(violation('schema-object', `Schema '${path}' uses 'items' as an array (tuple syntax) which is a 3.1-only feature`));
     }
     if (s.properties && typeof s.properties === 'object' && !Array.isArray(s.properties)) {
         for (const [key, prop] of Object.entries(s.properties)) {

package/dist/parser/version/v3.1/validator.d.ts

@@ -13,5 +13,7 @@ import type { ValidationResult } from '../validate.js';
  * - Accepts `type` as array, `$schema`, `$id`, `$comment`, `const`, `examples`, and `$ref` siblings
  *   (all legal in 3.1 via JSON Schema 2020-12)
  * - Accepts schema-level `example` (deprecated in 3.1 but still legal)
+ * - Validates `components.securitySchemes` and `security` requirements (shared rules;
+ *   `mutualTLS` accepted, non-empty scopes for non-oauth2/openIdConnect schemes allowed as role names)
  */
 export declare function validateSpec31(spec: unknown): ValidationResult;

package/dist/parser/version/v3.1/validator.js

@@ -1,3 +1,10 @@
+import { specViolation } from '../spec-links.js';
+import { validateSecurity } from '../validate-security.js';
+/**
+ * Every violation in this file belongs to the 3.1 dialect;
+ * bind it once so call sites stay key-and-message only.
+ */
+const violation = (key, message) => specViolation('3.1', key, message);
 /**
  * Validate a raw OpenAPI 3.1.x specification.
  *
@@ -12,50 +19,54 @@
  * - Accepts `type` as array, `$schema`, `$id`, `$comment`, `const`, `examples`, and `$ref` siblings
  *   (all legal in 3.1 via JSON Schema 2020-12)
  * - Accepts schema-level `example` (deprecated in 3.1 but still legal)
+ * - Validates `components.securitySchemes` and `security` requirements (shared rules;
+ *   `mutualTLS` accepted, non-empty scopes for non-oauth2/openIdConnect schemes allowed as role names)
  */
 export function validateSpec31(spec) {
     const errors = [];
     if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
-        errors.push('Document must be an object');
+        errors.push(violation('document-root', 'Document must be an object'));
         return { valid: false, errors };
     }
     const s = spec;
     if (!s.openapi || typeof s.openapi !== 'string') {
-        errors.push("OpenAPI specification must have an 'openapi' field with string value");
+        errors.push(violation('openapi-field', "OpenAPI specification must have an 'openapi' field with string value"));
     }
     else if (!s.openapi.startsWith('3.1')) {
-        errors.push(`OpenAPI version must start with '3.1', got: ${s.openapi}`);
+        errors.push(violation('openapi-field', `OpenAPI version must start with '3.1', got: ${s.openapi}`));
     }
     if (!s.info || typeof s.info !== 'object' || Array.isArray(s.info)) {
-        errors.push("OpenAPI specification must have an 'info' field with object value");
+        errors.push(violation('info-object', "OpenAPI specification must have an 'info' field with object value"));
     }
     else {
         const info = s.info;
         if (!info.title || typeof info.title !== 'string') {
-            errors.push("Info object must have a 'title' field with string value");
+            errors.push(violation('info-title', "Info object must have a 'title' field with string value"));
         }
         if (!info.version || typeof info.version !== 'string') {
-            errors.push("Info object must have a 'version' field with string value");
+            errors.push(violation('info-version', "Info object must have a 'version' field with string value"));
         }
     }
     if (!s.paths && !s.components && !s.webhooks) {
+        // Not a spec violation: all three fields are optional in 3.1; the check
+        // exists because an empty document gives genoc nothing to generate.
         errors.push("OpenAPI specification must have at least one of 'paths', 'components', or 'webhooks'");
     }
     if (s.paths) {
         if (typeof s.paths !== 'object' || Array.isArray(s.paths)) {
-            errors.push("'paths' field must be an object");
+            errors.push(violation('paths-object', "'paths' field must be an object"));
         }
     }
     if (s.components && typeof s.components === 'object' && !Array.isArray(s.components)) {
         const components = s.components;
         if (components.schemas) {
             if (typeof components.schemas !== 'object' || Array.isArray(components.schemas)) {
-                errors.push("'components.schemas' must be an object");
+                errors.push(violation('components-schemas', "'components.schemas' must be an object"));
             }
             else {
                 for (const [key, schema] of Object.entries(components.schemas)) {
                     if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-                        errors.push(`Schema '${key}' must be an object`);
+                        errors.push(violation('schema-object', `Schema '${key}' must be an object`));
                     }
                     else {
                         validateSchema31(schema, `components.schemas.${key}`, errors);
@@ -64,6 +75,7 @@ export function validateSpec31(spec) {
             }
         }
     }
+    validateSecurity(s, '3.1', errors);
     return {
         valid: errors.length === 0,
         errors,
@@ -79,16 +91,16 @@ function validateSchema31(schema, path, errors) {
     }
     const s = schema;
     if ('nullable' in s) {
-        errors.push(`Schema '${path}' uses 'nullable' which is a 3.0-only feature`);
+        errors.push(violation('schema-object', `Schema '${path}' uses 'nullable' which is a 3.0-only feature`));
     }
     if (typeof s.exclusiveMinimum === 'boolean') {
-        errors.push(`Schema '${path}' uses 'exclusiveMinimum' as a boolean which is a 3.0-only feature`);
+        errors.push(violation('schema-object', `Schema '${path}' uses 'exclusiveMinimum' as a boolean which is a 3.0-only feature`));
     }
     if (typeof s.exclusiveMaximum === 'boolean') {
-        errors.push(`Schema '${path}' uses 'exclusiveMaximum' as a boolean which is a 3.0-only feature`);
+        errors.push(violation('schema-object', `Schema '${path}' uses 'exclusiveMaximum' as a boolean which is a 3.0-only feature`));
     }
     if (s.items !== undefined && Array.isArray(s.items)) {
-        errors.push(`Schema '${path}' uses 'items' as an array which is not allowed in 3.1 (use 'prefixItems')`);
+        errors.push(violation('schema-object', `Schema '${path}' uses 'items' as an array which is not allowed in 3.1 (use 'prefixItems')`));
     }
     if (s.properties && typeof s.properties === 'object' && !Array.isArray(s.properties)) {
         for (const [key, prop] of Object.entries(s.properties)) {

package/dist/parser/version/validate-security.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared security validation for 3.0 and 3.1 validators.
+ *
+ * Rules are identical across dialects except:
+ * - `mutualTLS` scheme type is 3.1-only
+ * - non-empty scope arrays for non-oauth2/openIdConnect schemes are legal in
+ *   3.1 (role names) but MUST be empty in 3.0
+ *
+ * `$ref` scheme entries are resolved here (internal `#/` pointers, cycle
+ * guarded) so the resolved object is validated like an inline scheme — the
+ * soundness guarantee "validation ⇒ generated scheme payloads are well-formed"
+ * holds for referenced schemes too. External-document refs are left to the
+ * ref-resolver, which rejects them at its own boundary. `security` on a Path
+ * Item is rejected: OpenAPI allows security at document and operation level
+ * only, and silently dropping it would lose auth metadata.
+ */
+export declare function validateSecurity(spec: Record<string, unknown>, version: '3.0' | '3.1', errors: string[]): void;

package/dist/parser/version/validate-security.js

@@ -0,0 +1,218 @@
+/**
+ * Shared security validation for 3.0 and 3.1 validators.
+ *
+ * Rules are identical across dialects except:
+ * - `mutualTLS` scheme type is 3.1-only
+ * - non-empty scope arrays for non-oauth2/openIdConnect schemes are legal in
+ *   3.1 (role names) but MUST be empty in 3.0
+ *
+ * `$ref` scheme entries are resolved here (internal `#/` pointers, cycle
+ * guarded) so the resolved object is validated like an inline scheme — the
+ * soundness guarantee "validation ⇒ generated scheme payloads are well-formed"
+ * holds for referenced schemes too. External-document refs are left to the
+ * ref-resolver, which rejects them at its own boundary. `security` on a Path
+ * Item is rejected: OpenAPI allows security at document and operation level
+ * only, and silently dropping it would lose auth metadata.
+ */
+import { HTTP_METHODS } from '../../utils/http-methods.js';
+import { specViolation } from './spec-links.js';
+const SCHEME_TYPES = {
+    '3.0': new Set(['apiKey', 'http', 'oauth2', 'openIdConnect']),
+    '3.1': new Set(['apiKey', 'http', 'oauth2', 'openIdConnect', 'mutualTLS']),
+};
+export function validateSecurity(spec, version, errors) {
+    /** Raw entries keyed by declared name — presence check for requirement refs. */
+    let declaredNames;
+    /** `name` → resolved (un-ref'd) scheme object used for scope-rule checks. */
+    let resolvedByName;
+    const components = spec.components;
+    const rawSchemes = components?.securitySchemes;
+    if (rawSchemes === undefined) {
+        declaredNames = undefined;
+    }
+    else if (typeof rawSchemes !== 'object' || rawSchemes === null || Array.isArray(rawSchemes)) {
+        errors.push(specViolation(version, 'components-security-schemes', "'components.securitySchemes' must be an object"));
+        declaredNames = new Set();
+        resolvedByName = new Map();
+    }
+    else {
+        const schemes = rawSchemes;
+        declaredNames = new Set(Object.keys(schemes));
+        resolvedByName = new Map();
+        for (const [name, scheme] of Object.entries(schemes)) {
+            const resolved = resolveSchemeTarget(spec, name, scheme, version, new Set(), errors);
+            if (resolved !== undefined) {
+                validateScheme(name, resolved, version, errors);
+                resolvedByName.set(name, resolved);
+            }
+        }
+    }
+    validateSecurityList(spec.security, 'security', declaredNames, resolvedByName, version, errors);
+    const paths = spec.paths;
+    if (typeof paths !== 'object' || paths === null || Array.isArray(paths)) {
+        return;
+    }
+    for (const [pathKey, pathItem] of Object.entries(paths)) {
+        if (typeof pathItem !== 'object' || pathItem === null || Array.isArray(pathItem)) {
+            continue;
+        }
+        if ('security' in pathItem) {
+            errors.push(specViolation(version, 'path-item-object', `'paths.${pathKey}.security' is not allowed: security requirements may be declared at the document and operation levels only`));
+        }
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (typeof op === 'object' && op !== null && !Array.isArray(op)) {
+                validateSecurityList(op.security, `paths.${pathKey}.${method}.security`, declaredNames, resolvedByName, version, errors);
+            }
+        }
+    }
+}
+/**
+ * Follow a scheme entry to its validation target: a non-`$ref` entry is its
+ * own target; internal pointers (`#/…` and the root pointer `#`) are walked
+ * (JSON Pointer escapes honored, cycles guarded) and chained refs are
+ * followed. External refs are returned unresolved (the ref-resolver rejects
+ * them later). Returns `undefined` — after pushing an error — when the entry
+ * is not an object, the pointer dangles or carries malformed percent-
+ * encoding, or a ref cycle is detected.
+ */
+function resolveSchemeTarget(spec, name, entry, version, seenRefs, errors) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        errors.push(specViolation(version, 'security-scheme-object', `Security scheme '${name}' must be an object`));
+        return undefined;
+    }
+    const record = entry;
+    const ref = record.$ref;
+    if (typeof ref !== 'string') {
+        return record;
+    }
+    if (ref !== '#' && !ref.startsWith('#/')) {
+        return record; // external document — the ref-resolver's boundary
+    }
+    if (seenRefs.has(ref)) {
+        errors.push(specViolation(version, 'reference-object', `Security scheme '${name}' has a circular $ref chain ('${ref}')`));
+        return undefined;
+    }
+    seenRefs.add(ref);
+    let segments;
+    try {
+        const pointerBody = ref === '#' ? '' : ref.slice(2);
+        segments =
+            pointerBody === ''
+                ? []
+                : pointerBody
+                    .split('/')
+                    .map((s) => decodeURIComponent(s.replace(/~1/g, '/').replace(/~0/g, '~')));
+    }
+    catch {
+        // malformed percent-encoding (e.g. a bare '%') — same story as a dangling pointer
+        errors.push(specViolation(version, 'reference-object', `Security scheme '${name}' $ref '${ref}' does not resolve`));
+        return undefined;
+    }
+    let target = spec;
+    for (const segment of segments) {
+        if (typeof target !== 'object' ||
+            target === null ||
+            Array.isArray(target) ||
+            !(segment in target)) {
+            errors.push(specViolation(version, 'reference-object', `Security scheme '${name}' $ref '${ref}' does not resolve`));
+            return undefined;
+        }
+        target = target[segment];
+    }
+    return resolveSchemeTarget(spec, name, target, version, seenRefs, errors);
+}
+function validateScheme(name, scheme, version, errors) {
+    if (typeof scheme !== 'object' || scheme === null || Array.isArray(scheme)) {
+        errors.push(specViolation(version, 'security-scheme-object', `Security scheme '${name}' must be an object`));
+        return;
+    }
+    const s = scheme;
+    if (typeof s.$ref === 'string') {
+        return; // external ref — shape belongs to the target document's boundary
+    }
+    const type = s.type;
+    if (typeof type !== 'string' || !SCHEME_TYPES[version].has(type)) {
+        const allowed = [...SCHEME_TYPES[version]].join(', ');
+        errors.push(specViolation(version, 'security-scheme-type', `Security scheme '${name}' must have a 'type' field with one of: ${allowed}, got: ${JSON.stringify(type ?? null)}`));
+        return;
+    }
+    switch (type) {
+        case 'apiKey':
+            if (typeof s.name !== 'string' || s.name === '') {
+                errors.push(specViolation(version, 'security-scheme-name', `apiKey security scheme '${name}' must have a 'name' field with string value`));
+            }
+            if (s.in !== 'query' && s.in !== 'header' && s.in !== 'cookie') {
+                errors.push(specViolation(version, 'security-scheme-in', `apiKey security scheme '${name}' must have an 'in' field with one of: query, header, cookie`));
+            }
+            break;
+        case 'http':
+            if (typeof s.scheme !== 'string' || s.scheme === '') {
+                errors.push(specViolation(version, 'security-scheme-scheme', `http security scheme '${name}' must have a 'scheme' field with string value`));
+            }
+            break;
+        case 'oauth2':
+            validateOauth2Flows(name, s.flows, version, errors);
+            break;
+        case 'openIdConnect':
+            if (typeof s.openIdConnectUrl !== 'string' || s.openIdConnectUrl === '') {
+                errors.push(specViolation(version, 'security-scheme-open-id-connect-url', `openIdConnect security scheme '${name}' must have an 'openIdConnectUrl' field with string value`));
+            }
+            break;
+        case 'mutualTLS':
+            break; // no scheme-specific fields
+    }
+}
+function validateOauth2Flows(name, flows, version, errors) {
+    if (typeof flows !== 'object' || flows === null || Array.isArray(flows)) {
+        errors.push(specViolation(version, 'security-scheme-flows', `oauth2 security scheme '${name}' must have a 'flows' field with object value`));
+        return;
+    }
+    for (const [flowKind, flow] of Object.entries(flows)) {
+        if (flow === undefined) {
+            continue;
+        }
+        if (typeof flow !== 'object' || flow === null || Array.isArray(flow)) {
+            errors.push(specViolation(version, 'oauth-flow-object', `oauth2 flow '${flowKind}' of security scheme '${name}' must be an object`));
+            continue;
+        }
+        const scopes = flow.scopes;
+        if (typeof scopes !== 'object' || scopes === null || Array.isArray(scopes)) {
+            errors.push(specViolation(version, 'oauth-flow-scopes', `oauth2 flow '${flowKind}' of security scheme '${name}' must have a 'scopes' field with object value`));
+        }
+    }
+}
+function validateSecurityList(list, context, declaredNames, resolvedByName, version, errors) {
+    if (list === undefined) {
+        return;
+    }
+    if (!Array.isArray(list)) {
+        errors.push(specViolation(version, 'security-requirement-object', `'${context}' must be an array`));
+        return;
+    }
+    list.forEach((requirement, index) => {
+        const reqContext = `${context}[${index}]`;
+        if (typeof requirement !== 'object' || requirement === null || Array.isArray(requirement)) {
+            errors.push(specViolation(version, 'security-requirement-object', `'${reqContext}' must be an object`));
+            return;
+        }
+        for (const [schemeName, scopes] of Object.entries(requirement)) {
+            if (!declaredNames?.has(schemeName)) {
+                errors.push(specViolation(version, 'security-requirement-object', `'${reqContext}' references unknown security scheme '${schemeName}' (not declared in components.securitySchemes)`));
+                continue;
+            }
+            const schemeType = resolvedByName?.get(schemeName)?.type;
+            if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== 'string')) {
+                errors.push(specViolation(version, 'security-requirement-object', `'${reqContext}.${schemeName}' must be an array of strings`));
+                continue;
+            }
+            if (version === '3.0' &&
+                scopes.length > 0 &&
+                schemeType !== undefined &&
+                schemeType !== 'oauth2' &&
+                schemeType !== 'openIdConnect') {
+                errors.push(specViolation(version, 'security-requirement-object', `'${reqContext}.${schemeName}' must have an empty scopes array for '${String(schemeType)}' schemes in OpenAPI 3.0`));
+            }
+        }
+    });
+}

package/dist/parser/version/version-detector.js

@@ -1,32 +1,35 @@
 /**
  * Version detector for multi-version OpenAPI support
  */
+import { specLinkUrl, SpecViolationError } from './spec-links.js';
 export function detectSpecVersion(rawSpec) {
     if (typeof rawSpec !== 'object' || rawSpec === null || Array.isArray(rawSpec)) {
-        throw new Error('Invalid spec: must be a non-null object');
+        throw new SpecViolationError('Invalid spec: must be a non-null object', 'document-root');
     }
     const spec = rawSpec;
     // Check for Swagger 2.0
     if ('swagger' in spec && typeof spec.swagger === 'string') {
         if (spec.swagger === '2.0') {
+            // Unsupported feature, not a spec violation — the document is valid.
             throw new Error('Swagger 2.0 is not supported. Convert to OpenAPI using swagger2openapi first.');
         }
         throw new Error(`Unsupported Swagger version: ${spec.swagger}`);
     }
     // Check for OpenAPI 3.0+
     if (!('openapi' in spec) || typeof spec.openapi !== 'string') {
-        throw new Error("Invalid spec: missing or invalid 'openapi' field");
+        throw new SpecViolationError("Invalid spec: missing or invalid 'openapi' field", 'openapi-field');
     }
     const openapiVersion = spec.openapi;
-    // Extract major.minor version
-    const versionMatch = openapiVersion.match(/^(\d+\.\d+)/);
-    if (!versionMatch) {
-        throw new Error(`Invalid OpenAPI version format: ${openapiVersion}`);
+    // The version must be major.minor, optionally with a patch segment.
+    if (!openapiVersion.match(/^\d+\.\d+(\.\d+)?$/)) {
+        throw new SpecViolationError(`Invalid OpenAPI version format: ${openapiVersion}`, 'openapi-field');
     }
-    const majorMinorVersion = versionMatch[1];
+    // The format check above guarantees two leading numeric segments.
+    const majorMinorVersion = openapiVersion.split('.').slice(0, 2).join('.');
     // Validate supported versions
     const supportedVersions = ['3.0', '3.1', '3.2'];
     if (!supportedVersions.includes(majorMinorVersion)) {
+        // Unsupported feature, not a spec violation — the document is valid.
         throw new Error(`Unsupported OpenAPI version: ${openapiVersion}. ` +
             `Supported versions: ${supportedVersions.join(', ')}`);
     }
@@ -40,8 +43,24 @@ export function detectSpecVersion(rawSpec) {
  * dialect; `preserveRefSiblings` follows the effective dialect.
  */
 export function resolveVersion(doc, override) {
-    const detected = detectSpecVersion(doc);
+    let detected;
+    try {
+        detected = detectSpecVersion(doc);
+    }
+    catch (error) {
+        if (error instanceof SpecViolationError) {
+            // The dialect is unknown (or the document is not a document at all), so
+            // the link targets the dialect being applied; the override decides when
+            // given, otherwise the latest dialect. Two-space indent: this error is
+            // thrown standalone, not as a `  - ` bullet of validateSpec's message.
+            throw new Error(`${error.message}\n  ${specLinkUrl(override ?? '3.1', error.linkKey)}`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
     if (detected !== '3.0' && detected !== '3.1') {
+        // Unsupported feature, not a spec violation — the document is valid.
         throw new Error('OpenAPI 3.2 is not yet supported. Supported versions: 3.0, 3.1');
     }
     const effective = override ?? detected;

package/dist/runtime/defined-errors.d.ts

@@ -9,8 +9,9 @@ export declare function decorateWithErrors<T, E>(item: T, runtimeErrors: unknown
 };
 /**
  * Type guard that narrows a caught error to a method's defined error union.
- * Returns false for `UnspecifiedApiError` (status not declared in the spec)
- * and for anything that is not an `ApiError`.
+ * Returns false for `UnspecifiedApiError` (status not declared in the spec),
+ * for `DefaultApiError` (declared `default` response - not part of the
+ * per-status error union), and for anything that is not an `ApiError`.
  */
 export declare function isDefinedError<E extends ApiError<number, unknown>>(err: unknown, _fn: {
     __definedErrors: E;

package/dist/runtime/defined-errors.js

@@ -1,4 +1,4 @@
-import { ApiError, UnspecifiedApiError } from './errors.js';
+import { ApiError, DefaultApiError, UnspecifiedApiError } from './errors.js';
 /**
  * Attaches the `__definedErrors` metadata property to a client method.
  * The property carries the method's error codes and is used by
@@ -15,12 +15,15 @@ export function decorateWithErrors(item, runtimeErrors) {
 }
 /**
  * Type guard that narrows a caught error to a method's defined error union.
- * Returns false for `UnspecifiedApiError` (status not declared in the spec)
- * and for anything that is not an `ApiError`.
+ * Returns false for `UnspecifiedApiError` (status not declared in the spec),
+ * for `DefaultApiError` (declared `default` response - not part of the
+ * per-status error union), and for anything that is not an `ApiError`.
  */
 export function isDefinedError(err, _fn) {
     if (err instanceof UnspecifiedApiError)
         return false;
+    if (err instanceof DefaultApiError)
+        return false;
     if (!(err instanceof ApiError))
         return false;
     return true;

package/dist/runtime/errors.d.ts

@@ -16,9 +16,7 @@ export declare class UnspecifiedApiError extends ApiError<number, unknown> {
     constructor(status: number, data: unknown, message: string);
 }
 /** Error thrown for operations that declare a `default` response. */
-export declare class DefaultApiError<TData> extends Error {
-    readonly status: number;
-    readonly data: TData;
+export declare class DefaultApiError<TData> extends ApiError<number, TData> {
     constructor(status: number, data: TData, message: string);
 }
 /** Wraps unexpected failures inside a `Requester` implementation. */

package/dist/runtime/errors.js

@@ -24,13 +24,9 @@ export class UnspecifiedApiError extends ApiError {
     }
 }
 /** Error thrown for operations that declare a `default` response. */
-export class DefaultApiError extends Error {
-    status;
-    data;
+export class DefaultApiError extends ApiError {
     constructor(status, data, message) {
-        super(message);
-        this.status = status;
-        this.data = data;
+        super(status, data, message);
         this.name = 'DefaultApiError';
     }
 }

package/dist/runtime/index.d.ts

@@ -8,4 +8,4 @@
 export { ApiError, UnspecifiedApiError, DefaultApiError, RequesterFailError } from './errors.js';
 export { StreamResponse, ErrorResponse } from './responses.js';
 export { decorateWithErrors, isDefinedError } from './defined-errors.js';
-export type { Requester } from './requester.js';
+export type { Requester, SecurityScheme, SecurityCall, SecurityRequirement, OAuthFlow, OAuthFlows, } from './requester.js';