@scalar/oas-utils 0.2.42 → 0.2.44

package/dist/transforms/import-spec.js

@@ -1,149 +1,232 @@
-import { tagObjectSchema } from '../entities/workspace/spec/spec.js';
+import { securitySchemeSchema, authExampleFromSchema } from '../entities/spec/security.js';
 import { schemaModel } from '../helpers/schema-model.js';
-import { load, dereference } from '@scalar/openapi-parser';
-import { createRequest } from '../entities/workspace/spec/requests.js';
-import { createFolder } from '../entities/workspace/folder/folder.js';
-import { createServer } from '../entities/workspace/server/server.js';
-import { createCollection } from '../entities/workspace/collection/collection.js';
+import { keysOf } from '@scalar/object-utils/arrays';
+import { load, upgrade, dereference } from '@scalar/openapi-parser';
+import { serverSchema } from '../entities/spec/server.js';
+import { requestMethods, requestSchema } from '../entities/spec/requests.js';
+import { tagSchema } from '../entities/spec/spec-objects.js';
+import { createExampleFromRequest } from '../entities/spec/request-examples.js';
+import { collectionSchema } from '../entities/spec/collection.js';
 
-const PARAM_DICTIONARY = {
-    cookie: 'cookies',
-    header: 'headers',
-    path: 'path',
-    query: 'query',
+/**
+ * We need to convert from openapi spec flows to our singular flow object here
+ * If we ever go spec compliant (flows), we will no longer need this conversion
+ */
+const convertOauth2Flows = (security, nameKey) => {
+    if (security.type === 'oauth2') {
+        const entries = Object.entries(security.flows ?? {});
+        if (entries.length) {
+            const [[type, flow]] = entries;
+            return {
+                ...security,
+                nameKey,
+                flow: {
+                    ...flow,
+                    type,
+                },
+            };
+        }
+    }
+    return {
+        ...security,
+        nameKey,
+    };
 };
-/** Import an OpenAPI spec file and convert it to workspace entities */
-const importSpecToWorkspace = async (spec, overloadServers) => {
-    const importWarnings = [];
-    const requests = [];
-    // TODO: `parsedSpec` can have circular reference and will break.
-    // We always have to use the original document.
+/**
+ * Import an OpenAPI spec file and convert it to workspace entities
+ *
+ * We will aim to keep the entities as close to the specification as possible
+ * to leverage bi-directional translation. Where entities are able to be
+ * created and used at various levels we will index via the uids to create
+ * the relationships
+ */
+async function importSpecToWorkspace(spec) {
     const { filesystem } = await load(spec);
-    const { schema, errors } = await dereference(filesystem);
-    if (errors?.length || !schema) {
-        console.warn('Please open an issue on https://github.com/scalar/scalar\n', 'Scalar OpenAPI Parser Warning:\n', errors);
-    }
-    // Keep a list of all tags used in requests so we can reference them later
-    const requestTags = new Set();
-    Object.entries(schema?.paths || {}).forEach(([pathString, path]) => {
+    const { specification } = upgrade(filesystem);
+    const { schema: _schema, errors = [] } = await dereference(specification);
+    const schema = _schema;
+    const importWarnings = [...errors.map((e) => e.message)];
+    if (!schema)
+        return { importWarnings, error: true };
+    // ---------------------------------------------------------------------------
+    // Some entities will be broken out as individual lists for modification in the workspace
+    const requests = [];
+    const servers = serverSchema.array().parse(schema.servers?.map((s) => s ?? [
+        {
+            url: typeof window !== 'undefined'
+                ? window.location.origin
+                : 'http://localhost',
+            description: 'Replace with your API server',
+        },
+    ]) ?? []);
+    /**
+     * List of all tag strings. For non compliant specs we may need to
+     * add top level tag objects for missing tag objects
+     */
+    const tagNames = new Set();
+    // ---------------------------------------------------------------------------
+    // SECURITY HANDLING
+    const security = schema.components?.securitySchemes ?? {};
+    const securitySchemes = Object.entries(security)
+        .map?.(([nameKey, s]) => {
+        const scheme = schemaModel(
+        // We must convert flows to a singular object, technically not spec compliant so we grab the first
+        s.type === 'oauth2'
+            ? convertOauth2Flows(s, nameKey)
+            : {
+                ...s,
+                nameKey,
+            }, securitySchemeSchema, false);
+        if (!scheme)
+            importWarnings.push(`Security scheme ${nameKey} is invalid.`);
+        return scheme;
+    })
+        .filter((v) => !!v);
+    // Map of security scheme names to UIDs
+    const securitySchemeMap = {};
+    securitySchemes.forEach((s) => {
+        securitySchemeMap[s.nameKey] = s.uid;
+    });
+    // ---------------------------------------------------------------------------
+    // REQUEST HANDLING
+    keysOf(schema.paths ?? {}).forEach((pathString) => {
+        const path = schema?.paths?.[pathString];
         if (!path)
             return;
-        const methods = [
-            'get',
-            'put',
-            'post',
-            'delete',
-            'options',
-            'head',
-            'patch',
-            'trace',
-        ];
-        methods.forEach((method) => {
+        // Path level servers must be saved
+        const pathServers = serverSchema.array().parse(path.servers ?? []);
+        servers.push(...pathServers);
+        requestMethods.forEach((method) => {
             const operation = path[method];
-            if (!operation)
-                return;
-            if ('$ref' in operation) {
-                importWarnings.push(`${method.toUpperCase}:${pathString} - Importing of $ref paths is not yet supported`);
-                return;
+            if (operation && typeof operation === 'object') {
+                const operationServers = serverSchema
+                    .array()
+                    .parse(operation.servers ?? []);
+                servers.push(...operationServers);
+                // We will save a list of all tags to ensure they exists at the top level
+                // TODO: make sure we add any loose requests with no tags to the collection children
+                operation.tags?.forEach((t) => tagNames.add(t));
+                // Remove security here and add it correctly below
+                const { security: removed, ...operationWithoutSecurity } = operation;
+                const requestPayload = {
+                    ...operationWithoutSecurity,
+                    method,
+                    path: pathString,
+                    selectedSecuritySchemeUids: [],
+                    // Merge path and operation level parameters
+                    parameters: [
+                        ...(path?.parameters ?? []),
+                        ...(operation.parameters ?? []),
+                    ],
+                    servers: [...pathServers, ...operationServers].map((s) => s.uid),
+                };
+                // Add list of UIDs to associate security schemes
+                // As per the spec if there is operation level security we ignore the top level requirements
+                if (operation.security?.length)
+                    requestPayload.security = operation.security?.map((s) => {
+                        const keys = Object.keys(s);
+                        // Handle the case of {} for optional
+                        if (keys.length) {
+                            const [key] = Object.keys(s);
+                            return {
+                                [key]: s[key],
+                            };
+                        }
+                        else
+                            return s;
+                    });
+                // Save parse the request
+                const request = schemaModel(requestPayload, requestSchema, false);
+                if (!request)
+                    importWarnings.push(`${method} Request at ${path} is invalid.`);
+                else
+                    requests.push(request);
             }
-            const parameters = {
-                path: {},
-                query: {},
-                headers: {},
-                cookies: {},
-            };
-            // An operation can have component level parameters as well :)
-            const pathAndOperationParameters = [
-                ...(path.parameters || []),
-                ...(operation.parameters || []),
-            ].filter((p) => p);
-            // Loop over params to set request params
-            pathAndOperationParameters.forEach((_param) => {
-                const param = _param;
-                if ('name' in param &&
-                    PARAM_DICTIONARY[param.in]) {
-                    parameters[
-                    // Map cookie -> and header -> headers
-                    PARAM_DICTIONARY[param.in]][param.name] = param;
-                }
-            });
-            const request = createRequest({
-                method: method.toUpperCase(),
-                path: pathString,
-                tags: operation.tags || ['default'],
-                description: operation.description,
-                operationId: operation.operationId,
-                security: operation.security,
-                summary: operation.summary || pathString,
-                externalDocs: operation.externalDocs,
-                requestBody: operation.requestBody,
-                parameters,
-            });
-            request.tags?.forEach((t) => requestTags.add(t));
-            requests.push(request);
         });
     });
-    // todo workaround till we rethink how we do createTags
-    const tags = schemaModel(schema?.tags, tagObjectSchema.array(), false) ?? [
-        { name: 'default' },
-    ];
-    // If there are request tags that are only defined in
-    requestTags.forEach((requestTag) => {
-        if (!tags.some((tag) => tag.name === requestTag)) {
-            // Warn the user about implicit tags
-            importWarnings.push(`The tag *${requestTags}* is does not have an explicit tag object in the specification file. `);
-            tags.push({ name: requestTag });
-        }
+    // ---------------------------------------------------------------------------
+    // TAG HANDLING
+    // TODO: We may need to handle de-duping tags
+    const tags = schemaModel(schema?.tags ?? [], tagSchema.array(), false) ?? [];
+    // Delete any tag names that already have a definition
+    tags.forEach((t) => tagNames.delete(t.name));
+    // Add an entry for any tags that are used but do not have a definition
+    tagNames.forEach((name) => tags.push(tagSchema.parse({ name })));
+    // Tag name to UID map
+    const tagMap = {};
+    tags.forEach((t) => {
+        tagMap[t.name] = t;
     });
-    // TODO: Consider if we want this for production or just for data mocking
-    // Create a basic folder structure from tags
-    const folders = [];
+    // Add all tags by default. We will remove nested ones
+    const collectionChildren = new Set(tags.map((t) => t.uid));
+    // Nested folders go before any requests
     tags.forEach((t) => {
-        const folder = createFolder({
-            ...t,
-            childUids: requests
-                .filter((r) => r.tags?.includes(t.name))
-                .map((r) => r.uid),
+        t['x-scalar-children']?.forEach((c) => {
+            // Add the uid to the appropriate parent.children
+            const nestedUid = tagMap[c.tagName].uid;
+            t.children.push(nestedUid);
+            // Remove the nested uid from the root folder
+            collectionChildren.delete(nestedUid);
         });
-        folders.push(folder);
     });
-    // Toss in a default server if there aren't any
-    const unparsedServers = overloadServers ??
-        (schema?.servers?.length
-            ? schema.servers
-            : [
-                {
-                    url: typeof window !== 'undefined'
-                        ? window.location.origin
-                        : 'http://localhost',
-                    description: 'Replace with your API server',
-                },
-            ]);
-    const servers = unparsedServers.map((server) => createServer(server));
-    const collection = createCollection({
-        spec: {
-            openapi: schema?.openapi,
-            info: schema?.info,
-            security: schema?.security || schema?.securityDefinitions,
-            externalDocs: schema?.externalDocs,
-            serverUids: servers.map(({ uid }) => uid),
-            tags,
+    // Add the request UIDs to the tag children (or collection root)
+    requests.forEach((r) => {
+        if (r.tags) {
+            r.tags.forEach((t) => {
+                tagMap[t].children.push(r.uid);
+            });
+        }
+        else {
+            collectionChildren.add(r.uid);
+        }
+    });
+    // ---------------------------------------------------------------------------
+    const examples = [];
+    // Ensure each request has at least 1 example
+    requests.forEach((request) => {
+        // TODO: Need to handle parsing examples
+        // if (request['x-scalar-examples']) return
+        // Create the initial example
+        const example = createExampleFromRequest(request, 'Default Example');
+        examples.push(example);
+        request.examples.push(example.uid);
+    });
+    // ---------------------------------------------------------------------------
+    // Generate Collection
+    // Create the auth examples
+    const auth = securitySchemes?.reduce((prev, s) => {
+        const example = authExampleFromSchema(s);
+        if (example)
+            prev[s.uid] = example;
+        return prev;
+    }, {});
+    const collection = collectionSchema.parse({
+        ...schema,
+        auth,
+        requests: requests.map((r) => r.uid),
+        servers: servers.map((s) => s.uid),
+        tags: tags.map((t) => t.uid),
+        children: [...collectionChildren],
+        security: schema.security ?? [{}],
+        selectedServerUid: servers?.[0]?.uid,
+        components: {
+            ...schema.components,
         },
-        selectedServerUid: servers[0].uid,
-        // We default to having all the requests in the root folder
-        childUids: folders.map(({ uid }) => uid),
+        securitySchemes: securitySchemes.map((s) => s.uid),
     });
-    const components = schema?.components;
-    const securityDefinitions = schema?.securityDefinitions;
+    /**
+     * Servers and requests will be saved in top level maps and indexed via UID to
+     * maintain specification relationships
+     */
     return {
-        tags,
-        folders,
+        error: false,
         servers,
         requests,
+        examples,
         collection,
-        components,
-        securityDefinitions,
+        tags,
+        securitySchemes,
     };
-};
+}
 
 export { importSpecToWorkspace };

package/package.json

@@ -16,7 +16,7 @@
     "specification",
     "yaml"
   ],
-  "version": "0.2.42",
+  "version": "0.2.44",
   "engines": {
     "node": ">=18"
   },
@@ -31,6 +31,18 @@
       "import": "./dist/spec-getters/index.js",
       "types": "./dist/spec-getters/index.d.ts"
     },
+    "./migrations": {
+      "import": "./dist/migrations/index.js",
+      "types": "./dist/migrations/index.d.ts"
+    },
+    "./migrations/v-2.1.0": {
+      "import": "./dist/migrations/v-2.1.0/index.js",
+      "types": "./dist/migrations/v-2.1.0/index.d.ts"
+    },
+    "./migrations/v-0.0.0": {
+      "import": "./dist/migrations/v-0.0.0/index.js",
+      "types": "./dist/migrations/v-0.0.0/index.d.ts"
+    },
     "./helpers": {
       "import": "./dist/helpers/index.js",
       "types": "./dist/helpers/index.d.ts"
@@ -43,41 +55,29 @@
       "import": "./dist/entities/workspace/index.js",
       "types": "./dist/entities/workspace/index.d.ts"
     },
-    "./entities/workspace/spec": {
-      "import": "./dist/entities/workspace/spec/index.js",
-      "types": "./dist/entities/workspace/spec/index.d.ts"
-    },
-    "./entities/workspace/shared": {
-      "import": "./dist/entities/workspace/shared/index.js",
-      "types": "./dist/entities/workspace/shared/index.d.ts"
-    },
-    "./entities/workspace/server": {
-      "import": "./dist/entities/workspace/server/index.js",
-      "types": "./dist/entities/workspace/server/index.d.ts"
-    },
-    "./entities/workspace/security": {
-      "import": "./dist/entities/workspace/security/index.js",
-      "types": "./dist/entities/workspace/security/index.d.ts"
+    "./entities/spec": {
+      "import": "./dist/entities/spec/index.js",
+      "types": "./dist/entities/spec/index.d.ts"
     },
-    "./entities/workspace/folder": {
-      "import": "./dist/entities/workspace/folder/index.js",
-      "types": "./dist/entities/workspace/folder/index.d.ts"
+    "./entities/shared": {
+      "import": "./dist/entities/shared/index.js",
+      "types": "./dist/entities/shared/index.d.ts"
     },
-    "./entities/workspace/environment": {
-      "import": "./dist/entities/workspace/environment/index.js",
-      "types": "./dist/entities/workspace/environment/index.d.ts"
+    "./entities/hotkeys": {
+      "import": "./dist/entities/hotkeys/index.js",
+      "types": "./dist/entities/hotkeys/index.d.ts"
     },
-    "./entities/workspace/cookie": {
-      "import": "./dist/entities/workspace/cookie/index.js",
-      "types": "./dist/entities/workspace/cookie/index.d.ts"
+    "./entities/environment": {
+      "import": "./dist/entities/environment/index.js",
+      "types": "./dist/entities/environment/index.d.ts"
     },
-    "./entities/workspace/consts": {
-      "import": "./dist/entities/workspace/consts/index.js",
-      "types": "./dist/entities/workspace/consts/index.d.ts"
+    "./entities/cookie": {
+      "import": "./dist/entities/cookie/index.js",
+      "types": "./dist/entities/cookie/index.d.ts"
     },
-    "./entities/workspace/collection": {
-      "import": "./dist/entities/workspace/collection/index.js",
-      "types": "./dist/entities/workspace/collection/index.d.ts"
+    "./diff": {
+      "import": "./dist/diff/index.js",
+      "types": "./dist/diff/index.d.ts"
     }
   },
   "files": [
@@ -86,21 +86,26 @@
   ],
   "module": "dist/index.js",
   "dependencies": {
+    "@hyperjump/json-schema": "^1.9.6",
+    "flatted": "^3.3.1",
+    "microdiff": "^1.4.0",
     "nanoid": "^5.0.7",
     "yaml": "^2.4.5",
-    "zod": "^3.22.4",
-    "@scalar/themes": "0.9.28",
-    "@scalar/types": "0.0.7",
-    "@scalar/object-utils": "1.1.7"
+    "zod": "^3.23.8",
+    "@scalar/object-utils": "1.1.8",
+    "@scalar/themes": "0.9.30",
+    "@scalar/types": "0.0.9",
+    "@scalar/openapi-types": "0.1.1"
   },
   "devDependencies": {
     "rollup": "^4.16.4",
     "type-fest": "^4.20.0",
     "vite": "^5.2.10",
     "vitest": "^1.6.0",
-    "@scalar/openapi-types": "0.1.0",
+    "zod-to-ts": "^1.2.0",
     "@scalar/build-tooling": "0.1.10",
-    "@scalar/openapi-parser": "0.8.1"
+    "@scalar/openapi-parser": "0.8.3",
+    "@scalar/openapi-types": "0.1.1"
   },
   "scripts": {
     "build": "scalar-build-rollup",
@@ -110,6 +115,7 @@
     "preview": "vite preview",
     "test": "vitest",
     "test:unit": "vitest .",
+    "typegen:migration": "vite-node ./src/migrations/generate-types.ts",
     "types:build": "scalar-types-build",
     "types:check": "scalar-types-check"
   }