@mintlify/scraping 4.0.904 → 4.0.906

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/scraping",
-  "version": "4.0.904",
+  "version": "4.0.906",
   "description": "Scrape documentation frameworks to Mintlify docs",
   "engines": {
     "node": ">=18.0.0"
@@ -43,9 +43,10 @@
     "format:check": "oxfmt --check"
   },
   "dependencies": {
-    "@mintlify/common": "1.0.1039",
+    "@mintlify/common": "1.0.1041",
     "@mintlify/openapi-parser": "0.0.8",
     "fs-extra": "11.1.1",
+    "graphql": "16.11.0",
     "hast-util-to-mdast": "10.1.0",
     "js-yaml": "4.1.1",
     "mdast-util-mdx-jsx": "3.1.3",
@@ -62,9 +63,9 @@
     "zod": "3.24.0"
   },
   "devDependencies": {
-    "@mintlify/models": "0.0.342",
+    "@mintlify/models": "0.0.343",
     "@mintlify/ts-config": "2.0.2",
-    "@mintlify/validation": "0.1.796",
+    "@mintlify/validation": "0.1.798",
     "@tsconfig/recommended": "1.0.2",
     "@types/hast": "3.0.4",
     "@types/mdast": "4.0.4",
@@ -78,5 +79,5 @@
     "typescript": "5.5.3",
     "vitest": "2.1.9"
   },
-  "gitHead": "48ebadbb106c4c5969cd83c048e660bc39955f3f"
+  "gitHead": "e6c3793e677c3aa79650fb9fbd31467ff1649d2e"
 }

package/src/asyncapi/generateAsyncApiPagesForDocsConfig.ts

@@ -14,6 +14,7 @@ type GenerateAsyncApiPagesOptions = {
   outDirBasePath?: string;
   overwrite?: boolean;
   localSchema?: boolean;
+  writeFile?: (filename: string, content: string) => void | Promise<void>;
 };
 
 type AsyncApiPageGenerationResult = {

package/src/asyncapi/processAsyncApiChannel.ts

@@ -24,6 +24,7 @@ type GenerateAsyncApiPagesOptions = {
   outDir?: string;
   outDirBasePath?: string;
   overwrite?: boolean;
+  writeFile?: (filename: string, content: string) => void | Promise<void>;
 };
 
 type ProcessAsyncApiChannelArgs = {
@@ -90,18 +91,15 @@ export const processAsyncApiChannel = ({
     ? join(opts.outDirBasePath, `${filenameWithoutExtension}.mdx`)
     : `${filenameWithoutExtension}.mdx`;
   if (opts?.writeFiles && (!fse.pathExistsSync(targetPath) || opts.overwrite)) {
-    writePromises.push(createAsyncApiFrontmatter(targetPath, asyncApiMetaTag, opts.version));
+    const content = createAsyncApiFrontmatterContent(asyncApiMetaTag, opts.version);
+    writePromises.push(
+      opts.writeFile
+        ? Promise.resolve(opts.writeFile(targetPath, content))
+        : outputFile(targetPath, content)
+    );
   }
 };
 
-const createAsyncApiFrontmatter = async (
-  filename: string,
-  asyncApiMetaTag: string,
-  version?: string
-) => {
-  const data = `---
+const createAsyncApiFrontmatterContent = (asyncApiMetaTag: string, version?: string) => `---
 asyncapi: ${asyncApiMetaTag}${version ? `\nversion: ${version}` : ''}
 ---`;
-
-  await outputFile(filename, data);
-};

package/src/graphql/parseGraphqlSdl.ts

@@ -0,0 +1,146 @@
+import type {
+  GraphqlField,
+  GraphqlInputValue,
+  GraphqlReference,
+  GraphqlType,
+  GraphqlTypeRef,
+} from '@mintlify/models';
+import {
+  buildSchema,
+  isEnumType,
+  isInputObjectType,
+  isInterfaceType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isSpecifiedScalarType,
+  isUnionType,
+  print,
+  validateSchema,
+  valueFromASTUntyped,
+  type GraphQLArgument,
+  type GraphQLField,
+  type GraphQLInputField,
+  type GraphQLType,
+} from 'graphql';
+
+const isVisibleName = (name: string) => !name.startsWith('__');
+
+const withDescription = (description: string | undefined | null) =>
+  description === undefined || description === null ? {} : { description };
+
+const withDeprecation = (deprecationReason: string | undefined | null) =>
+  deprecationReason === undefined || deprecationReason === null ? {} : { deprecationReason };
+
+function normalizeGraphqlTypeRef(type: GraphQLType): GraphqlTypeRef {
+  if (isNonNullType(type)) {
+    return { kind: 'nonNull', ofType: normalizeGraphqlTypeRef(type.ofType) };
+  }
+  if (isListType(type)) {
+    return { kind: 'list', ofType: normalizeGraphqlTypeRef(type.ofType) };
+  }
+  return { kind: 'named', name: type.name };
+}
+
+function normalizeInputValue(field: GraphQLArgument | GraphQLInputField): GraphqlInputValue {
+  const defaultValue = field.astNode?.defaultValue;
+  return {
+    name: field.name,
+    type: normalizeGraphqlTypeRef(field.type),
+    ...withDescription(field.description),
+    ...(defaultValue === undefined
+      ? {}
+      : {
+          defaultValue: valueFromASTUntyped(defaultValue),
+          defaultValueLiteral: print(defaultValue),
+        }),
+    ...withDeprecation(field.deprecationReason),
+  };
+}
+
+function normalizeField(field: GraphQLField<unknown, unknown>): GraphqlField {
+  return {
+    name: field.name,
+    type: normalizeGraphqlTypeRef(field.type),
+    ...withDescription(field.description),
+    arguments: field.args.filter(({ name }) => isVisibleName(name)).map(normalizeInputValue),
+    ...withDeprecation(field.deprecationReason),
+  };
+}
+
+export function parseGraphqlSdl(sdl: string): GraphqlReference {
+  const schema = buildSchema(sdl);
+  const validationErrors = validateSchema(schema);
+  if (validationErrors.length > 0) {
+    throw new Error(validationErrors.map(({ message }) => message).join('\n'));
+  }
+
+  const types: GraphqlType[] = [];
+  for (const type of Object.values(schema.getTypeMap())) {
+    if (!isVisibleName(type.name) || (isScalarType(type) && isSpecifiedScalarType(type))) {
+      continue;
+    }
+
+    const named = { name: type.name, ...withDescription(type.description) };
+    if (isObjectType(type)) {
+      types.push({
+        kind: 'object',
+        ...named,
+        fields: Object.values(type.getFields())
+          .filter(({ name }) => isVisibleName(name))
+          .map(normalizeField),
+        interfaces: type.getInterfaces().map(({ name }) => name),
+      });
+    } else if (isInputObjectType(type)) {
+      types.push({
+        kind: 'input',
+        ...named,
+        fields: Object.values(type.getFields())
+          .filter(({ name }) => isVisibleName(name))
+          .map(normalizeInputValue),
+      });
+    } else if (isEnumType(type)) {
+      types.push({
+        kind: 'enum',
+        ...named,
+        values: type
+          .getValues()
+          .filter(({ name }) => isVisibleName(name))
+          .map((value) => ({
+            name: value.name,
+            ...withDescription(value.description),
+            ...withDeprecation(value.deprecationReason),
+          })),
+      });
+    } else if (isInterfaceType(type)) {
+      types.push({
+        kind: 'interface',
+        ...named,
+        fields: Object.values(type.getFields())
+          .filter(({ name }) => isVisibleName(name))
+          .map(normalizeField),
+        interfaces: type.getInterfaces().map(({ name }) => name),
+        possibleTypes: schema.getPossibleTypes(type).map(({ name }) => name),
+      });
+    } else if (isUnionType(type)) {
+      types.push({
+        kind: 'union',
+        ...named,
+        possibleTypes: type.getTypes().map(({ name }) => name),
+      });
+    } else if (isScalarType(type)) {
+      types.push({ kind: 'scalar', ...named });
+    }
+  }
+
+  const queryType = schema.getQueryType();
+  const mutationType = schema.getMutationType();
+  const subscriptionType = schema.getSubscriptionType();
+  return {
+    ...(queryType == null ? {} : { queryType: queryType.name }),
+    ...(mutationType == null ? {} : { mutationType: mutationType.name }),
+    ...(subscriptionType == null ? {} : { subscriptionType: subscriptionType.name }),
+    types,
+  };
+}

package/src/index.ts

@@ -12,3 +12,4 @@ export { write } from './utils/file.js';
 export { getErrorMessage } from './utils/errors.js';
 export { checkUrl } from './utils/url.js';
 export { FINAL_SUCCESS_MESSAGE } from './constants.js';
+export { parseGraphqlSdl } from './graphql/parseGraphqlSdl.js';

package/src/openapi/common.ts

@@ -62,21 +62,19 @@ export const getOpenApiDefinition = async (
   return { document: pathOrDocumentOrUrl, isUrl };
 };
 
-export const createOpenApiFrontmatter = async ({
-  filename,
+export const createOpenApiFrontmatterContent = ({
   openApiMetaTag,
   version,
   deprecated,
   metadata,
   extraContent,
 }: {
-  filename: string;
   openApiMetaTag: string;
   version?: string;
   deprecated?: boolean;
   metadata?: PageMetaTags;
   extraContent?: string;
-}) => {
+}): string => {
   let frontmatter = `---\nopenapi: ${openApiMetaTag}`;
   if (metadata && 'version' in metadata) {
     frontmatter += `\nversion: ${metadata.version}`;
@@ -99,10 +97,21 @@ export const createOpenApiFrontmatter = async ({
   }
 
   frontmatter += `\n---`;
+  return extraContent ? `${frontmatter}\n\n${extraContent}` : frontmatter;
+};
 
-  const data = extraContent ? `${frontmatter}\n\n${extraContent}` : frontmatter;
-
-  await outputFile(filename, data);
+export const createOpenApiFrontmatter = async ({
+  filename,
+  ...input
+}: {
+  filename: string;
+  openApiMetaTag: string;
+  version?: string;
+  deprecated?: boolean;
+  metadata?: PageMetaTags;
+  extraContent?: string;
+}) => {
+  await outputFile(filename, createOpenApiFrontmatterContent(input));
 };
 
 export type GenerateOpenApiPagesOptions = {
@@ -113,6 +122,7 @@ export type GenerateOpenApiPagesOptions = {
   outDirBasePath?: string;
   overwrite?: boolean;
   localSchema?: boolean;
+  writeFile?: (filename: string, content: string) => void | Promise<void>;
 };
 
 export type OpenApiPageGenerationResult<N, DN> = {
@@ -248,15 +258,17 @@ export function processOpenApiPath<N, DN>(
         ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
         : `${filenameWithoutExtension}.mdx`;
       if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
+        const input = {
+          openApiMetaTag: openapiMetaTag,
+          version: options.version,
+          deprecated: operation?.deprecated,
+          metadata: xMintMetadata,
+          extraContent: xMint?.content,
+        };
         writePromises.push(
-          createOpenApiFrontmatter({
-            filename: targetPath,
-            openApiMetaTag: openapiMetaTag,
-            version: options.version,
-            deprecated: operation?.deprecated,
-            metadata: xMintMetadata,
-            extraContent: xMint?.content,
-          })
+          options.writeFile
+            ? Promise.resolve(options.writeFile(targetPath, createOpenApiFrontmatterContent(input)))
+            : createOpenApiFrontmatter({ filename: targetPath, ...input })
         );
       }
     }
@@ -341,15 +353,17 @@ export function processOpenApiWebhook<N, DN>(
         ? join(options.outDirBasePath, `${filenameWithoutExtension}.mdx`)
         : `${filenameWithoutExtension}.mdx`;
       if (options.writeFiles && (!fse.pathExistsSync(targetPath) || options.overwrite)) {
+        const input = {
+          openApiMetaTag: openapiMetaTag,
+          version: options.version,
+          deprecated: operation?.deprecated,
+          metadata: xMint?.metadata,
+          extraContent: xMint?.content,
+        };
         writePromises.push(
-          createOpenApiFrontmatter({
-            filename: targetPath,
-            openApiMetaTag: openapiMetaTag,
-            version: options.version,
-            deprecated: operation?.deprecated,
-            metadata: xMint?.metadata,
-            extraContent: xMint?.content,
-          })
+          options.writeFile
+            ? Promise.resolve(options.writeFile(targetPath, createOpenApiFrontmatterContent(input)))
+            : createOpenApiFrontmatter({ filename: targetPath, ...input })
         );
       }
     }