@scalar/openapi-parser 0.25.3 → 0.25.5

package/dist/utils/transform/sanitize.js

@@ -1,23 +1,23 @@
-import { addInfoObject } from "./utils/addInfoObject.js";
-import { addLatestOpenApiVersion } from "./utils/addLatestOpenApiVersion.js";
-import { addMissingTags } from "./utils/addMissingTags.js";
-import { normalizeSecuritySchemes } from "./utils/normalizeSecuritySchemes.js";
-import { rejectSwaggerDocuments } from "./utils/rejectSwaggerDocuments.js";
-import { DEFAULT_TITLE } from "./utils/addInfoObject.js";
-import { DEFAULT_OPENAPI_VERSION } from "./utils/addLatestOpenApiVersion.js";
-function sanitize(definition) {
-  const transformers = [
-    rejectSwaggerDocuments,
-    addLatestOpenApiVersion,
-    addInfoObject,
-    addMissingTags,
-    normalizeSecuritySchemes
-  ];
-  return transformers.reduce((doc, transformer) => transformer(doc), definition);
+import { addInfoObject } from './utils/addInfoObject.js';
+import { addLatestOpenApiVersion } from './utils/addLatestOpenApiVersion.js';
+import { addMissingTags } from './utils/addMissingTags.js';
+import { normalizeSecuritySchemes } from './utils/normalizeSecuritySchemes.js';
+import { rejectSwaggerDocuments } from './utils/rejectSwaggerDocuments.js';
+// biome-ignore lint/performance/noBarrelFile: re-exports utilities
+export { DEFAULT_TITLE } from './utils/addInfoObject.js';
+export { DEFAULT_OPENAPI_VERSION } from './utils/addLatestOpenApiVersion.js';
+/**
+ * Make an OpenAPI document a valid and clean OpenAPI document
+ *
+ * @deprecated We're about to drop this from the package.
+ */
+export function sanitize(definition) {
+    const transformers = [
+        rejectSwaggerDocuments,
+        addLatestOpenApiVersion,
+        addInfoObject,
+        addMissingTags,
+        normalizeSecuritySchemes,
+    ];
+    return transformers.reduce((doc, transformer) => transformer(doc), definition);
 }
-export {
-  DEFAULT_OPENAPI_VERSION,
-  DEFAULT_TITLE,
-  sanitize
-};
-//# sourceMappingURL=sanitize.js.map

package/dist/utils/transform/utils/addInfoObject.js

@@ -1,15 +1,10 @@
-const DEFAULT_TITLE = "API";
-const DEFAULT_VERSION = "1.0";
-const addInfoObject = (definition) => ({
-  ...definition,
-  info: {
-    ...definition.info,
-    title: definition.info?.title ?? DEFAULT_TITLE,
-    version: definition.info?.version ?? DEFAULT_VERSION
-  }
+export const DEFAULT_TITLE = 'API';
+const DEFAULT_VERSION = '1.0';
+export const addInfoObject = (definition) => ({
+    ...definition,
+    info: {
+        ...definition.info,
+        title: definition.info?.title ?? DEFAULT_TITLE,
+        version: definition.info?.version ?? DEFAULT_VERSION,
+    },
 });
-export {
-  DEFAULT_TITLE,
-  addInfoObject
-};
-//# sourceMappingURL=addInfoObject.js.map

package/dist/utils/transform/utils/addLatestOpenApiVersion.js

@@ -1,10 +1,5 @@
-const DEFAULT_OPENAPI_VERSION = "3.1.1";
-const addLatestOpenApiVersion = (definition) => ({
-  openapi: definition.openapi ?? DEFAULT_OPENAPI_VERSION,
-  ...definition
+export const DEFAULT_OPENAPI_VERSION = '3.1.1';
+export const addLatestOpenApiVersion = (definition) => ({
+    openapi: definition.openapi ?? DEFAULT_OPENAPI_VERSION,
+    ...definition,
 });
-export {
-  DEFAULT_OPENAPI_VERSION,
-  addLatestOpenApiVersion
-};
-//# sourceMappingURL=addLatestOpenApiVersion.js.map

package/dist/utils/transform/utils/addMissingTags.js

@@ -1,30 +1,29 @@
-const addMissingTags = (definition) => {
-  if (!definition.paths) {
-    return definition;
-  }
-  const usedTags = /* @__PURE__ */ new Set();
-  for (const path of Object.values(definition.paths)) {
-    if (typeof path === "object" && path !== null) {
-      for (const operation of Object.values(path)) {
-        if (typeof operation === "object" && operation !== null && "tags" in operation) {
-          const tags = operation.tags;
-          if (Array.isArray(tags)) {
-            tags.forEach((tag) => usedTags.add(String(tag)));
-          }
+export const addMissingTags = (definition) => {
+    if (!definition.paths) {
+        return definition;
+    }
+    // Collect all unique tags used in operations
+    const usedTags = new Set();
+    for (const path of Object.values(definition.paths)) {
+        if (typeof path === 'object' && path !== null) {
+            for (const operation of Object.values(path)) {
+                if (typeof operation === 'object' && operation !== null && 'tags' in operation) {
+                    const tags = operation.tags;
+                    if (Array.isArray(tags)) {
+                        tags.forEach((tag) => usedTags.add(String(tag)));
+                    }
+                }
+            }
         }
-      }
     }
-  }
-  const existingTags = new Set(
-    (Array.isArray(definition.tags) ? definition.tags : []).map((tag) => typeof tag === "object" && tag !== null ? String(tag.name) : null).filter(Boolean)
-  );
-  const missingTags = [...usedTags].filter((tag) => !existingTags.has(tag)).map((name) => ({ name }));
-  return {
-    ...definition,
-    tags: [...Array.isArray(definition.tags) ? definition.tags : [], ...missingTags]
-  };
-};
-export {
-  addMissingTags
+    // Convert tags to array of tag objects if not already present
+    const existingTags = new Set((Array.isArray(definition.tags) ? definition.tags : [])
+        .map((tag) => (typeof tag === 'object' && tag !== null ? String(tag.name) : null))
+        .filter(Boolean));
+    // Add missing tags
+    const missingTags = [...usedTags].filter((tag) => !existingTags.has(tag)).map((name) => ({ name }));
+    return {
+        ...definition,
+        tags: [...(Array.isArray(definition.tags) ? definition.tags : []), ...missingTags],
+    };
 };
-//# sourceMappingURL=addMissingTags.js.map

package/dist/utils/transform/utils/normalizeSecuritySchemes.js

@@ -1,42 +1,44 @@
-const normalizeSecuritySchemes = (definition) => {
-  if (!definition.components?.securitySchemes) {
-    return definition;
-  }
-  const securitySchemes = { ...definition.components.securitySchemes };
-  for (const scheme of Object.values(securitySchemes)) {
-    if (typeof scheme === "object" && scheme !== null && "type" in scheme) {
-      const type = String(scheme.type).toLowerCase();
-      scheme.type = {
-        apikey: "apiKey",
-        oauth2: "oauth2",
-        http: "http",
-        mutualtls: "mutualTLS",
-        openidconnect: "openIdConnect"
-      }[type] ?? type;
+export const normalizeSecuritySchemes = (definition) => {
+    if (!definition.components?.securitySchemes) {
+        return definition;
     }
-  }
-  for (const scheme of Object.values(securitySchemes)) {
-    if (typeof scheme === "object" && scheme !== null && "type" in scheme && scheme.type === "oauth2" && "flows" in scheme) {
-      const flows = scheme.flows;
-      for (const flow of Object.values(flows)) {
-        if (typeof flow === "object" && flow !== null && "scopes" in flow && Array.isArray(flow.scopes)) {
-          flow.scopes = flow.scopes.reduce((acc, scope) => {
-            acc[scope] = "";
-            return acc;
-          }, {});
+    const securitySchemes = { ...definition.components.securitySchemes };
+    for (const scheme of Object.values(securitySchemes)) {
+        if (typeof scheme === 'object' && scheme !== null && 'type' in scheme) {
+            const type = String(scheme.type).toLowerCase();
+            scheme.type =
+                {
+                    apikey: 'apiKey',
+                    oauth2: 'oauth2',
+                    http: 'http',
+                    mutualtls: 'mutualTLS',
+                    openidconnect: 'openIdConnect',
+                }[type] ?? type;
         }
-      }
     }
-  }
-  return {
-    ...definition,
-    components: {
-      ...definition.components,
-      securitySchemes
+    // Convert array scopes to objects
+    for (const scheme of Object.values(securitySchemes)) {
+        if (typeof scheme === 'object' &&
+            scheme !== null &&
+            'type' in scheme &&
+            scheme.type === 'oauth2' &&
+            'flows' in scheme) {
+            const flows = scheme.flows;
+            for (const flow of Object.values(flows)) {
+                if (typeof flow === 'object' && flow !== null && 'scopes' in flow && Array.isArray(flow.scopes)) {
+                    flow.scopes = flow.scopes.reduce((acc, scope) => {
+                        acc[scope] = '';
+                        return acc;
+                    }, {});
+                }
+            }
+        }
     }
-  };
-};
-export {
-  normalizeSecuritySchemes
+    return {
+        ...definition,
+        components: {
+            ...definition.components,
+            securitySchemes,
+        },
+    };
 };
-//# sourceMappingURL=normalizeSecuritySchemes.js.map

package/dist/utils/transform/utils/rejectSwaggerDocuments.js

@@ -1,10 +1,6 @@
-const rejectSwaggerDocuments = (defintion) => {
-  if ("swagger" in defintion) {
-    throw new Error("Swagger 2.0 documents are not supported. Please upgrade to OpenAPI 3.x.");
-  }
-  return defintion;
+export const rejectSwaggerDocuments = (defintion) => {
+    if ('swagger' in defintion) {
+        throw new Error('Swagger 2.0 documents are not supported. Please upgrade to OpenAPI 3.x.');
+    }
+    return defintion;
 };
-export {
-  rejectSwaggerDocuments
-};
-//# sourceMappingURL=rejectSwaggerDocuments.js.map

package/dist/utils/transform-errors.js

@@ -1,58 +1,65 @@
-import { betterAjvErrors } from "./betterAjvErrors/index.js";
-function transformErrors(specification, errors) {
-  if (typeof errors === "string") {
-    return [
-      {
-        message: errors
-      }
-    ];
-  }
-  if (!specification || typeof specification !== "object") {
-    return [
-      {
-        message: "Invalid specification"
-      }
-    ];
-  }
-  let processedErrors;
-  try {
-    processedErrors = betterAjvErrors(specification, null, errors, {
-      indent: 2
-    }).map((error) => {
-      error.message = error.message.trim();
-      return error;
-    });
-  } catch (error) {
-    console.error(error);
-    if (Array.isArray(errors)) {
-      return errors.map((err) => {
-        let message = err.message || "Validation error";
-        if (err.keyword === "additionalProperties" && err.params?.additionalProperty) {
-          message = `Property ${err.params.additionalProperty} is not expected to be here`;
-        }
-        return {
-          message,
-          path: err.dataPath || err.instancePath
-        };
-      });
+import { betterAjvErrors } from './betterAjvErrors/index.js';
+/**
+ * Transforms ajv errors, finds the positions in the schema and returns an enriched format.
+ */
+export function transformErrors(specification, errors) {
+    // TODO: This should work with multiple files
+    if (typeof errors === 'string') {
+        return [
+            {
+                message: errors,
+            },
+        ];
     }
-    return [
-      {
-        message: "Validation failed"
-      }
-    ];
-  }
-  const seen = /* @__PURE__ */ new Set();
-  return processedErrors.filter((error) => {
-    const key = `${error.message}||${error.path}`;
-    if (seen.has(key)) {
-      return false;
+    // If specification is null or invalid, betterAjvErrors cannot process it
+    // This can happen when reference resolution fails
+    if (!specification || typeof specification !== 'object') {
+        return [
+            {
+                message: 'Invalid specification',
+            },
+        ];
     }
-    seen.add(key);
-    return true;
-  });
+    // Wrap betterAjvErrors in a try-catch since it can fail with malformed schemas
+    let processedErrors;
+    try {
+        processedErrors = betterAjvErrors(specification, null, errors, {
+            indent: 2,
+        }).map((error) => {
+            error.message = error.message.trim();
+            return error;
+        });
+    }
+    catch (error) {
+        console.error(error);
+        // If betterAjvErrors fails, fall back to raw AJV errors
+        if (Array.isArray(errors)) {
+            return errors.map((err) => {
+                let message = err.message || 'Validation error';
+                // For additionalProperties errors, include the property name
+                if (err.keyword === 'additionalProperties' && err.params?.additionalProperty) {
+                    message = `Property ${err.params.additionalProperty} is not expected to be here`;
+                }
+                return {
+                    message,
+                    path: err.dataPath || err.instancePath,
+                };
+            });
+        }
+        return [
+            {
+                message: 'Validation failed',
+            },
+        ];
+    }
+    // Deduplicate errors with the same message and path
+    const seen = new Set();
+    return processedErrors.filter((error) => {
+        const key = `${error.message}||${error.path}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
 }
-export {
-  transformErrors
-};
-//# sourceMappingURL=transform-errors.js.map

package/dist/utils/traverse.js

@@ -1,25 +1,24 @@
-function traverse(content, transform, path = []) {
-  const result = {};
-  for (const [key, value] of Object.entries(content)) {
-    const currentPath = [...path, key];
-    if (Array.isArray(value)) {
-      result[key] = value.map((item, index) => {
-        if (typeof item === "object" && !Array.isArray(item) && item !== null) {
-          return traverse(item, transform, [...currentPath, index.toString()]);
+/**
+ * Recursively traverses the content and applies the transform function to each node.
+ */
+export function traverse(content, transform, path = []) {
+    const result = {};
+    for (const [key, value] of Object.entries(content)) {
+        const currentPath = [...path, key];
+        if (Array.isArray(value)) {
+            result[key] = value.map((item, index) => {
+                if (typeof item === 'object' && !Array.isArray(item) && item !== null) {
+                    return traverse(item, transform, [...currentPath, index.toString()]);
+                }
+                return item;
+            });
+            continue;
         }
-        return item;
-      });
-      continue;
-    }
-    if (typeof value === "object" && value !== null) {
-      result[key] = traverse(value, transform, currentPath);
-      continue;
+        if (typeof value === 'object' && value !== null) {
+            result[key] = traverse(value, transform, currentPath);
+            continue;
+        }
+        result[key] = value;
     }
-    result[key] = value;
-  }
-  return transform(result, path);
+    return transform(result, path);
 }
-export {
-  traverse
-};
-//# sourceMappingURL=traverse.js.map

package/dist/utils/unescape-json-pointer.js

@@ -1,7 +1,9 @@
-function unescapeJsonPointer(uri) {
-  return decodeURI(uri.replace(/~1/g, "/").replace(/~0/g, "~"));
+/**
+ * Unescape JSON pointer
+ *
+ * Examples:
+ * /foo~1bar~0baz -> /foo/bar~baz
+ */
+export function unescapeJsonPointer(uri) {
+    return decodeURI(uri.replace(/~1/g, '/').replace(/~0/g, '~'));
 }
-export {
-  unescapeJsonPointer
-};
-//# sourceMappingURL=unescape-json-pointer.js.map

package/dist/utils/upgrade.js

@@ -1,25 +1,22 @@
-import { upgrade as originalUpgrade } from "@scalar/openapi-upgrader";
-import { getEntrypoint } from "./get-entrypoint.js";
-import { isFilesystem } from "./is-filesystem.js";
-import { normalize } from "./normalize.js";
-function upgrade(value) {
-  if (!value) {
+import { upgrade as originalUpgrade } from '@scalar/openapi-upgrader';
+import { getEntrypoint } from './get-entrypoint.js';
+import { isFilesystem } from './is-filesystem.js';
+import { normalize } from './normalize.js';
+/**
+ * Upgrade specification to OpenAPI 3.1.0
+ */
+export function upgrade(value) {
+    if (!value) {
+        return {
+            specification: null,
+            version: '3.1',
+        };
+    }
+    // TODO: Run upgrade over the whole filesystem
+    const document = originalUpgrade(isFilesystem(value) ? getEntrypoint(value).specification : normalize(value), '3.1');
     return {
-      specification: null,
-      version: "3.1"
+        specification: document,
+        // TODO: Make dynamic
+        version: '3.1',
     };
-  }
-  const document = originalUpgrade(
-    isFilesystem(value) ? getEntrypoint(value).specification : normalize(value),
-    "3.1"
-  );
-  return {
-    specification: document,
-    // TODO: Make dynamic
-    version: "3.1"
-  };
 }
-export {
-  upgrade
-};
-//# sourceMappingURL=upgrade.js.map

package/dist/utils/validate-path-parameters.d.ts

@@ -0,0 +1,6 @@
+import type { AnyObject, ErrorObject } from '../types/index.js';
+/**
+ * Validates path-template semantics that are not enforced by the JSON schema.
+ */
+export declare function validatePathParameters(specification: AnyObject): ErrorObject[];
+//# sourceMappingURL=validate-path-parameters.d.ts.map

package/dist/utils/validate-path-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-path-parameters.d.ts","sourceRoot":"","sources":["../../src/utils/validate-path-parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAU3D;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,SAAS,GAAG,WAAW,EAAE,CAoE9E"}

package/dist/utils/validate-path-parameters.js

@@ -0,0 +1,91 @@
+const OPERATION_KEYS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+const PATH_PARAMETER_PATTERN = /{([^}]+)}/g;
+/**
+ * Validates path-template semantics that are not enforced by the JSON schema.
+ */
+export function validatePathParameters(specification) {
+    const paths = specification?.paths;
+    if (!paths || typeof paths !== 'object') {
+        return [];
+    }
+    const errors = [];
+    for (const [pathName, pathItem] of Object.entries(paths)) {
+        if (!isRecord(pathItem)) {
+            continue;
+        }
+        const operations = Object.entries(pathItem).filter(([key, value]) => OPERATION_KEYS.has(key) && isRecord(value));
+        // Preserve the repo's current behaviour for empty path items.
+        if (operations.length === 0) {
+            continue;
+        }
+        const templateParameters = new Set(getTemplateParameterNames(pathName));
+        const pathLevelParameters = getPathParameters(pathItem.parameters, ['paths', pathName, 'parameters']);
+        for (const parameter of pathLevelParameters) {
+            if (!templateParameters.has(parameter.name)) {
+                errors.push({
+                    path: parameter.path,
+                    message: `Path parameter "${parameter.name}" must have the corresponding {${parameter.name}} segment in the "${pathName}" path`,
+                });
+            }
+        }
+        for (const [operationKey, operation] of operations) {
+            const operationParameters = getPathParameters(operation.parameters, [
+                'paths',
+                pathName,
+                operationKey,
+                'parameters',
+            ]);
+            for (const parameter of operationParameters) {
+                if (!templateParameters.has(parameter.name)) {
+                    errors.push({
+                        path: parameter.path,
+                        message: `Path parameter "${parameter.name}" must have the corresponding {${parameter.name}} segment in the "${pathName}" path`,
+                    });
+                }
+            }
+            const effectiveParameters = new Set([...pathLevelParameters, ...operationParameters].map((parameter) => parameter.name));
+            for (const templateParameter of templateParameters) {
+                if (!effectiveParameters.has(templateParameter)) {
+                    errors.push({
+                        path: ['paths', pathName, operationKey],
+                        message: `Declared path parameter "${templateParameter}" needs to be defined as a path parameter at either the path or operation level`,
+                    });
+                }
+            }
+        }
+    }
+    return deduplicateErrors(errors);
+}
+function getTemplateParameterNames(pathName) {
+    return [...pathName.matchAll(PATH_PARAMETER_PATTERN)].map((match) => match[1]);
+}
+function getPathParameters(parameters, pathPrefix) {
+    if (!Array.isArray(parameters)) {
+        return [];
+    }
+    return parameters.flatMap((parameter, index) => {
+        if (!isRecord(parameter) || parameter.in !== 'path' || typeof parameter.name !== 'string') {
+            return [];
+        }
+        return [
+            {
+                name: parameter.name,
+                path: [...pathPrefix, String(index), 'name'],
+            },
+        ];
+    });
+}
+function deduplicateErrors(errors) {
+    const seen = new Set();
+    return errors.filter((error) => {
+        const key = `${error.message}||${error.path?.join('.') ?? ''}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/utils/validate.js

@@ -1,20 +1,24 @@
-import { Validator } from "../lib/Validator/Validator.js";
-import { makeFilesystem } from "./make-filesystem.js";
-function validate(value, options) {
-  try {
-    const filesystem = makeFilesystem(value);
-    const validator = new Validator();
-    const result = validator.validate(filesystem, options);
-    return Promise.resolve({
-      ...result,
-      specification: validator.specification,
-      version: validator.version
-    });
-  } catch (err) {
-    return Promise.reject(err);
-  }
+import { Validator } from '../lib/Validator/Validator.js';
+import { makeFilesystem } from './make-filesystem.js';
+/**
+ * Validates an OpenAPI document
+ */
+export function validate(value, options) {
+    try {
+        const filesystem = makeFilesystem(value);
+        const validator = new Validator();
+        const result = validator.validate(filesystem, options);
+        /**
+         * Currently contains no asynchronous logic, but returns a Promise
+         * to preserve API compatibility and allow async logic in the future.
+         */
+        return Promise.resolve({
+            ...result,
+            specification: validator.specification,
+            version: validator.version,
+        });
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
 }
-export {
-  validate
-};
-//# sourceMappingURL=validate.js.map