@skmtc/core 0.28.7 → 0.30.1

package/script/parse/v3-2/string/toString.js

@@ -0,0 +1,249 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toParsedString = exports.toString = void 0;
+const String_js_1 = require("../../../oas/string/String.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const string_types_js_1 = require("../../../oas/string/string-types.js");
+const v = __importStar(require("valibot"));
+const parseNullable_js_1 = require("../_helpers/parseNullable.js");
+const parseEnum_js_1 = require("../_helpers/parseEnum.js");
+const parseExample_js_1 = require("../_helpers/parseExample.js");
+const parseDefault_js_1 = require("../_helpers/parseDefault.js");
+/**
+ * Transforms an OpenAPI v3 string schema object into an internal OAS string representation.
+ *
+ * This function processes OpenAPI string schemas by extracting and parsing nullable values,
+ * examples, enumerations, and default values. It handles the complete transformation from
+ * raw OpenAPI JSON to the SKMTC internal string representation with proper validation
+ * of string formats and constraints.
+ *
+ * The transformation follows a pipeline approach:
+ * 1. Parse nullable flag and extract base value
+ * 2. Parse example values with nullable support
+ * 3. Parse enumeration constraints
+ * 4. Parse default values
+ * 5. Create final OasString instance with format validation
+ *
+ * @param args - Transformation arguments
+ * @param args.context - Parse context providing utilities and tracing
+ * @param args.value - The OpenAPI v3 string schema object to transform
+ * @returns Transformed OAS string object with parsed properties
+ *
+ * @example Basic string transformation
+ * ```typescript
+ * import { toString } from '@skmtc/core';
+ *
+ * const openApiString = {
+ *   type: 'string',
+ *   format: 'email',
+ *   maxLength: 255,
+ *   pattern: '^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: openApiString
+ * });
+ *
+ * console.log(oasString.format); // 'email'
+ * console.log(oasString.maxLength); // 255
+ * ```
+ *
+ * @example String with nullable and enums
+ * ```typescript
+ * const statusString = {
+ *   type: 'string',
+ *   nullable: true,
+ *   enum: ['active', 'inactive', 'pending', null],
+ *   default: 'active',
+ *   example: 'pending'
+ * };
+ *
+ * const oasString = toString({
+ *   context: parseContext,
+ *   value: statusString
+ * });
+ *
+ * console.log(oasString.nullable); // true
+ * console.log(oasString.enums); // ['active', 'inactive', 'pending', null]
+ * ```
+ */
+const toString = ({ context, value, stackTrail }) => {
+    if (value.type === 'string' && Object.keys(value).length === 1) {
+        return context.withStackTrail(stackTrail, () => new String_js_1.OasString({}, context));
+    }
+    const { nullable, value: valueWithoutNullable } = (0, parseNullable_js_1.parseNullable)({
+        value,
+        context,
+        stackTrail
+    });
+    const { example: unparsedExample, ...valueWithoutExample } = valueWithoutNullable;
+    const example = (0, parseExample_js_1.parseExample)({
+        value: unparsedExample,
+        context,
+        parent: valueWithoutNullable,
+        nullable,
+        check: isString,
+        toMessage: item => `Removed invalid example. Expected "string", got: ${item}`,
+        stackTrail
+    });
+    const { enum: unparsedEnums, ...valueWithoutEnums } = valueWithoutExample;
+    const enums = (0, parseEnum_js_1.parseEnum)({
+        value: unparsedEnums,
+        nullable,
+        parent: valueWithoutExample,
+        context,
+        check: isString,
+        toMessage: item => `Removed invalid enum. Expected "string", got: ${item}`,
+        stackTrail
+    });
+    const { default: unparsedDefaultValue, ...valueWithoutDefault } = valueWithoutEnums;
+    const defaultValue = (0, parseDefault_js_1.parseDefault)({
+        value: unparsedDefaultValue,
+        context,
+        parent: valueWithoutEnums,
+        nullable,
+        check: isString,
+        toMessage: item => `Removed invalid default. Expected "string", got: ${item}`,
+        stackTrail
+    });
+    return (0, exports.toParsedString)({
+        context,
+        nullable,
+        example,
+        enums,
+        defaultValue,
+        value: valueWithoutDefault,
+        stackTrail
+    });
+};
+exports.toString = toString;
+/**
+ * Creates an OAS string instance from pre-parsed string schema components.
+ *
+ * This function is the final step in the string transformation pipeline, taking
+ * already-parsed nullable, example, enum, and default values and combining them
+ * with the remaining string properties to create the complete OasString instance.
+ *
+ * The function handles format validation against known OpenAPI string formats,
+ * length constraints parsing, pattern validation, and specification extension
+ * processing. It logs warnings for unrecognized formats while still preserving
+ * them in the output.
+ *
+ * @template Nullable - Boolean type indicating if the string can be null
+ * @param args - Pre-parsed string components
+ * @param args.context - Parse context for tracing and issue logging
+ * @param args.nullable - Parsed nullable flag
+ * @param args.example - Parsed example value (type-safe with nullable)
+ * @param args.enums - Parsed enumeration constraints (type-safe with nullable)
+ * @param args.defaultValue - Parsed default value (type-safe with nullable)
+ * @param args.value - OpenAPI string object without parsed fields
+ * @returns Complete OAS string instance with all properties and validation
+ *
+ * @example Date-time string with validation
+ * ```typescript
+ * const dateTimeString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: '2023-12-25T10:00:00Z',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'date-time',
+ *     title: 'Event Date',
+ *     description: 'When the event occurs'
+ *   }
+ * });
+ *
+ * console.log(dateTimeString.format); // 'date-time'
+ * ```
+ *
+ * @example String with custom format (generates warning)
+ * ```typescript
+ * const customFormatString = toParsedString({
+ *   context: parseContext,
+ *   nullable: false,
+ *   example: 'ABC123',
+ *   enums: undefined,
+ *   defaultValue: undefined,
+ *   value: {
+ *     type: 'string',
+ *     format: 'custom-id', // Unknown format, will log warning
+ *     pattern: '^[A-Z]{3}[0-9]{3}$'
+ *   }
+ * });
+ *
+ * // Logs: "Unexpected format: custom-id"
+ * console.log(customFormatString.format); // 'custom-id' (still preserved)
+ * ```
+ */
+const toParsedString = ({ context, nullable, example, enums, defaultValue, value, stackTrail }) => {
+    if (!v.is(string_types_js_1.oasStringData, value)) {
+        v.parse(string_types_js_1.oasStringData, value);
+    }
+    const { type: _type, title, description, format, maxLength, minLength, pattern, readOnly, writeOnly, deprecated, ...skipped } = value;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: value,
+        context,
+        stackTrail,
+        parentType: 'schema:string'
+    });
+    // `format` is an open vocabulary — custom string formats (e.g. `decimal`,
+    // `utc_datetime`) are spec-legal. The value is preserved on the OasString
+    // below, so an unrecognised format is passed through, not warned.
+    return context.withStackTrail(stackTrail, () => new String_js_1.OasString({
+        title,
+        description,
+        enums,
+        nullable,
+        example,
+        format,
+        maxLength,
+        minLength,
+        pattern,
+        readOnly,
+        writeOnly,
+        default: defaultValue,
+        extensionFields,
+        deprecated
+    }, context));
+};
+exports.toParsedString = toParsedString;
+const isString = (value) => {
+    return typeof value === 'string';
+};

package/script/parse/v3-2/tag/toTagsV3.d.ts

@@ -0,0 +1,22 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasTag } from '../../../oas/tag/Tag.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/** A 3.2 Tag Object: the 3.0 shape plus `summary`, `parent` and `kind`. */
+export type TagObjectV32 = OpenAPIV3.TagObject & {
+    summary?: string;
+    parent?: string;
+    kind?: string;
+};
+export type ToTagsV3Args = {
+    tags: TagObjectV32[] | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toTagsV3: ({ tags, stackTrail, context }: ToTagsV3Args) => OasTag[] | undefined;
+export type ToTagV3Args = {
+    tag: TagObjectV32;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toTagV3: ({ tag, stackTrail, context }: ToTagV3Args) => OasTag;

package/script/parse/v3-2/tag/toTagsV3.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTagV3 = exports.toTagsV3 = void 0;
+const Tag_js_1 = require("../../../oas/tag/Tag.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const toExternalDocs_js_1 = require("../externalDocs/toExternalDocs.js");
+const toTagsV3 = ({ tags, stackTrail, context }) => {
+    if (!tags) {
+        return undefined;
+    }
+    const parents = new Map(tags.map(({ name, parent }) => [name, parent]));
+    return tags.map(tag => {
+        const parentError = toParentError({ name: tag.name, parent: tag.parent, parents });
+        if (!parentError) {
+            return (0, exports.toTagV3)({ tag, stackTrail, context });
+        }
+        context.logIssue({
+            key: 'parent',
+            level: 'warning',
+            message: `Tag '${tag.name}' ${parentError}; dropping 'parent'`,
+            parent: tag,
+            stackTrail,
+            type: 'INVALID_TAG_PARENT'
+        });
+        return (0, exports.toTagV3)({ tag: { ...tag, parent: undefined }, stackTrail, context });
+    });
+};
+exports.toTagsV3 = toTagsV3;
+/** Describes why the tag's `parent` is invalid, or returns undefined when it is valid. */
+const toParentError = ({ name, parent, parents }) => {
+    if (parent === undefined) {
+        return undefined;
+    }
+    if (!parents.has(parent)) {
+        return `names parent '${parent}', which is not a tag`;
+    }
+    if (leadsBackTo({ name, current: parent, parents, visited: new Set() })) {
+        return `is in a parent cycle through '${parent}'`;
+    }
+    return undefined;
+};
+/** Follows the parent chain from `current` and reports whether it reaches `name`. */
+const leadsBackTo = ({ name, current, parents, visited }) => {
+    if (current === undefined) {
+        return false;
+    }
+    if (current === name) {
+        return true;
+    }
+    // The chain loops without reaching `name`: the cycle is above this tag, and
+    // the tags in it report it.
+    if (visited.has(current)) {
+        return false;
+    }
+    return leadsBackTo({
+        name,
+        current: parents.get(current),
+        parents,
+        visited: new Set([...visited, current])
+    });
+};
+const toTagV3 = ({ tag, stackTrail, context }) => {
+    const { name, description, summary, parent, kind, externalDocs, ...skipped } = tag;
+    const parsedExternalDocs = stackTrail.trace('externalDocs', st => (0, toExternalDocs_js_1.toExternalDocs)({ externalDocs, stackTrail: st, context }));
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: tag,
+        context,
+        stackTrail,
+        parentType: 'tag'
+    });
+    const fields = {
+        name,
+        description,
+        summary,
+        parent,
+        kind,
+        externalDocs: parsedExternalDocs,
+        extensionFields
+    };
+    return new Tag_js_1.OasTag(fields);
+};
+exports.toTagV3 = toTagV3;

package/script/parse/v3-2/union/toUnion.d.ts

@@ -0,0 +1,12 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasUnion } from '../../../oas/union/Union.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToUnionArgs = {
+    value: OpenAPIV3.SchemaObject;
+    members: (OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject)[];
+    parentType: 'anyOf' | 'oneOf';
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toUnion: ({ value, members, parentType, stackTrail, context }: ToUnionArgs) => OasUnion;

package/script/parse/v3-2/union/toUnion.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toUnion = void 0;
+const Union_js_1 = require("../../../oas/union/Union.js");
+const toDiscriminatorV3_js_1 = require("../discriminator/toDiscriminatorV3.js");
+const toSchemasV3_js_1 = require("../schema/toSchemasV3.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const parseNullable_js_1 = require("../_helpers/parseNullable.js");
+const parseExample_js_1 = require("../_helpers/parseExample.js");
+const parseDefault_js_1 = require("../_helpers/parseDefault.js");
+const toExternalDocs_js_1 = require("../externalDocs/toExternalDocs.js");
+const toUnion = ({ value, members, parentType, stackTrail, context }) => {
+    const { nullable, value: valueWithoutNullable } = (0, parseNullable_js_1.parseNullable)({
+        value,
+        context,
+        stackTrail
+    });
+    const { discriminator, title, description, externalDocs, example: unparsedExample, default: unparsedDefaultValue, ...skipped } = valueWithoutNullable;
+    const example = (0, parseExample_js_1.parseExample)({
+        value: unparsedExample,
+        context,
+        parent: value,
+        nullable,
+        check: isPresent,
+        toMessage: item => `Removed invalid example. Expected a non-null value, got: ${item}`,
+        stackTrail
+    });
+    const defaultValue = (0, parseDefault_js_1.parseDefault)({
+        value: unparsedDefaultValue,
+        context,
+        parent: value,
+        nullable,
+        check: isPresent,
+        toMessage: item => `Removed invalid default. Expected a non-null value, got: ${item}`,
+        stackTrail
+    });
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: value,
+        context,
+        stackTrail,
+        parentType: `schema:${parentType}`
+    });
+    const discriminatorParsed = stackTrail.trace('discriminator', st => (0, toDiscriminatorV3_js_1.toDiscriminatorV3)({ discriminator, stackTrail: st, context }));
+    const membersParsed = members.reduce((acc, item, index) => {
+        if (item === undefined || item === null) {
+            return acc;
+        }
+        return [
+            ...acc,
+            stackTrail.trace(`${index}`, st => (0, toSchemasV3_js_1.toSchemaV3)({ schema: item, stackTrail: st, context }))
+        ];
+    }, []);
+    return context.withStackTrail(stackTrail, () => new Union_js_1.OasUnion({
+        title,
+        description,
+        externalDocs: stackTrail.trace('externalDocs', st => (0, toExternalDocs_js_1.toExternalDocs)({ externalDocs, stackTrail: st, context })),
+        nullable,
+        default: defaultValue,
+        discriminator: discriminatorParsed,
+        members: membersParsed,
+        example,
+        extensionFields
+    }, context));
+};
+exports.toUnion = toUnion;
+// A union (anyOf/oneOf) value may match any of its members, so the most we
+// can validate without resolving members is that a present default/example
+// is not a bare `null` on a non-nullable schema.
+const isPresent = (value) => {
+    return value !== null && value !== undefined;
+};

package/script/parse/v3-2/unknown/toUnknown.d.ts

@@ -0,0 +1,10 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasUnknown } from '../../../oas/unknown/Unknown.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+export type ToUnknownArgs = {
+    value: OpenAPIV3.SchemaObject;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+export declare const toUnknown: ({ value, stackTrail, context }: ToUnknownArgs) => OasUnknown;

package/script/parse/v3-2/unknown/toUnknown.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toUnknown = void 0;
+const Unknown_js_1 = require("../../../oas/unknown/Unknown.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const toUnknown = ({ value, stackTrail, context }) => {
+    const { type: _type, title, description, example, nullable, ...skipped } = value;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: value,
+        context,
+        stackTrail,
+        parentType: 'schema:unknown'
+    });
+    return context.withStackTrail(stackTrail, () => new Unknown_js_1.OasUnknown({
+        title,
+        description,
+        nullable,
+        extensionFields,
+        example
+    }, context));
+};
+exports.toUnknown = toUnknown;

package/script/parse/v3-2/webhook/toWebhooksV3.d.ts

@@ -0,0 +1,48 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { Method } from '../../../types/Method.js';
+import type { ParseContextType } from '../../../context/parseTypes.js';
+import { OasWebhook } from '../../../oas/webhook/Webhook.js';
+import type { OasPathItem } from '../../../oas/pathItem/PathItem.js';
+import type { StackTrail } from '../../../context/StackTrail.js';
+/**
+ * The 3.1 `webhooks` object: a map of webhook NAME → PathItem, identical
+ * in shape to `paths` but keyed by name rather than URL path. Inline
+ * PathItems only — a webhook PathItem `$ref` is a 3.1 edge case not yet
+ * handled (see the arc note §5 Refs).
+ */
+export type WebhooksObject = Record<string, OpenAPIV3.PathItemObject>;
+type WebhookInfo = {
+    method: Method;
+    name: string;
+    pathItem: OasPathItem | undefined;
+};
+export type ToWebhookV3Args = {
+    operation: OpenAPIV3.OperationObject;
+    webhookInfo: WebhookInfo;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+/**
+ * Parses a single webhook Operation Object into an {@link OasWebhook}.
+ *
+ * Mirrors `toOperationV3` and reuses the same leaf field parsers
+ * (`toParameterListV3` / `toRequestBodyV3` / `toResponsesV3` / …) — the
+ * inner Operation Object is structurally identical. Only the orchestration
+ * is duplicated (the dialect-shaped glue), and the output is an
+ * `OasWebhook` carrying a `name`, not an `OasOperation` carrying a `path`.
+ */
+export declare const toWebhookV3: ({ operation, webhookInfo, stackTrail, context }: ToWebhookV3Args) => OasWebhook;
+export type ToWebhooksV3Args = {
+    webhooks: WebhooksObject | undefined;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+/**
+ * Flattens the 3.1 `webhooks` map into `OasWebhook[]`, mirroring
+ * `toOperationsV3`'s `paths` → `OasOperation[]` flattening. Returns `[]`
+ * when no `webhooks` object is present (the common 3.0 / no-webhook case).
+ * The stack trail nests `webhooks` → `<name>` → `<method>` so
+ * `OasDocument.removeItem` can locate a webhook by name.
+ */
+export declare const toWebhooksV3: ({ webhooks, stackTrail, context }: ToWebhooksV3Args) => OasWebhook[];
+export {};

package/script/parse/v3-2/webhook/toWebhooksV3.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWebhooksV3 = exports.toWebhookV3 = void 0;
+const toRequestBodiesV3_js_1 = require("../requestBody/toRequestBodiesV3.js");
+const toResponseV3_js_1 = require("../response/toResponseV3.js");
+const toParameterV3_js_1 = require("../parameter/toParameterV3.js");
+const Webhook_js_1 = require("../../../oas/webhook/Webhook.js");
+const toPathItemV3_js_1 = require("../pathItem/toPathItemV3.js");
+const methods_js_1 = require("../methods.js");
+const dropAdditionalOperationsV3_js_1 = require("../pathItem/dropAdditionalOperationsV3.js");
+const warnQuerystringConflictsV3_js_1 = require("../parameter/warnQuerystringConflictsV3.js");
+const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const toSecurityRequirement_js_1 = require("../securityRequirement/toSecurityRequirement.js");
+const toExternalDocs_js_1 = require("../externalDocs/toExternalDocs.js");
+const toServerV3_js_1 = require("../server/toServerV3.js");
+/**
+ * Parses a single webhook Operation Object into an {@link OasWebhook}.
+ *
+ * Mirrors `toOperationV3` and reuses the same leaf field parsers
+ * (`toParameterListV3` / `toRequestBodyV3` / `toResponsesV3` / …) — the
+ * inner Operation Object is structurally identical. Only the orchestration
+ * is duplicated (the dialect-shaped glue), and the output is an
+ * `OasWebhook` carrying a `name`, not an `OasOperation` carrying a `path`.
+ */
+const toWebhookV3 = ({ operation, webhookInfo, stackTrail, context }) => {
+    const { method, name, pathItem } = webhookInfo;
+    const { operationId, tags, summary, description, parameters, requestBody, responses, deprecated, security, externalDocs, servers, ...skipped } = operation;
+    const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
+        skipped,
+        parent: operation,
+        context,
+        stackTrail,
+        parentType: 'operation'
+    });
+    const parsedParameters = stackTrail.trace('parameters', st => (0, toParameterV3_js_1.toParameterListV3)({ parameters, stackTrail: st, context }));
+    (0, warnQuerystringConflictsV3_js_1.warnQuerystringConflictsV3)({ parameters: parsedParameters, pathItem, stackTrail, context });
+    const parsedRequestBody = stackTrail.trace('requestBody', st => (0, toRequestBodiesV3_js_1.toRequestBodyV3)({ requestBody, stackTrail: st, context }));
+    const parsedResponses = stackTrail.trace('responses', st => (0, toResponseV3_js_1.toResponsesV3)({ responses, stackTrail: st, context }));
+    const parsedSecurity = stackTrail.trace('security', st => (0, toSecurityRequirement_js_1.toSecurityRequirementsV3)({ security, stackTrail: st, context }));
+    const parsedExternalDocs = stackTrail.trace('externalDocs', st => (0, toExternalDocs_js_1.toExternalDocs)({ externalDocs, stackTrail: st, context }));
+    const parsedServers = stackTrail.trace('servers', st => (0, toServerV3_js_1.toOptionalServersV3)({ servers, stackTrail: st, context }));
+    return context.withStackTrail(stackTrail, () => new Webhook_js_1.OasWebhook({
+        pathItem,
+        name,
+        method,
+        operationId,
+        summary,
+        tags,
+        description,
+        parameters: parsedParameters,
+        requestBody: parsedRequestBody,
+        responses: parsedResponses,
+        deprecated,
+        security: parsedSecurity,
+        externalDocs: parsedExternalDocs,
+        servers: parsedServers,
+        extensionFields
+    }, context));
+};
+exports.toWebhookV3 = toWebhookV3;
+/**
+ * Flattens the 3.1 `webhooks` map into `OasWebhook[]`, mirroring
+ * `toOperationsV3`'s `paths` → `OasOperation[]` flattening. Returns `[]`
+ * when no `webhooks` object is present (the common 3.0 / no-webhook case).
+ * The stack trail nests `webhooks` → `<name>` → `<method>` so
+ * `OasDocument.removeItem` can locate a webhook by name.
+ */
+const toWebhooksV3 = ({ webhooks, stackTrail, context }) => {
+    if (!webhooks) {
+        return [];
+    }
+    return Object.entries(webhooks).flatMap(([name, pathItem]) => {
+        return stackTrail.trace(name, nameStack => {
+            if (!pathItem) {
+                return [];
+            }
+            const fixedFields = (0, dropAdditionalOperationsV3_js_1.dropAdditionalOperationsV3)({ pathItem, stackTrail: nameStack, context });
+            const cleaned = Object.entries(fixedFields).reduce(({ rest, methodObject }, [key, operation]) => {
+                const method = (0, methods_js_1.toPathItemMethod)(key);
+                if (method) {
+                    const { [method]: _deleted, ...remaining } = rest;
+                    return {
+                        rest: remaining,
+                        methodObject: {
+                            ...methodObject,
+                            [method]: operation
+                        }
+                    };
+                }
+                return { rest, methodObject };
+            }, {
+                rest: fixedFields,
+                methodObject: {}
+            });
+            const pathItemResult = (0, toPathItemV3_js_1.toPathItemResultV3)({
+                pathItem: cleaned.rest,
+                stackTrail: nameStack,
+                context
+            });
+            if (!pathItemResult.valid) {
+                return [];
+            }
+            const pathItemObject = pathItemResult.pathItem;
+            return Object.entries(cleaned.methodObject)
+                .map(([method, operation]) => {
+                // Use `nameStack` (the trail with the webhook name already
+                // pushed) so downstream traces record webhooks:<name>:<method>:…
+                // — the trail `OasDocument.removeItem` matches a webhook on.
+                return nameStack.trace(method, st => {
+                    if (!operation) {
+                        return;
+                    }
+                    try {
+                        return (0, exports.toWebhookV3)({
+                            operation,
+                            webhookInfo: {
+                                method: method,
+                                name,
+                                pathItem: pathItemObject
+                            },
+                            stackTrail: st,
+                            context
+                        });
+                    }
+                    catch (error) {
+                        const normalized = error instanceof Error ? error : new Error(String(error));
+                        context.logIssue({
+                            key: method,
+                            parent: operation,
+                            level: 'error',
+                            message: normalized.message,
+                            cause: normalized,
+                            stackTrail: st,
+                            type: 'INVALID_OPERATION'
+                        });
+                        return undefined;
+                    }
+                });
+            })
+                .filter((item) => Boolean(item));
+        });
+    });
+};
+exports.toWebhooksV3 = toWebhooksV3;