@scalar/openapi-parser 0.8.9 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/openapi-parser
 
+## 0.9.0
+
+### Minor Changes
+
+- 6fef2f3: feat(openapi-parser): support `onDereference` option on `dereference`
+
+## 0.8.10
+
+### Patch Changes
+
+- 98e9cb2: feat: new `sanitize` utility to make documents OpenAPI-compliant
+
 ## 0.8.9
 
 ### Patch Changes

package/README.md

@@ -63,7 +63,21 @@ const specification = `{
 const { schema, errors } = await dereference(specification)
 ```
 
-### Modify an OpenAPI specification
+### Track references
+
+The `dereference` function accepts an `onDereference` callback option that gets called whenever a reference is resolved. This can be useful for tracking which schemas are being dereferenced:
+
+```ts
+import { dereference } from '@scalar/openapi-parser'
+
+const { schema, errors } = await dereference(specification, {
+  onDereference: ({ schema, ref }) => {
+    //
+  },
+})
+```
+
+### Modify an OpenAPI document
 
 ```ts
 import { filter } from '@scalar/openapi-parser'
@@ -80,9 +94,9 @@ const specification = `{
 const { specification } = filter(specification, (schema) => !schema?.['x-internal'])
 ```
 
-### Upgrade your OpenAPI specification
+### Upgrade your OpenAPI document
 
-There’s an `upgrade` command to upgrade all your OpenAPI specifications to the latest OpenAPI version.
+There’s an `upgrade` command to upgrade all your OpenAPI documents to the latest OpenAPI version.
 
 > ⚠️ The upgrade from Swagger 2.0 is still experimental and probably lacks features.
 
@@ -102,6 +116,29 @@ console.log(specification.openapi)
 // Output: 3.1.0
 ```
 
+### Sanitize your OpenAPI document
+
+The `sanitize()` utility helps ensure your OpenAPI document is valid and complete.
+It automatically adds any missing required properties like the OpenAPI version and info object, collects operation tags
+and adds them to the global tags array and normalizes security scheme types.
+
+This makes your document as OpenAPI-compliant as possible with minimal effort, handling many common specification
+requirements automatically.
+
+> ⚠️ This doesn’t support Swagger 2.0 documents.
+
+```ts
+import { sanitize } from '@scalar/openapi-parser'
+
+const result = sanitize({
+  info: {
+    title: 'Hello World',
+  },
+})
+
+console.log(result)
+```
+
 ### Pipeline syntax
 
 ```ts

package/dist/index.js

@@ -24,3 +24,6 @@ export { upgrade } from './utils/upgrade.js';
 export { isSchemaPath, upgradeFromThreeToThreeOne } from './utils/upgradeFromThreeToThreeOne.js';
 export { upgradeFromTwoToThree } from './utils/upgradeFromTwoToThree.js';
 export { validate } from './utils/validate.js';
+export { DEFAULT_OPENAPI_VERSION } from './utils/transform/utils/addLatestOpenApiVersion.js';
+export { DEFAULT_TITLE, DEFAULT_VERSION } from './utils/transform/utils/addInfoObject.js';
+export { sanitize } from './utils/transform/sanitize.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/dereference.d.ts

@@ -1,7 +1,8 @@
-import type { AnyApiDefinitionFormat, DereferenceResult, Filesystem, ThrowOnErrorOption } from '../types';
-export type DereferenceOptions = ThrowOnErrorOption;
+import type { AnyApiDefinitionFormat, DereferenceResult, Filesystem } from '../types';
+import { type ResolveReferencesOptions } from './resolveReferences.js';
+export type DereferenceOptions = ResolveReferencesOptions;
 /**
- * Validates an OpenAPI schema and resolves all references.
+ * Resolves all references in an OpenAPI document
  */
 export declare function dereference(value: AnyApiDefinitionFormat | Filesystem, options?: DereferenceOptions): Promise<DereferenceResult>;
 //# sourceMappingURL=dereference.d.ts.map

package/dist/utils/dereference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dereference.d.ts","sourceRoot":"","sources":["../../src/utils/dereference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EAEtB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAMjB,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAA;AAEnD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,sBAAsB,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAY5B"}
+{"version":3,"file":"dereference.d.ts","sourceRoot":"","sources":["../../src/utils/dereference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACX,MAAM,UAAU,CAAA;AAIjB,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,qBAAqB,CAAA;AAE5B,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAA;AAEzD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,sBAAsB,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAY5B"}

package/dist/utils/dereference.js

@@ -4,7 +4,7 @@ import { makeFilesystem } from './makeFilesystem.js';
 import { resolveReferences } from './resolveReferences.js';
 
 /**
- * Validates an OpenAPI schema and resolves all references.
+ * Resolves all references in an OpenAPI document
  */
 async function dereference(value, options) {
     const filesystem = makeFilesystem(value);

package/dist/utils/details.d.ts

@@ -1,6 +1,6 @@
 import type { AnyObject, DetailsResult } from '../types';
 /**
- * Get versions of the OpenAPI specification.
+ * Get versions of the OpenAPI document.
  */
 export declare function details(specification: AnyObject): DetailsResult;
 //# sourceMappingURL=details.d.ts.map

package/dist/utils/details.js

@@ -1,7 +1,7 @@
 import { OpenApiVersions } from '../configuration/index.js';
 
 /**
- * Get versions of the OpenAPI specification.
+ * Get versions of the OpenAPI document.
  */
 function details(specification) {
     for (const version of new Set(OpenApiVersions)) {

package/dist/utils/index.d.ts

@@ -23,4 +23,5 @@ export * from './upgrade.js';
 export * from './upgradeFromThreeToThreeOne.js';
 export * from './upgradeFromTwoToThree.js';
 export * from './validate.js';
+export * from './transform';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,qBAAqB,CAAA;AACnC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,qBAAqB,CAAA;AACnC,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,uBAAuB,CAAA;AACrC,cAAc,WAAW,CAAA;AACzB,cAAc,8BAA8B,CAAA;AAC5C,cAAc,yBAAyB,CAAA;AACvC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,qBAAqB,CAAA;AACnC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,qBAAqB,CAAA;AACnC,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,uBAAuB,CAAA;AACrC,cAAc,WAAW,CAAA;AACzB,cAAc,8BAA8B,CAAA;AAC5C,cAAc,yBAAyB,CAAA;AACvC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/dist/utils/normalize.d.ts

@@ -1,7 +1,8 @@
 import type { AnyObject, Filesystem } from '../types';
 /**
- * Normalize the OpenAPI specification to a JavaScript object.
- * Don’t touch the object if it’s a `Filesystem` (multiple files).
+ * Normalize the OpenAPI document (YAML, JSON, object) to a JavaScript object.
+ *
+ * Doesn’t modify the object if it’s a `Filesystem` (multiple files) already.
  */
 export declare function normalize(specification: string | AnyObject | Filesystem): AnyObject | Filesystem;
 //# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAGrD;;;GAGG;AACH,wBAAgB,SAAS,CACvB,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAC7C,SAAS,GAAG,UAAU,CAgBxB"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAGrD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAC7C,SAAS,GAAG,UAAU,CAgBxB"}

package/dist/utils/normalize.js

@@ -2,8 +2,9 @@ import { parse } from 'yaml';
 import { isFilesystem } from './isFilesystem.js';
 
 /**
- * Normalize the OpenAPI specification to a JavaScript object.
- * Don’t touch the object if it’s a `Filesystem` (multiple files).
+ * Normalize the OpenAPI document (YAML, JSON, object) to a JavaScript object.
+ *
+ * Doesn’t modify the object if it’s a `Filesystem` (multiple files) already.
  */
 function normalize(specification) {
     if (isFilesystem(specification)) {

package/dist/utils/resolveReferences.d.ts

@@ -5,8 +5,14 @@ export type ResolveReferencesResult = {
     errors: ErrorObject[];
     schema: OpenAPI.Document;
 };
+export type ResolveReferencesOptions = ThrowOnErrorOption & {
+    onDereference?: (data: {
+        schema: AnyObject;
+        ref: string;
+    }) => void;
+};
 /**
  * Takes a specification and resolves all references.
  */
-export declare function resolveReferences(input: AnyObject | Filesystem, options?: ThrowOnErrorOption, file?: FilesystemEntry, errors?: ErrorObject[]): ResolveReferencesResult;
+export declare function resolveReferences(input: AnyObject | Filesystem, options?: ResolveReferencesOptions, file?: FilesystemEntry, errors?: ErrorObject[]): ResolveReferencesResult;
 //# sourceMappingURL=resolveReferences.d.ts.map

package/dist/utils/resolveReferences.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveReferences.d.ts","sourceRoot":"","sources":["../../src/utils/resolveReferences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAGpD,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAejB,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAA;CACzB,CAAA;AAOD;;GAEG;AACH,wBAAgB,iBAAiB,CAE/B,KAAK,EAAE,SAAS,GAAG,UAAU,EAE7B,OAAO,CAAC,EAAE,kBAAkB,EAE5B,IAAI,CAAC,EAAE,eAAe,EAEtB,MAAM,CAAC,EAAE,WAAW,EAAE,GACrB,uBAAuB,CA+FzB"}
+{"version":3,"file":"resolveReferences.d.ts","sourceRoot":"","sources":["../../src/utils/resolveReferences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAGpD,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAejB,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG;IAC1D,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACnE,CAAA;AAOD;;GAEG;AACH,wBAAgB,iBAAiB,CAE/B,KAAK,EAAE,SAAS,GAAG,UAAU,EAE7B,OAAO,CAAC,EAAE,wBAAwB,EAElC,IAAI,CAAC,EAAE,eAAe,EAEtB,MAAM,CAAC,EAAE,WAAW,EAAE,GACrB,uBAAuB,CAoGzB"}

package/dist/utils/resolveReferences.js

@@ -26,10 +26,10 @@ errors) {
     // Get the main file
     const entrypoint = getEntrypoint(filesystem);
     // Recursively resolve all references
-    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint);
+    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint, options?.onDereference);
     // If we replace references with content, that includes a reference, we can’t deal with that right-away.
     // That’s why we need a second run.
-    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint);
+    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint, options?.onDereference);
     // Remove duplicats (according to message) from errors
     errors = errors.filter((error, index, self) => index ===
         self.findIndex((t) => t.message === error.message && t.code === error.code));
@@ -43,7 +43,7 @@ errors) {
     /**
      * Resolves the circular reference to an object and deletes the $ref properties.
      */
-    function resolve(schema, resolveFilesystem, resolveFile) {
+    function resolve(schema, resolveFilesystem, resolveFile, onResolve) {
         let result;
         // Iterate over the whole objecct
         Object.entries(schema ?? {}).forEach(([_, value]) => {
@@ -54,6 +54,7 @@ errors) {
                 if (target === undefined) {
                     return undefined;
                 }
+                onResolve?.({ schema, ref: schema.$ref });
                 // Get rid of the reference
                 delete schema.$ref;
                 if (typeof target === 'object') {
@@ -65,7 +66,7 @@ errors) {
                 }
             }
             if (typeof value === 'object' && !isCircular(value)) {
-                result = resolve(value, resolveFilesystem, resolveFile);
+                result = resolve(value, resolveFilesystem, resolveFile, onResolve);
             }
         });
         return {

package/dist/utils/transform/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sanitize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/transform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/transform/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/dist/utils/transform/sanitize.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAPI } from '@scalar/openapi-types';
+import type { AnyObject } from '../../types';
+export { DEFAULT_OPENAPI_VERSION } from './utils/addLatestOpenApiVersion.js';
+export { DEFAULT_TITLE, DEFAULT_VERSION } from './utils/addInfoObject.js';
+/**
+ * Make an OpenAPI document a valid and clean OpenAPI document
+ */
+export declare function sanitize(definition: AnyObject): OpenAPI.Document;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/utils/transform/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/utils/transform/sanitize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAO5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AACzE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEtE;;GAEG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAUhE"}

package/dist/utils/transform/sanitize.js

@@ -0,0 +1,23 @@
+import { addInfoObject } from './utils/addInfoObject.js';
+export { DEFAULT_TITLE, DEFAULT_VERSION } from './utils/addInfoObject.js';
+import { addLatestOpenApiVersion } from './utils/addLatestOpenApiVersion.js';
+export { DEFAULT_OPENAPI_VERSION } from './utils/addLatestOpenApiVersion.js';
+import { addMissingTags } from './utils/addMissingTags.js';
+import { normalizeSecuritySchemes } from './utils/normalizeSecuritySchemes.js';
+import { rejectSwaggerDocuments } from './utils/rejectSwaggerDocuments.js';
+
+/**
+ * Make an OpenAPI document a valid and clean OpenAPI document
+ */
+function sanitize(definition) {
+    const transformers = [
+        rejectSwaggerDocuments,
+        addLatestOpenApiVersion,
+        addInfoObject,
+        addMissingTags,
+        normalizeSecuritySchemes,
+    ];
+    return transformers.reduce((doc, transformer) => transformer(doc), definition);
+}
+
+export { sanitize };

package/dist/utils/transform/utils/addInfoObject.d.ts

@@ -0,0 +1,7 @@
+import type { AnyObject } from '../../../types';
+export declare const DEFAULT_TITLE = "API";
+export declare const DEFAULT_VERSION = "1.0";
+export declare const addInfoObject: (definition: AnyObject) => {
+    info: any;
+};
+//# sourceMappingURL=addInfoObject.d.ts.map

package/dist/utils/transform/utils/addInfoObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addInfoObject.d.ts","sourceRoot":"","sources":["../../../../src/utils/transform/utils/addInfoObject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,eAAO,MAAM,aAAa,QAAQ,CAAA;AAClC,eAAO,MAAM,eAAe,QAAQ,CAAA;AAEpC,eAAO,MAAM,aAAa,eAAgB,SAAS;;CAOjD,CAAA"}

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

@@ -0,0 +1,12 @@
+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 { DEFAULT_TITLE, DEFAULT_VERSION, addInfoObject };

package/dist/utils/transform/utils/addLatestOpenApiVersion.d.ts

@@ -0,0 +1,6 @@
+import type { AnyObject } from '../../../types';
+export declare const DEFAULT_OPENAPI_VERSION = "3.1.1";
+export declare const addLatestOpenApiVersion: (definition: AnyObject) => {
+    openapi: any;
+};
+//# sourceMappingURL=addLatestOpenApiVersion.d.ts.map

package/dist/utils/transform/utils/addLatestOpenApiVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addLatestOpenApiVersion.d.ts","sourceRoot":"","sources":["../../../../src/utils/transform/utils/addLatestOpenApiVersion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,eAAO,MAAM,uBAAuB,UAAU,CAAA;AAE9C,eAAO,MAAM,uBAAuB,eAAgB,SAAS;;CAG3D,CAAA"}

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

@@ -0,0 +1,7 @@
+const DEFAULT_OPENAPI_VERSION = '3.1.1';
+const addLatestOpenApiVersion = (definition) => ({
+    openapi: definition.openapi ?? DEFAULT_OPENAPI_VERSION,
+    ...definition,
+});
+
+export { DEFAULT_OPENAPI_VERSION, addLatestOpenApiVersion };

package/dist/utils/transform/utils/addMissingTags.d.ts

@@ -0,0 +1,3 @@
+import type { AnyObject } from '../../../types';
+export declare const addMissingTags: (definition: AnyObject) => AnyObject;
+//# sourceMappingURL=addMissingTags.d.ts.map

package/dist/utils/transform/utils/addMissingTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addMissingTags.d.ts","sourceRoot":"","sources":["../../../../src/utils/transform/utils/addMissingTags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,eAAO,MAAM,cAAc,eAAgB,SAAS,cA8CnD,CAAA"}

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

@@ -0,0 +1,38 @@
+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)));
+                    }
+                }
+            }
+        }
+    }
+    // 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,
+        ],
+    };
+};
+
+export { addMissingTags };

package/dist/utils/transform/utils/normalizeSecuritySchemes.d.ts

@@ -0,0 +1,3 @@
+import type { AnyObject } from '../../../types';
+export declare const normalizeSecuritySchemes: (definition: AnyObject) => AnyObject;
+//# sourceMappingURL=normalizeSecuritySchemes.d.ts.map

package/dist/utils/transform/utils/normalizeSecuritySchemes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeSecuritySchemes.d.ts","sourceRoot":"","sources":["../../../../src/utils/transform/utils/normalizeSecuritySchemes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,eAAO,MAAM,wBAAwB,eAAgB,SAAS,cAsD7D,CAAA"}

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

@@ -0,0 +1,49 @@
+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;
+        }
+    }
+    // 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;
+                    }, {});
+                }
+            }
+        }
+    }
+    return {
+        ...definition,
+        components: {
+            ...definition.components,
+            securitySchemes,
+        },
+    };
+};
+
+export { normalizeSecuritySchemes };

package/dist/utils/transform/utils/rejectSwaggerDocuments.d.ts

@@ -0,0 +1,3 @@
+import type { AnyObject } from '../../../types';
+export declare const rejectSwaggerDocuments: (defintion: AnyObject) => AnyObject;
+//# sourceMappingURL=rejectSwaggerDocuments.d.ts.map

package/dist/utils/transform/utils/rejectSwaggerDocuments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejectSwaggerDocuments.d.ts","sourceRoot":"","sources":["../../../../src/utils/transform/utils/rejectSwaggerDocuments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,eAAO,MAAM,sBAAsB,cAAe,SAAS,cAQ1D,CAAA"}

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

@@ -0,0 +1,8 @@
+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 };

package/dist/utils/validate.d.ts

@@ -1,7 +1,7 @@
 import type { AnyObject, Filesystem, ThrowOnErrorOption, ValidateResult } from '../types';
 export type ValidateOptions = ThrowOnErrorOption;
 /**
- * Validates an OpenAPI schema.
+ * Validates an OpenAPI document
  */
 export declare function validate(value: string | AnyObject | Filesystem, options?: ValidateOptions): Promise<ValidateResult>;
 //# sourceMappingURL=validate.d.ts.map

package/dist/utils/validate.js

@@ -2,7 +2,7 @@ import { makeFilesystem } from './makeFilesystem.js';
 import { Validator } from '../lib/Validator/Validator.js';
 
 /**
- * Validates an OpenAPI schema.
+ * Validates an OpenAPI document
  */
 async function validate(value, options) {
     const filesystem = makeFilesystem(value);

package/package.json

@@ -17,7 +17,7 @@
     "parser",
     "typescript"
   ],
-  "version": "0.8.9",
+  "version": "0.9.0",
   "engines": {
     "node": ">=18"
   },
@@ -64,7 +64,7 @@
     "json-to-ast": "^2.1.0",
     "just-diff": "^6.0.2",
     "tinybench": "^2.8.0",
-    "@scalar/build-tooling": "0.1.11",
+    "@scalar/build-tooling": "0.1.12",
     "@scalar/openapi-types": "0.1.5"
   },
   "scripts": {