@mintlify/scraping 4.0.1033 → 4.0.1035

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/scraping",
-  "version": "4.0.1033",
+  "version": "4.0.1035",
   "description": "Scrape documentation frameworks to Mintlify docs",
   "engines": {
     "node": ">=18.0.0"
@@ -43,7 +43,7 @@
     "format:check": "oxfmt --check"
   },
   "dependencies": {
-    "@mintlify/common": "1.0.1165",
+    "@mintlify/common": "1.0.1166",
     "fast-xml-parser": "5.7.3",
     "fs-extra": "11.1.1",
     "graphql": "16.11.0",
@@ -65,7 +65,7 @@
   "devDependencies": {
     "@mintlify/models": "0.0.361",
     "@mintlify/ts-config": "2.0.2",
-    "@mintlify/validation": "0.1.868",
+    "@mintlify/validation": "0.1.869",
     "@tsconfig/recommended": "1.0.2",
     "@types/hast": "3.0.4",
     "@types/mdast": "4.0.4",
@@ -79,5 +79,5 @@
     "typescript": "5.5.3",
     "vitest": "2.1.9"
   },
-  "gitHead": "8915b9a07e0f69a40ccb9395d8d0514157c710d3"
+  "gitHead": "5273fce0f218cb475e78a9db77622d699cfb0ecd"
 }

package/src/sdk/converters/typedoc.ts

@@ -69,6 +69,7 @@ type TypedocNode = {
   implementedTypes?: TypedocType[];
   inheritedFrom?: { name: string };
 };
+type TypeToken = { text: string; href?: string };
 
 const SECTIONS: {
   kind: number;
@@ -116,7 +117,7 @@ export async function convertTypedoc(sourcePath: string): Promise<SdkReference>
     const prefix = multiModule ? slugify(module.name) : '';
     for (const { node, namespacePath } of collectDeclarations(module)) {
       const section = SECTIONS.find((entry) => entry.kind === node.kind);
-      if (!section) continue;
+      if (!section || node.flags?.isPrivate) continue;
       slugById.set(
         node.id,
         path.posix.join(prefix, ...namespacePath.map(slugify), section.dir, slugify(node.name))
@@ -245,7 +246,7 @@ class TypedocRenderer {
         title: `${parentTitle}.${property.name}`,
         description: this.firstSentence(property.comment ?? property.getSignature?.comment),
         tag: 'PROPERTY',
-        content: this.responseField(property.name, this.type(type), optional, summary),
+        content: this.typeField(property.name, type, optional, summary),
         target: { kind: 'property', name: property.name, parent: parent.name },
       });
     }
@@ -302,9 +303,9 @@ class TypedocRenderer {
         const type = property.kind === KIND.accessor ? property.getSignature?.type : property.type;
         const optional = property.flags?.isOptional === true;
         lines.push(
-          this.responseField(
+          this.typeField(
             property.name,
-            this.type(type),
+            type,
             optional,
             this.comment(property.comment ?? property.getSignature?.comment)
           )
@@ -354,9 +355,9 @@ class TypedocRenderer {
         lines.push(`${'#'.repeat(depth)} Parameters`);
         for (const param of signature.parameters) {
           lines.push(
-            this.responseField(
+            this.typeField(
               param.name,
-              this.type(param.type),
+              param.type,
               param.flags?.isOptional === true || param.defaultValue !== undefined,
               this.comment(param.comment)
             )
@@ -367,18 +368,38 @@ class TypedocRenderer {
       const returnType = this.type(signature.type);
       if (returnType && returnType !== 'void') {
         lines.push(`${'#'.repeat(depth)} Returns`);
-        lines.push(
-          `\`${escapeInlineCode(returnType)}\`${returns ? `\n\n${this.parts(returns.content)}` : ''}`
-        );
+        const linked = this.linkedType(signature.type) ?? inlineCode(returnType);
+        lines.push(`${linked}${returns ? `\n\n${this.parts(returns.content)}` : ''}`);
       }
     }
     return lines;
   }
 
-  private responseField(name: string, type: string, optional: boolean, body?: string): string {
+  private typeField(
+    name: string,
+    type: TypedocType | undefined,
+    optional: boolean,
+    body?: string
+  ): string {
+    const tokens = this.typeTokens(type);
+    const [only] = tokens;
+    const typeHref = tokens.length === 1 && only?.href ? `/${only.href}` : undefined;
+    const linked = typeHref ? undefined : this.linkedType(type);
+    const content = [linked && `**Type:** ${linked}`, body].filter(Boolean).join('\n\n');
+    return this.responseField(name, this.type(type), optional, content, typeHref);
+  }
+
+  private responseField(
+    name: string,
+    type: string,
+    optional: boolean,
+    body?: string,
+    typeHref?: string
+  ): string {
     const typeAttr = type ? ` type=${this.jsxString(truncate(type, 80))}` : '';
+    const typeHrefAttr = typeHref ? ` typeHref=${this.jsxString(typeHref)}` : '';
     const requiredAttr = optional ? '' : ' required';
-    return `<ResponseField name=${this.jsxString(name)}${typeAttr}${requiredAttr}>\n${indent(body || '')}\n</ResponseField>`;
+    return `<ResponseField name=${this.jsxString(name)}${typeAttr}${typeHrefAttr}${requiredAttr}>\n${indent(body || '')}\n</ResponseField>`;
   }
 
   private jsxString(value: string): string {
@@ -435,56 +456,102 @@ class TypedocRenderer {
   }
 
   type(type?: TypedocType): string {
-    if (!type) return 'void';
+    return this.typeTokens(type)
+      .map((token) => token.text)
+      .join('');
+  }
+
+  private linkedType(type?: TypedocType): string | undefined {
+    const tokens = this.typeTokens(type);
+    if (!tokens.some((token) => token.href)) return undefined;
+    const merged: TypeToken[] = [];
+    for (const token of tokens) {
+      const last = merged.at(-1);
+      if (last && !last.href && !token.href) last.text += token.text;
+      else merged.push({ ...token });
+    }
+    const children = merged
+      .map((token) => (token.href ? `[${token.text}](/${token.href})` : this.jsxString(token.text)))
+      .join('');
+    return `<code>${children}</code>`;
+  }
+
+  private typeTokens(type?: TypedocType): TypeToken[] {
+    if (!type) return [{ text: 'void' }];
     switch (type.type) {
       case 'intrinsic':
-        return type.name ?? 'unknown';
+        return [{ text: type.name ?? 'unknown' }];
       case 'reference': {
-        const args = type.typeArguments?.length
-          ? `<${type.typeArguments.map((arg) => this.type(arg)).join(', ')}>`
-          : '';
-        return `${type.name ?? 'unknown'}${args}`;
+        const href = typeof type.target === 'number' ? this.slugById.get(type.target) : undefined;
+        const name: TypeToken = { text: type.name ?? 'unknown', href };
+        if (!type.typeArguments?.length) return [name];
+        return [name, { text: '<' }, ...this.joinTypes(type.typeArguments, ', '), { text: '>' }];
       }
       case 'union':
-        return (type.types ?? []).map((entry) => this.type(entry)).join(' | ');
+        return this.joinTypes(type.types, ' | ');
       case 'intersection':
-        return (type.types ?? []).map((entry) => this.type(entry)).join(' & ');
+        return this.joinTypes(type.types, ' & ');
       case 'array':
-        return `${this.type(type.elementType)}[]`;
+        return [...this.typeTokens(type.elementType), { text: '[]' }];
       case 'literal':
-        return JSON.stringify(type.value);
+        return [{ text: JSON.stringify(type.value) }];
       case 'tuple':
-        return `[${(type.elements ?? []).map((entry) => this.type(entry)).join(', ')}]`;
+        return [{ text: '[' }, ...this.joinTypes(type.elements, ', '), { text: ']' }];
       case 'reflection':
         return this.reflection(type.declaration);
       case 'typeOperator':
-        return `${type.operator} ${this.type(type.target as TypedocType)}`;
+        return [{ text: `${type.operator} ` }, ...this.typeTokens(type.target as TypedocType)];
       case 'indexedAccess':
-        return `${this.type(type.objectType)}[${this.type(type.indexType)}]`;
+        return [
+          ...this.typeTokens(type.objectType),
+          { text: '[' },
+          ...this.typeTokens(type.indexType),
+          { text: ']' },
+        ];
       case 'conditional':
-        return `${this.type(type.checkType)} extends ${this.type(type.extendsType)} ? ${this.type(type.trueType)} : ${this.type(type.falseType)}`;
+        return [
+          ...this.typeTokens(type.checkType),
+          { text: ' extends ' },
+          ...this.typeTokens(type.extendsType),
+          { text: ' ? ' },
+          ...this.typeTokens(type.trueType),
+          { text: ' : ' },
+          ...this.typeTokens(type.falseType),
+        ];
       case 'query':
-        return `typeof ${this.type(type.target as TypedocType)}`;
+        return [{ text: 'typeof ' }, ...this.typeTokens(type.target as TypedocType)];
       case 'templateLiteral':
-        return 'string';
+        return [{ text: 'string' }];
       default:
-        return type.name ?? 'unknown';
+        return [{ text: type.name ?? 'unknown' }];
     }
   }
 
-  private reflection(declaration?: TypedocNode): string {
-    if (!declaration) return 'object';
-    if (declaration.signatures?.length) {
-      const signature = declaration.signatures[0]!;
-      const params = (signature.parameters ?? [])
-        .map((param) => `${param.name}: ${this.type(param.type)}`)
-        .join(', ');
-      return `(${params}) => ${this.type(signature.type)}`;
+  private joinTypes(types: TypedocType[] = [], separator: string): TypeToken[] {
+    return types.flatMap((entry, index) => [
+      ...(index > 0 ? [{ text: separator }] : []),
+      ...this.typeTokens(entry),
+    ]);
+  }
+
+  private reflection(declaration?: TypedocNode): TypeToken[] {
+    if (!declaration) return [{ text: 'object' }];
+    const signature = declaration.signatures?.[0];
+    if (signature) {
+      const params = (signature.parameters ?? []).flatMap((param, index) => [
+        { text: `${index > 0 ? ', ' : ''}${param.name}: ` },
+        ...this.typeTokens(param.type),
+      ]);
+      return [{ text: '(' }, ...params, { text: ') => ' }, ...this.typeTokens(signature.type)];
     }
     if (declaration.children?.length) {
-      return `{ ${declaration.children.map((child) => `${child.name}: ${this.type(child.type)}`).join('; ')} }`;
+      const members = declaration.children.flatMap((child, index) => [
+        { text: `${index > 0 ? '; ' : ''}${child.name}: ` },
+        ...this.typeTokens(child.type),
+      ]);
+      return [{ text: '{ ' }, ...members, { text: ' }' }];
     }
-    return 'object';
+    return [{ text: 'object' }];
   }
 }
 
@@ -499,6 +566,12 @@ function truncate(text: string, max: number): string {
   return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 
-function escapeInlineCode(text: string): string {
-  return text.replace(/`/g, '');
+function inlineCode(text: string): string {
+  const code = text.trim();
+  if (!code) return text;
+  const start = text.indexOf(code);
+  const longestRun = Math.max(0, ...(code.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = '`'.repeat(longestRun + 1);
+  const pad = code.startsWith('`') || code.endsWith('`') ? ' ' : '';
+  return `${text.slice(0, start)}${fence}${pad}${code}${pad}${fence}${text.slice(start + code.length)}`;
 }