genoc 0.4.2 → 0.5.0

package/dist/parser/spec-reader.js

@@ -5,23 +5,6 @@ import { fetchSpec } from '../utils/proxy.js';
 import { isUrl } from '../utils/url.js';
 const VALID_EXTENSIONS = ['.json', '.yaml', '.yml'];
 const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
-function assertSupportedVersion(doc) {
-    if (typeof doc !== 'object' ||
-        doc === null ||
-        !('openapi' in doc) ||
-        typeof doc.openapi !== 'string') {
-        throw new Error("Invalid spec: missing or invalid 'openapi' field.");
-    }
-    const version = doc.openapi;
-    // Check for valid version format
-    if (!version.match(/^\d+\.\d+(\.\d+)?$/)) {
-        throw new Error(`Invalid OpenAPI version format: ${version}`);
-    }
-    // Check that major version is 3 (but don't restrict minor versions)
-    if (!version.startsWith('3.')) {
-        throw new Error(`Unsupported OpenAPI version: ${version}. Supported versions: 3.0, 3.1, 3.2`);
-    }
-}
 function parseContent(content, ext) {
     if (ext === '.json') {
         try {
@@ -69,10 +52,10 @@ export async function loadFromFile(filePath) {
         throw new Error(`Failed to load spec from file: ${err.message}`, { cause: err });
     }
     const doc = parseContent(content, ext);
-    if (typeof doc !== 'object' || doc === null) {
-        throw new Error('Failed to parse: spec is not an object.');
-    }
-    assertSupportedVersion(doc);
+    // Version/dialect rules — including whether the parsed root is even an
+    // OpenAPI document — belong to the version module, which resolves the
+    // dialect and links spec violations to the specification. The cast is safe
+    // for the same I/O reason as above: callers validate via resolveVersion.
     return doc;
 }
 export async function loadFromUrl(url, opts) {
@@ -103,10 +86,8 @@ export async function loadFromUrl(url, opts) {
             throw new Error(`Failed to parse spec from URL as JSON or YAML: ${yamlErr.message}`, { cause: yamlErr });
         }
     }
-    if (typeof doc !== 'object' || doc === null) {
-        throw new Error('Failed to parse: spec is not an object.');
-    }
-    assertSupportedVersion(doc);
+    // Version/dialect rules — including document-rootedness — belong to the
+    // version module (see loadFromFile).
     return doc;
 }
 export async function load(source, opts) {

package/dist/parser/version/spec-links.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Single source of links from spec-violation errors to the section of the
+ * OpenAPI specification that states the rule being violated.
+ *
+ * Unsupported-feature errors (Swagger 2.0, OpenAPI 3.2, external `$ref`s)
+ * never use this module: the document is valid and the error cites a genoc
+ * limitation, not a specification rule.
+ */
+/** Latest patch release per dialect. */
+export declare const SPEC_PAGE: Record<'3.0' | '3.1', string>;
+/**
+ * One anchor per violated rule, shared by both dialect pages. A wrong anchor
+ * is a one-line fix here; no automated anchor checking exists.
+ */
+export declare const SPEC_ANCHORS: {
+    readonly 'document-root': "openapi-object";
+    readonly 'openapi-field': "oas-version";
+    readonly 'info-object': "info-object";
+    readonly 'info-title': "info-title";
+    readonly 'info-version': "info-version";
+    readonly 'paths-object': "paths-object";
+    readonly 'path-item-object': "path-item-object";
+    readonly 'components-security-schemes': "security-scheme-object";
+    readonly 'components-schemas': "components-schemas";
+    readonly 'schema-object': "schema-object";
+    readonly 'security-scheme-object': "security-scheme-object-0";
+    readonly 'security-scheme-type': "security-scheme-type";
+    readonly 'security-scheme-name': "security-scheme-name";
+    readonly 'security-scheme-in': "security-scheme-in";
+    readonly 'security-scheme-scheme': "security-scheme-scheme";
+    readonly 'security-scheme-flows': "security-scheme-flows";
+    readonly 'security-scheme-open-id-connect-url': "security-scheme-open-id-connect-url";
+    readonly 'oauth-flow-object': "oauth-flow-object";
+    readonly 'oauth-flow-scopes': "oauth-flow-scopes";
+    readonly 'reference-object': "reference-object";
+    readonly 'security-requirement-object': "security-requirement-object";
+};
+export type SpecLinkKey = keyof typeof SPEC_ANCHORS;
+export declare function specLinkUrl(version: '3.0' | '3.1', key: SpecLinkKey): string;
+/**
+ * Renders a spec-violation message with its link line appended on its own
+ * line, indented four spaces so it aligns under the `  - ` bullet that
+ * `validateSpec` puts each message in.
+ */
+export declare function specViolation(version: '3.0' | '3.1', key: SpecLinkKey, message: string): string;
+/**
+ * Detection error for a document that violates the specification itself
+ * (as opposed to an unsupported-but-valid dialect). Carries the anchor key
+ * so `resolveVersion` can render the link against the dialect being applied.
+ */
+export declare class SpecViolationError extends Error {
+    /** Which specification section states the violated rule. */
+    linkKey: SpecLinkKey;
+    constructor(message: string, linkKey: SpecLinkKey);
+}

package/dist/parser/version/spec-links.js

@@ -0,0 +1,65 @@
+/**
+ * Single source of links from spec-violation errors to the section of the
+ * OpenAPI specification that states the rule being violated.
+ *
+ * Unsupported-feature errors (Swagger 2.0, OpenAPI 3.2, external `$ref`s)
+ * never use this module: the document is valid and the error cites a genoc
+ * limitation, not a specification rule.
+ */
+/** Latest patch release per dialect. */
+export const SPEC_PAGE = {
+    '3.0': 'https://spec.openapis.org/oas/v3.0.4.html',
+    '3.1': 'https://spec.openapis.org/oas/v3.1.1.html',
+};
+/**
+ * One anchor per violated rule, shared by both dialect pages. A wrong anchor
+ * is a one-line fix here; no automated anchor checking exists.
+ */
+export const SPEC_ANCHORS = {
+    'document-root': 'openapi-object',
+    'openapi-field': 'oas-version',
+    'info-object': 'info-object',
+    'info-title': 'info-title',
+    'info-version': 'info-version',
+    'paths-object': 'paths-object',
+    'path-item-object': 'path-item-object',
+    'components-security-schemes': 'security-scheme-object',
+    'components-schemas': 'components-schemas',
+    'schema-object': 'schema-object',
+    'security-scheme-object': 'security-scheme-object-0',
+    'security-scheme-type': 'security-scheme-type',
+    'security-scheme-name': 'security-scheme-name',
+    'security-scheme-in': 'security-scheme-in',
+    'security-scheme-scheme': 'security-scheme-scheme',
+    'security-scheme-flows': 'security-scheme-flows',
+    'security-scheme-open-id-connect-url': 'security-scheme-open-id-connect-url',
+    'oauth-flow-object': 'oauth-flow-object',
+    'oauth-flow-scopes': 'oauth-flow-scopes',
+    'reference-object': 'reference-object',
+    'security-requirement-object': 'security-requirement-object',
+};
+export function specLinkUrl(version, key) {
+    return `${SPEC_PAGE[version]}#${SPEC_ANCHORS[key]}`;
+}
+/**
+ * Renders a spec-violation message with its link line appended on its own
+ * line, indented four spaces so it aligns under the `  - ` bullet that
+ * `validateSpec` puts each message in.
+ */
+export function specViolation(version, key, message) {
+    return `${message}\n    ${specLinkUrl(version, key)}`;
+}
+/**
+ * Detection error for a document that violates the specification itself
+ * (as opposed to an unsupported-but-valid dialect). Carries the anchor key
+ * so `resolveVersion` can render the link against the dialect being applied.
+ */
+export class SpecViolationError extends Error {
+    /** Which specification section states the violated rule. */
+    linkKey;
+    constructor(message, linkKey) {
+        super(message);
+        this.name = 'SpecViolationError';
+        this.linkKey = linkKey;
+    }
+}

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`));
+            }
+        }
+    });
+}