@mintlify/common 1.0.1206 → 1.0.1207

package/dist/openapi/additionalOperations.d.ts

@@ -1,5 +1,3 @@
-import { type OpenAPIV3_2 } from '@mintlify/validation';
+import { type PathItemSources } from './pathItems.js';
 import type { OpenApiValidateError } from './validate.js';
-type PathItemSources = Partial<Pick<OpenAPIV3_2.Document, 'paths' | 'webhooks' | 'components'>>;
 export declare const validateAdditionalOperations: (document: PathItemSources) => OpenApiValidateError[];
-export {};

package/dist/openapi/additionalOperations.js

@@ -1,5 +1,5 @@
-import { getPathItemOperations, isAdditionalHttpMethod, isFixedHttpMethod, } from '@mintlify/validation';
-const escapePointer = (segment) => segment.replaceAll('~', '~0').replaceAll('/', '~1');
+import { getPathItemOperations, isAdditionalHttpMethod, } from '@mintlify/validation';
+import { escapePointer, operationPointer, } from './pathItems.js';
 const callbackPathItemsOf = (location, pathItem) => {
     if (!pathItem || '$ref' in pathItem)
         return [];
@@ -7,14 +7,11 @@ const callbackPathItemsOf = (location, pathItem) => {
         const callbacks = operation.callbacks;
         if (!callbacks)
             return [];
-        const operationPointer = isFixedHttpMethod(method)
-            ? escapePointer(method)
-            : `additionalOperations/${escapePointer(method)}`;
         return Object.entries(callbacks).flatMap(([name, callback]) => {
             if (!callback || '$ref' in callback)
                 return [];
             return Object.entries(callback).flatMap(([expression, item]) => {
-                const itemLocation = `${location}/${operationPointer}/callbacks/${escapePointer(name)}/${escapePointer(expression)}`;
+                const itemLocation = `${location}/${operationPointer(method)}/callbacks/${escapePointer(name)}/${escapePointer(expression)}`;
                 const entry = [itemLocation, item];
                 return [entry, ...callbackPathItemsOf(itemLocation, item)];
             });

package/dist/openapi/discriminators.d.ts

@@ -0,0 +1,4 @@
+import { type PathItemSources } from './pathItems.js';
+import type { OpenApiValidateError } from './validate.js';
+export declare const resolveDiscriminatorTargetPointer: (target: string) => string | undefined;
+export declare const validateDiscriminatorDefaults: (document: PathItemSources) => OpenApiValidateError[];

package/dist/openapi/discriminators.js

@@ -0,0 +1,121 @@
+import { isObject } from '../types/guards.js';
+import { forEachDocumentPosition } from './documentPositions.js';
+import { escapePointer } from './pathItems.js';
+const unescapePointerToken = (token) => token.replace(/~1/g, '/').replace(/~0/g, '~');
+export const resolveDiscriminatorTargetPointer = (target) => {
+    if (target.startsWith('#')) {
+        try {
+            const pointer = decodeURIComponent(target.slice(1));
+            return pointer.startsWith('/') ? pointer : undefined;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    const name = target.startsWith('./') ? target.slice(2) : target;
+    return `/components/schemas/${escapePointer(name)}`;
+};
+const ALIAS_KEYS = new Set(['$ref', 'summary', 'description']);
+const componentSchemaName = (pointer) => {
+    const match = /^\/components\/schemas\/([^/]+)$/.exec(pointer);
+    return (match === null || match === void 0 ? void 0 : match[1]) === undefined ? undefined : unescapePointerToken(match[1]);
+};
+export const validateDiscriminatorDefaults = (document) => {
+    const errors = [];
+    const componentSchemas = isObject(document.components)
+        ? document.components.schemas
+        : undefined;
+    const schemaExists = (pointer) => {
+        const name = pointer === undefined ? undefined : componentSchemaName(pointer);
+        return (name !== undefined &&
+            isObject(componentSchemas) &&
+            Object.prototype.hasOwnProperty.call(componentSchemas, name) &&
+            isObject(componentSchemas[name]));
+    };
+    const canonicalSchemaPointer = (pointer) => {
+        const seen = new Set();
+        let current = pointer;
+        while (!seen.has(current)) {
+            seen.add(current);
+            const name = componentSchemaName(current);
+            const schema = name === undefined || !isObject(componentSchemas) ? undefined : componentSchemas[name];
+            if (!isObject(schema) ||
+                typeof schema.$ref !== 'string' ||
+                !Object.keys(schema).every((key) => ALIAS_KEYS.has(key))) {
+                return current;
+            }
+            const next = resolveDiscriminatorTargetPointer(schema.$ref);
+            if (next === undefined || !schemaExists(next))
+                return current;
+            current = next;
+        }
+        return current;
+    };
+    const variantPointers = (schema) => {
+        const members = [
+            ...(Array.isArray(schema.oneOf) ? schema.oneOf : []),
+            ...(Array.isArray(schema.anyOf) ? schema.anyOf : []),
+        ];
+        if (members.length === 0)
+            return undefined;
+        return members.flatMap((member) => {
+            if (!isObject(member) || typeof member.$ref !== 'string')
+                return [];
+            const pointer = resolveDiscriminatorTargetPointer(member.$ref);
+            return pointer === undefined ? [] : [canonicalSchemaPointer(pointer)];
+        });
+    };
+    const componentSchema = (pointer) => {
+        const name = componentSchemaName(pointer);
+        const schema = name === undefined || !isObject(componentSchemas) ? undefined : componentSchemas[name];
+        return isObject(schema) ? schema : undefined;
+    };
+    const compositionOf = (schema, seen) => {
+        const own = Object.assign(Object.assign(Object.assign({}, ('oneOf' in schema ? { oneOf: schema.oneOf } : {})), ('anyOf' in schema ? { anyOf: schema.anyOf } : {})), ('allOf' in schema ? { allOf: schema.allOf } : {}));
+        if (typeof schema.$ref !== 'string')
+            return own;
+        const pointer = resolveDiscriminatorTargetPointer(schema.$ref);
+        const canonical = pointer === undefined ? undefined : canonicalSchemaPointer(pointer);
+        if (canonical === undefined || seen.has(canonical))
+            return own;
+        seen.add(canonical);
+        const target = componentSchema(canonical);
+        return target === undefined ? own : Object.assign(Object.assign({}, compositionOf(target, seen)), own);
+    };
+    const reachableVariantPointers = (schema, seen) => {
+        const composition = compositionOf(schema, seen);
+        const own = variantPointers(composition);
+        const nested = (Array.isArray(composition.allOf) ? composition.allOf : []).flatMap((member) => {
+            if (!isObject(member))
+                return [];
+            const inner = reachableVariantPointers(member, seen);
+            return inner === undefined ? [] : [inner];
+        });
+        if (own === undefined && nested.length === 0)
+            return undefined;
+        return [...(own !== null && own !== void 0 ? own : []), ...nested.flat()];
+    };
+    forEachDocumentPosition(document, {
+        onSchema: (path, schema) => {
+            const discriminator = schema.discriminator;
+            if (!isObject(discriminator) || typeof discriminator.defaultMapping !== 'string')
+                return;
+            const target = discriminator.defaultMapping;
+            const pointer = resolveDiscriminatorTargetPointer(target);
+            const variants = reachableVariantPointers(schema, new Set());
+            const exists = schemaExists(pointer);
+            const selectable = exists &&
+                (variants === undefined ||
+                    (pointer !== undefined && variants.includes(canonicalSchemaPointer(pointer))));
+            if (!selectable) {
+                errors.push({
+                    path: `${path}/discriminator/defaultMapping`,
+                    message: exists
+                        ? `defaultMapping ${target} is not one of the schema's oneOf/anyOf variants`
+                        : `defaultMapping ${target} does not name a schema in mapping or components.schemas`,
+                });
+            }
+        },
+    });
+    return errors;
+};

package/dist/openapi/documentPositions.d.ts

@@ -0,0 +1,10 @@
+import { type PathItemSources } from './pathItems.js';
+type Visitor = (path: string, value: Record<string, unknown>) => void;
+export type DocumentVisitors = {
+    onMediaType?: Visitor;
+    onSchema?: Visitor;
+    onParameter?: Visitor;
+    onHeaderName?: (path: string, name: string) => void;
+};
+export declare const forEachDocumentPosition: (document: PathItemSources, visitors: DocumentVisitors) => void;
+export {};

package/dist/openapi/documentPositions.js

@@ -0,0 +1,154 @@
+import { getPathItemOperations } from '@mintlify/validation';
+import { isObject } from '../types/guards.js';
+import { escapePointer, forEachPathItem, operationPointer, } from './pathItems.js';
+const SCHEMA_KEYWORDS = [
+    'additionalProperties',
+    'contains',
+    'contentSchema',
+    'else',
+    'if',
+    'items',
+    'not',
+    'propertyNames',
+    'then',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+];
+const SCHEMA_MAP_KEYWORDS = [
+    '$defs',
+    'dependentSchemas',
+    'patternProperties',
+    'properties',
+];
+const SCHEMA_LIST_KEYWORDS = ['allOf', 'anyOf', 'oneOf', 'prefixItems'];
+const visitSchema = (value, path, walk) => {
+    var _a, _b;
+    if (!isObject(value) || walk.seen.has(value))
+        return;
+    walk.seen.add(value);
+    (_b = (_a = walk.visitors).onSchema) === null || _b === void 0 ? void 0 : _b.call(_a, path, value);
+    for (const keyword of SCHEMA_KEYWORDS) {
+        visitSchema(value[keyword], `${path}/${keyword}`, walk);
+    }
+    for (const keyword of SCHEMA_MAP_KEYWORDS) {
+        const entries = value[keyword];
+        if (!isObject(entries))
+            continue;
+        for (const [name, child] of Object.entries(entries)) {
+            visitSchema(child, `${path}/${keyword}/${escapePointer(name)}`, walk);
+        }
+    }
+    for (const keyword of SCHEMA_LIST_KEYWORDS) {
+        const list = value[keyword];
+        if (!Array.isArray(list))
+            continue;
+        list.forEach((child, index) => visitSchema(child, `${path}/${keyword}/${index}`, walk));
+    }
+};
+const visitEncoding = (value, path, walk) => {
+    if (!isObject(value) || walk.seen.has(value))
+        return;
+    walk.seen.add(value);
+    visitHeaderMap(value.headers, `${path}/headers`, walk);
+    visitEncodings(value, path, walk);
+};
+const visitEncodings = (value, path, walk) => {
+    if (isObject(value.encoding)) {
+        for (const [name, encoding] of Object.entries(value.encoding)) {
+            visitEncoding(encoding, `${path}/encoding/${escapePointer(name)}`, walk);
+        }
+    }
+    if (Array.isArray(value.prefixEncoding)) {
+        value.prefixEncoding.forEach((encoding, index) => visitEncoding(encoding, `${path}/prefixEncoding/${index}`, walk));
+    }
+    visitEncoding(value.itemEncoding, `${path}/itemEncoding`, walk);
+};
+const visitMedia = (value, path, walk) => {
+    var _a, _b;
+    if (!isObject(value))
+        return;
+    if (!('$ref' in value))
+        (_b = (_a = walk.visitors).onMediaType) === null || _b === void 0 ? void 0 : _b.call(_a, path, value);
+    visitSchema(value.schema, `${path}/schema`, walk);
+    visitSchema(value.itemSchema, `${path}/itemSchema`, walk);
+    visitEncodings(value, path, walk);
+};
+const visitContent = (value, path, walk) => {
+    if (!isObject(value))
+        return;
+    for (const [mediaType, media] of Object.entries(value)) {
+        visitMedia(media, `${path}/${escapePointer(mediaType)}`, walk);
+    }
+};
+const visitParameterOrHeader = (value, path, walk) => {
+    if (!isObject(value) || '$ref' in value)
+        return;
+    visitSchema(value.schema, `${path}/schema`, walk);
+    visitContent(value.content, `${path}/content`, walk);
+};
+const visitParameter = (value, path, walk) => {
+    var _a, _b;
+    if (!isObject(value) || '$ref' in value)
+        return;
+    (_b = (_a = walk.visitors).onParameter) === null || _b === void 0 ? void 0 : _b.call(_a, path, value);
+    visitParameterOrHeader(value, path, walk);
+};
+const visitComponentMap = (value, path, walk, visit) => {
+    if (!isObject(value))
+        return;
+    for (const [name, entry] of Object.entries(value)) {
+        visit(entry, `${path}/${escapePointer(name)}`, walk);
+    }
+};
+const visitHeaderMap = (value, path, walk) => {
+    var _a, _b;
+    if (!isObject(value))
+        return;
+    for (const [name, header] of Object.entries(value)) {
+        const entryPath = `${path}/${escapePointer(name)}`;
+        (_b = (_a = walk.visitors).onHeaderName) === null || _b === void 0 ? void 0 : _b.call(_a, entryPath, name);
+        visitParameterOrHeader(header, entryPath, walk);
+    }
+};
+const visitRequestBody = (value, path, walk) => {
+    if (!isObject(value) || '$ref' in value)
+        return;
+    visitContent(value.content, `${path}/content`, walk);
+};
+const visitResponse = (value, path, walk) => {
+    if (!isObject(value) || '$ref' in value)
+        return;
+    visitHeaderMap(value.headers, `${path}/headers`, walk);
+    visitContent(value.content, `${path}/content`, walk);
+};
+export const forEachDocumentPosition = (document, visitors) => {
+    var _a, _b, _c, _d, _e;
+    const walk = { visitors, seen: new Set() };
+    const components = (_a = document.components) !== null && _a !== void 0 ? _a : {};
+    for (const [name, schema] of Object.entries((_b = components.schemas) !== null && _b !== void 0 ? _b : {})) {
+        visitSchema(schema, `/components/schemas/${escapePointer(name)}`, walk);
+    }
+    visitComponentMap(components.parameters, '/components/parameters', walk, visitParameter);
+    visitComponentMap(components.headers, '/components/headers', walk, visitParameterOrHeader);
+    for (const [name, body] of Object.entries((_c = components.requestBodies) !== null && _c !== void 0 ? _c : {})) {
+        visitRequestBody(body, `/components/requestBodies/${escapePointer(name)}`, walk);
+    }
+    for (const [name, response] of Object.entries((_d = components.responses) !== null && _d !== void 0 ? _d : {})) {
+        visitResponse(response, `/components/responses/${escapePointer(name)}`, walk);
+    }
+    for (const [name, media] of Object.entries((_e = components.mediaTypes) !== null && _e !== void 0 ? _e : {})) {
+        visitMedia(media, `/components/mediaTypes/${escapePointer(name)}`, walk);
+    }
+    forEachPathItem(document, (location, pathItem) => {
+        var _a, _b, _c;
+        ((_a = pathItem.parameters) !== null && _a !== void 0 ? _a : []).forEach((parameter, index) => visitParameter(parameter, `${location}/parameters/${index}`, walk));
+        for (const [method, operation] of getPathItemOperations(pathItem)) {
+            const operationPath = `${location}/${operationPointer(method)}`;
+            ((_b = operation.parameters) !== null && _b !== void 0 ? _b : []).forEach((parameter, index) => visitParameter(parameter, `${operationPath}/parameters/${index}`, walk));
+            visitRequestBody(operation.requestBody, `${operationPath}/requestBody`, walk);
+            for (const [code, response] of Object.entries((_c = operation.responses) !== null && _c !== void 0 ? _c : {})) {
+                visitResponse(response, `${operationPath}/responses/${escapePointer(code)}`, walk);
+            }
+        }
+    });
+};

package/dist/openapi/encodings.d.ts

@@ -0,0 +1,3 @@
+import type { PathItemSources } from './pathItems.js';
+import type { OpenApiValidateError } from './validate.js';
+export declare const validatePositionalEncodings: (document: PathItemSources) => OpenApiValidateError[];

package/dist/openapi/encodings.js

@@ -0,0 +1,59 @@
+import { getComponentNameFromRef } from '@mintlify/validation';
+import { isObject } from '../types/guards.js';
+import { forEachDocumentPosition } from './documentPositions.js';
+const resolveLocalSchema = (schema, componentSchemas, seen = new Set()) => {
+    if (!isObject(schema) || typeof schema.$ref !== 'string')
+        return schema;
+    const name = getComponentNameFromRef(schema.$ref, 'schemas');
+    if (name === undefined || seen.has(name))
+        return undefined;
+    return resolveLocalSchema(componentSchemas[name], componentSchemas, seen.add(name));
+};
+const isArraySchema = (schema, componentSchemas, seen = new Set()) => {
+    if (!isObject(schema) || seen.has(schema))
+        return false;
+    seen.add(schema);
+    if (schema.type !== undefined) {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        return types.includes('array') && types.every((type) => type === 'array' || type === 'null');
+    }
+    if ('items' in schema || 'prefixItems' in schema) {
+        return true;
+    }
+    if (typeof schema.$ref === 'string' &&
+        isArraySchema(resolveLocalSchema(schema, componentSchemas), componentSchemas, seen)) {
+        return true;
+    }
+    if (Array.isArray(schema.allOf) &&
+        schema.allOf.some((member) => isArraySchema(member, componentSchemas, seen))) {
+        return true;
+    }
+    const alternatives = [
+        ...(Array.isArray(schema.oneOf) ? schema.oneOf : []),
+        ...(Array.isArray(schema.anyOf) ? schema.anyOf : []),
+    ];
+    return (alternatives.some((member) => !isNullSchema(resolveLocalSchema(member, componentSchemas))) &&
+        alternatives.every((member) => isNullSchema(resolveLocalSchema(member, componentSchemas)) ||
+            isArraySchema(member, componentSchemas, new Set(seen))));
+};
+const isNullSchema = (schema) => isObject(schema) &&
+    (schema.type === 'null' ||
+        (Array.isArray(schema.type) && schema.type.every((type) => type === 'null')));
+export const validatePositionalEncodings = (document) => {
+    var _a, _b;
+    const errors = [];
+    const componentSchemas = (_b = (_a = document.components) === null || _a === void 0 ? void 0 : _a.schemas) !== null && _b !== void 0 ? _b : {};
+    forEachDocumentPosition(document, {
+        onMediaType: (path, media) => {
+            if (('prefixEncoding' in media || 'itemEncoding' in media) &&
+                !('itemSchema' in media) &&
+                !isArraySchema(media.schema, componentSchemas)) {
+                errors.push({
+                    path,
+                    message: 'prefixEncoding and itemEncoding require itemSchema or an array schema',
+                });
+            }
+        },
+    });
+    return errors;
+};

package/dist/openapi/generateOpenApiPages.js

@@ -1,4 +1,4 @@
-import { getPathItemOperations } from '@mintlify/validation';
+import { getPathItemOperations, resolvePathItemReference, } from '@mintlify/validation';
 import jsYaml from 'js-yaml';
 import { optionallyAddLeadingSlash } from '../fs/optionallySlash.js';
 import { mergePageGroups } from '../navigation/groupAccess.js';
@@ -73,7 +73,7 @@ function getXMintGroups(pathObject, operationObject) {
     return groups;
 }
 export function generateOpenApiPages(opts) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
     const { spec, specFilePath, outputDirectory } = opts;
     const outDir = outputDirectory !== null && outputDirectory !== void 0 ? outputDirectory : DEFAULT_OUTPUT_DIR;
     const openApiFilePathFromRoot = optionallyAddLeadingSlash(specFilePath);
@@ -88,15 +88,15 @@ export function generateOpenApiPages(opts) {
         {
             filename: (_a = specFilePath.split('/').pop()) !== null && _a !== void 0 ? _a : 'spec',
             spec: spec,
-            originalFileLocation: specFilePath,
+            originalFileLocation: openApiFilePathFromRoot,
         },
     ];
     // Process paths
-    for (const [apiPath, pathItemObject] of Object.entries((_b = spec.paths) !== null && _b !== void 0 ? _b : {})) {
-        if (!pathItemObject || typeof pathItemObject !== 'object')
+    for (const [apiPath, rawPathItem] of Object.entries((_b = spec.paths) !== null && _b !== void 0 ? _b : {})) {
+        if (!rawPathItem || typeof rawPathItem !== 'object')
             continue;
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        const pathItem = pathItemObject;
+        const pathItem = ((_c = resolvePathItemReference(rawPathItem, spec.components)) !== null && _c !== void 0 ? _c : rawPathItem);
         for (const [method, pathOperation] of getPathItemOperations(pathItem)) {
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
             const operation = pathOperation;
@@ -105,10 +105,10 @@ export function generateOpenApiPages(opts) {
             const xMint = operation['x-mint'];
             const xMintGroups = getXMintGroups(pathItem, operation);
             const tagPath = resolveTags(operation.tags);
-            const tagName = (_c = tagPath.at(-1)) === null || _c === void 0 ? void 0 : _c.name;
-            const groupName = (_d = tagPath.at(-1)) === null || _d === void 0 ? void 0 : _d.label;
-            let title = (_e = prepareStringToBeValidFilename(operation.summary)) !== null && _e !== void 0 ? _e : `${method.toLowerCase()}-${prepareStringToBeValidFilename(apiPath)}`;
-            let folder = (_f = prepareStringToBeValidFilename(tagName)) !== null && _f !== void 0 ? _f : '';
+            const tagName = (_d = tagPath.at(-1)) === null || _d === void 0 ? void 0 : _d.name;
+            const groupName = (_e = tagPath.at(-1)) === null || _e === void 0 ? void 0 : _e.label;
+            let title = (_f = prepareStringToBeValidFilename(operation.summary)) !== null && _f !== void 0 ? _f : `${method.toLowerCase()}-${prepareStringToBeValidFilename(apiPath)}`;
+            let folder = (_g = prepareStringToBeValidFilename(tagName)) !== null && _g !== void 0 ? _g : '';
             let base = posixJoin(outDir, folder, title);
             if (xMint === null || xMint === void 0 ? void 0 : xMint.href) {
                 const href = xMint.href.startsWith('/') ? xMint.href.slice(1) : xMint.href;
@@ -133,7 +133,7 @@ export function generateOpenApiPages(opts) {
             if (badge !== undefined && (xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.tag) === undefined) {
                 xMintMetadata = Object.assign(Object.assign({}, xMintMetadata), { tag: badge });
             }
-            const page = Object.assign(Object.assign({ title: (_h = (_g = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.title) !== null && _g !== void 0 ? _g : titleTag) !== null && _h !== void 0 ? _h : slugToTitle(filenameWithoutExtension), description: (_j = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.description) !== null && _j !== void 0 ? _j : description, deprecated: (_k = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.deprecated) !== null && _k !== void 0 ? _k : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method, path: apiPath, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
+            const page = Object.assign(Object.assign({ title: (_j = (_h = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.title) !== null && _h !== void 0 ? _h : titleTag) !== null && _j !== void 0 ? _j : slugToTitle(filenameWithoutExtension), description: (_k = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.description) !== null && _k !== void 0 ? _k : description, deprecated: (_l = xMintMetadata === null || xMintMetadata === void 0 ? void 0 : xMintMetadata.deprecated) !== null && _l !== void 0 ? _l : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method, path: apiPath, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
             pages.push(page);
         }
     }
@@ -147,7 +147,7 @@ export function generateOpenApiPages(opts) {
             if (!webhookObject || typeof webhookObject !== 'object')
                 continue;
             // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-            const pathItem = webhookObject;
+            const pathItem = ((_m = resolvePathItemReference(webhookObject, spec.components)) !== null && _m !== void 0 ? _m : webhookObject);
             for (const [, pathOperation] of getPathItemOperations(pathItem)) {
                 // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
                 const operation = pathOperation;
@@ -155,10 +155,10 @@ export function generateOpenApiPages(opts) {
                     continue;
                 const xMint = operation['x-mint'];
                 const tagPath = resolveTags(operation.tags);
-                const tagName = (_l = tagPath.at(-1)) === null || _l === void 0 ? void 0 : _l.name;
-                const groupName = (_m = tagPath.at(-1)) === null || _m === void 0 ? void 0 : _m.label;
-                let title = (_o = prepareStringToBeValidFilename(operation.summary)) !== null && _o !== void 0 ? _o : `${prepareStringToBeValidFilename(webhook)}`;
-                let folder = (_p = prepareStringToBeValidFilename(tagName)) !== null && _p !== void 0 ? _p : '';
+                const tagName = (_o = tagPath.at(-1)) === null || _o === void 0 ? void 0 : _o.name;
+                const groupName = (_p = tagPath.at(-1)) === null || _p === void 0 ? void 0 : _p.label;
+                let title = (_q = prepareStringToBeValidFilename(operation.summary)) !== null && _q !== void 0 ? _q : `${prepareStringToBeValidFilename(webhook)}`;
+                let folder = (_r = prepareStringToBeValidFilename(tagName)) !== null && _r !== void 0 ? _r : '';
                 let base = posixJoin(outDir, folder, title);
                 if (xMint === null || xMint === void 0 ? void 0 : xMint.href) {
                     const href = xMint.href.startsWith('/') ? xMint.href.slice(1) : xMint.href;
@@ -175,9 +175,9 @@ export function generateOpenApiPages(opts) {
                     path: webhook,
                 });
                 const badge = resolveBadge(operation.tags);
-                const xMintMetadata = badge !== undefined && ((_q = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _q === void 0 ? void 0 : _q.tag) === undefined
+                const xMintMetadata = badge !== undefined && ((_s = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _s === void 0 ? void 0 : _s.tag) === undefined
                     ? Object.assign(Object.assign({}, xMint === null || xMint === void 0 ? void 0 : xMint.metadata), { tag: badge }) : xMint === null || xMint === void 0 ? void 0 : xMint.metadata;
-                const page = Object.assign(Object.assign({ title: (_s = (_r = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _r === void 0 ? void 0 : _r.title) !== null && _s !== void 0 ? _s : slugToTitle(filenameWithoutExtension), description: (_u = (_t = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _t === void 0 ? void 0 : _t.description) !== null && _u !== void 0 ? _u : operation.description, deprecated: (_w = (_v = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _v === void 0 ? void 0 : _v.deprecated) !== null && _w !== void 0 ? _w : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method: 'webhook', path: webhook, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, isWebhook: true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
+                const page = Object.assign(Object.assign({ title: (_u = (_t = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _t === void 0 ? void 0 : _t.title) !== null && _u !== void 0 ? _u : slugToTitle(filenameWithoutExtension), description: (_w = (_v = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _v === void 0 ? void 0 : _v.description) !== null && _w !== void 0 ? _w : operation.description, deprecated: (_y = (_x = xMint === null || xMint === void 0 ? void 0 : xMint.metadata) === null || _x === void 0 ? void 0 : _x.deprecated) !== null && _y !== void 0 ? _y : operation.deprecated, openapi: openapiMetaTag, href: posixResolve('/', filenameWithoutExtension), method: 'webhook', path: webhook, tag: groupName }, (nestedTags ? { tagPath } : {})), { hidden: operation['x-hidden'] === true, isWebhook: true, xMintMetadata, xMintContent: xMint === null || xMint === void 0 ? void 0 : xMint.content, version: opts.version });
                 pages.push(page);
             }
         }

package/dist/openapi/getOpenApiOperationMethodAndEndpoint.js

@@ -1,7 +1,8 @@
-import { httpMethods, isFixedHttpMethod, parseHttpMethod } from '@mintlify/validation';
+import { httpMethods, isFixedHttpMethod, parseHttpMethod, resolvePathItemReference, } from '@mintlify/validation';
 import { findOpenApiPath } from './findOpenApiPath.js';
 import { potentiallyParseOpenApiString } from './parseOpenApiString.js';
 export const getOpenApiOperationMethodAndEndpoint = (endpointStr, openApiFiles) => {
+    var _a;
     const potentiallyParsedOpenApiString = potentiallyParseOpenApiString(endpointStr);
     if (potentiallyParsedOpenApiString == undefined) {
         return undefined;
@@ -15,7 +16,8 @@ export const getOpenApiOperationMethodAndEndpoint = (endpointStr, openApiFiles)
         const match = findOpenApiPath(openApiFile.paths, endpoint);
         const filenameMatches = !filename || filename === file.filename || filename === file.originalFileLocation;
         if (match && filenameMatches) {
-            path = match.pathItem;
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- resolved items keep the PathItemObject shape
+            path = ((_a = resolvePathItemReference(match.pathItem, 'components' in openApiFile ? openApiFile.components : undefined)) !== null && _a !== void 0 ? _a : match.pathItem);
             apiFile = openApiFile;
             matchedEndpoint = match.pathKey;
         }

package/dist/openapi/headerNames.d.ts

@@ -0,0 +1,3 @@
+import type { PathItemSources } from './pathItems.js';
+import type { OpenApiValidateError } from './validate.js';
+export declare const validateHeaderNames: (document: PathItemSources) => OpenApiValidateError[];

package/dist/openapi/headerNames.js

@@ -0,0 +1,25 @@
+import { forEachDocumentPosition } from './documentPositions.js';
+// RFC 9110 field names are tokens: letters, digits and these symbols, nothing else
+const TOKEN_SYMBOLS = new Set("!#$%&'*+-.^_`|~");
+const isTokenChar = (char) => (char >= 'a' && char <= 'z') ||
+    (char >= 'A' && char <= 'Z') ||
+    (char >= '0' && char <= '9') ||
+    TOKEN_SYMBOLS.has(char);
+const isValidHeaderName = (name) => typeof name === 'string' && name.length > 0 && [...name].every(isTokenChar);
+export const validateHeaderNames = (document) => {
+    const errors = [];
+    const report = (path, name) => errors.push({ path, message: `Header name ${name} is not a valid HTTP field name` });
+    forEachDocumentPosition(document, {
+        onParameter: (path, parameter) => {
+            if (parameter.in === 'header' && typeof parameter.name === 'string') {
+                if (!isValidHeaderName(parameter.name))
+                    report(`${path}/name`, parameter.name);
+            }
+        },
+        onHeaderName: (path, name) => {
+            if (!isValidHeaderName(name))
+                report(path, name);
+        },
+    });
+    return errors;
+};

package/dist/openapi/pathItems.d.ts

@@ -0,0 +1,7 @@
+import { type HttpMethod, type OpenAPIV3_2 } from '@mintlify/validation';
+export type PathItemSources = Partial<Pick<OpenAPIV3_2.Document, 'paths' | 'webhooks' | 'components'>>;
+export type PathItemLike = OpenAPIV3_2.PathItemObject | OpenAPIV3_2.ReferenceObject;
+export declare const escapePointer: (segment: string) => string;
+export declare const operationPointer: (method: HttpMethod) => string;
+export declare const resolvePathItem: (pathItem: PathItemLike, components: OpenAPIV3_2.ComponentsObject | undefined, seen?: Set<string>) => OpenAPIV3_2.PathItemObject;
+export declare const forEachPathItem: (document: PathItemSources, visit: (location: string, pathItem: OpenAPIV3_2.PathItemObject) => void) => void;