@deplens/mcp 0.1.6 → 0.1.8

package/src/core/parse-dts.mjs

@@ -1,14 +1,14 @@
 // parse-dts.mjs - TypeScript Compiler API based .d.ts parser
-import ts from "typescript"
-import fs from "fs"
-import path from "path"
+import ts from "typescript";
+import fs from "fs";
+import path from "path";
 
 function getScriptKind(filePath) {
   if (typeof ts.getScriptKindFromFileName === "function") {
-    const kind = ts.getScriptKindFromFileName(filePath)
-    return kind === ts.ScriptKind.Unknown ? ts.ScriptKind.TS : kind
+    const kind = ts.getScriptKindFromFileName(filePath);
+    return kind === ts.ScriptKind.Unknown ? ts.ScriptKind.TS : kind;
   }
-  return ts.ScriptKind.TS
+  return ts.ScriptKind.TS;
 }
 
 /**
@@ -18,71 +18,77 @@ function getScriptKind(filePath) {
  * @returns {Map<string, string>} Map of symbol name -> source file path
  */
 function findReExports(dtsPath, filterList) {
-  const content = fs.readFileSync(dtsPath, "utf-8")
+  const content = fs.readFileSync(dtsPath, "utf-8");
   const sourceFile = ts.createSourceFile(
     dtsPath,
     content,
     ts.ScriptTarget.Latest,
     true,
     getScriptKind(dtsPath),
-  )
+  );
 
-  const dtsDir = path.dirname(dtsPath)
-  const reExports = new Map()
-  const wildcardSources = []
-  const filterSet = filterList ? new Set(filterList.map((n) => n.toLowerCase())) : null
+  const dtsDir = path.dirname(dtsPath);
+  const reExports = new Map();
+  const wildcardSources = [];
+  const filterSet = filterList
+    ? new Set(filterList.map((n) => n.toLowerCase()))
+    : null;
 
   function resolveDtsPath(moduleSpec) {
     // Handle .cjs/.mjs/.js -> .d.cts/.d.mts/.d.ts
     let sourceFile = moduleSpec
       .replace(/\.cjs$/, ".d.cts")
       .replace(/\.mjs$/, ".d.mts")
-      .replace(/\.js$/, ".d.ts")
-    if (!sourceFile.endsWith(".d.ts") && !sourceFile.endsWith(".d.cts") && !sourceFile.endsWith(".d.mts")) {
+      .replace(/\.js$/, ".d.ts");
+    if (
+      !sourceFile.endsWith(".d.ts") &&
+      !sourceFile.endsWith(".d.cts") &&
+      !sourceFile.endsWith(".d.mts")
+    ) {
       // Try all extensions
-      const dtsCandidate = path.resolve(dtsDir, sourceFile + ".d.ts")
-      const ctsCandidate = path.resolve(dtsDir, sourceFile + ".d.cts")
-      const mtsCandidate = path.resolve(dtsDir, sourceFile + ".d.mts")
-      if (fs.existsSync(dtsCandidate)) return dtsCandidate
-      if (fs.existsSync(ctsCandidate)) return ctsCandidate
-      if (fs.existsSync(mtsCandidate)) return mtsCandidate
-      return null
+      const dtsCandidate = path.resolve(dtsDir, sourceFile + ".d.ts");
+      const ctsCandidate = path.resolve(dtsDir, sourceFile + ".d.cts");
+      const mtsCandidate = path.resolve(dtsDir, sourceFile + ".d.mts");
+      if (fs.existsSync(dtsCandidate)) return dtsCandidate;
+      if (fs.existsSync(ctsCandidate)) return ctsCandidate;
+      if (fs.existsSync(mtsCandidate)) return mtsCandidate;
+      return null;
     }
-    const fullPath = path.resolve(dtsDir, sourceFile)
-    return fs.existsSync(fullPath) ? fullPath : null
+    const fullPath = path.resolve(dtsDir, sourceFile);
+    return fs.existsSync(fullPath) ? fullPath : null;
   }
 
   function visit(node) {
     // Handle: export { foo } from './foo.js'
     if (ts.isExportDeclaration(node) && node.moduleSpecifier) {
-      const moduleSpec = node.moduleSpecifier.text
+      const moduleSpec = node.moduleSpecifier.text;
 
       if (node.exportClause && ts.isNamedExports(node.exportClause)) {
         // Named exports
         for (const elem of node.exportClause.elements) {
-          const exportedName = elem.name.text
+          const exportedName = elem.name.text;
           if (!filterSet || filterSet.has(exportedName.toLowerCase())) {
-            const fullPath = resolveDtsPath(moduleSpec)
+            const fullPath = resolveDtsPath(moduleSpec);
             if (fullPath) {
-              reExports.set(exportedName, fullPath)
+              reExports.set(exportedName, fullPath);
             }
           }
         }
       } else if (!node.exportClause) {
         // Wildcard: export * from './module'
-        const fullPath = resolveDtsPath(moduleSpec)
+        const fullPath = resolveDtsPath(moduleSpec);
         if (fullPath) {
-          wildcardSources.push(fullPath)
+          wildcardSources.push(fullPath);
         }
       }
     }
-    ts.forEachChild(node, visit)
+    ts.forEachChild(node, visit);
   }
 
-  visit(sourceFile)
+  visit(sourceFile);
 
   // For wildcard exports, we return them all as potential sources
-  return { named: reExports, wildcards: wildcardSources }
+  return { named: reExports, wildcards: wildcardSources };
 }
 
 /**
@@ -93,21 +99,21 @@ function findReExports(dtsPath, filterList) {
  */
 export function parseDtsFile(dtsPath, filterList, visited = new Set()) {
   if (!fs.existsSync(dtsPath)) {
-    return null
+    return null;
   }
   if (visited.has(dtsPath)) {
-    return null
+    return null;
   }
-  visited.add(dtsPath)
+  visited.add(dtsPath);
 
-  const content = fs.readFileSync(dtsPath, "utf-8")
+  const content = fs.readFileSync(dtsPath, "utf-8");
   const sourceFile = ts.createSourceFile(
     dtsPath,
     content,
     ts.ScriptTarget.Latest,
     true,
     getScriptKind(dtsPath),
-  )
+  );
 
   const typeInfo = {
     functions: {},
@@ -118,205 +124,225 @@ export function parseDtsFile(dtsPath, filterList, visited = new Set()) {
     namespaces: {},
     defaults: [],
     jsdoc: {},
-  }
+  };
 
-  const filterSet = filterList ? new Set(filterList.map((n) => n.toLowerCase())) : null
+  const filterSet = filterList
+    ? new Set(filterList.map((n) => n.toLowerCase()))
+    : null;
 
   function shouldInclude(name) {
-    if (!filterSet) return true
-    return filterSet.has(name.toLowerCase())
+    if (!filterSet) return true;
+    return filterSet.has(name.toLowerCase());
   }
 
   function getNodeText(node) {
-    return node.getText(sourceFile)
+    return node.getText(sourceFile);
   }
 
   function formatType(typeNode, maxLen = 80) {
-    if (!typeNode) return "any"
-    const text = getNodeText(typeNode).replace(/\s+/g, " ").trim()
-    return text.length > maxLen ? text.substring(0, maxLen) + "..." : text
+    if (!typeNode) return "any";
+    const text = getNodeText(typeNode).replace(/\s+/g, " ").trim();
+    return text.length > maxLen ? text.substring(0, maxLen) + "..." : text;
   }
 
   function formatParams(params) {
-    if (!params || params.length === 0) return ""
+    if (!params || params.length === 0) return "";
 
     // For complex destructuring, simplify
     const paramStrs = params.map((p) => {
-      const name = p.name ? getNodeText(p.name) : "arg"
+      const name = p.name ? getNodeText(p.name) : "arg";
 
       // Handle destructuring pattern - just show "options"
       if (name.startsWith("{")) {
-        return "options: object"
+        return "options: object";
       }
 
-      const optional = p.questionToken ? "?" : ""
-      const type = p.type ? formatType(p.type, 40) : "any"
+      const optional = p.questionToken ? "?" : "";
+      const type = p.type ? formatType(p.type, 40) : "any";
 
       // Simplify long type names
-      const shortType = type.length > 40 ? type.split("<")[0] + "<...>" : type
-      return `${name}${optional}: ${shortType}`
-    })
+      const shortType = type.length > 40 ? type.split("<")[0] + "<...>" : type;
+      return `${name}${optional}: ${shortType}`;
+    });
 
     // If total length too long, just show count
-    const joined = paramStrs.join(", ")
+    const joined = paramStrs.join(", ");
     if (joined.length > 100) {
-      return `${params.length} param${params.length > 1 ? "s" : ""}`
+      return `${params.length} param${params.length > 1 ? "s" : ""}`;
     }
-    return joined
+    return joined;
   }
 
   function jsDocText(comment) {
-    if (!comment) return ""
-    if (typeof comment === "string") return comment.trim()
+    if (!comment) return "";
+    if (typeof comment === "string") return comment.trim();
     if (Array.isArray(comment)) {
-      return comment.map((part) => part.text || "").join("").trim()
+      return comment
+        .map((part) => part.text || "")
+        .join("")
+        .trim();
     }
-    return ""
+    return "";
   }
 
   function collectJSDocTags(tagNodes) {
-    const tags = {}
-    if (!tagNodes || tagNodes.length === 0) return tags
+    const tags = {};
+    if (!tagNodes || tagNodes.length === 0) return tags;
     for (const tag of tagNodes) {
-      if (!tag?.tagName?.text) continue
-      const tagName = tag.tagName.text
-      const comment = jsDocText(tag.comment)
-      if (!tags[tagName]) tags[tagName] = []
-      tags[tagName].push(comment || "")
+      if (!tag?.tagName?.text) continue;
+      const tagName = tag.tagName.text;
+      const comment = jsDocText(tag.comment);
+      if (!tags[tagName]) tags[tagName] = [];
+      tags[tagName].push(comment || "");
     }
-    return tags
+    return tags;
   }
 
   function extractJSDoc(node) {
-    const entries = ts.getJSDocCommentsAndTags(node)
-    if (!entries || entries.length === 0) return null
-    let summary = ""
-    const tags = {}
+    const entries = ts.getJSDocCommentsAndTags(node);
+    if (!entries || entries.length === 0) return null;
+    let summary = "";
+    const tags = {};
     for (const entry of entries) {
       if (ts.isJSDoc(entry)) {
-        if (!summary) summary = jsDocText(entry.comment)
-        const entryTags = collectJSDocTags(entry.tags)
+        if (!summary) summary = jsDocText(entry.comment);
+        const entryTags = collectJSDocTags(entry.tags);
         for (const [name, values] of Object.entries(entryTags)) {
-          if (!tags[name]) tags[name] = []
-          tags[name].push(...values)
+          if (!tags[name]) tags[name] = [];
+          tags[name].push(...values);
         }
       } else if (ts.isJSDocTag(entry)) {
-        const tagName = entry.tagName?.text
+        const tagName = entry.tagName?.text;
         if (tagName) {
-          const comment = jsDocText(entry.comment)
-          if (!tags[tagName]) tags[tagName] = []
-          tags[tagName].push(comment || "")
+          const comment = jsDocText(entry.comment);
+          if (!tags[tagName]) tags[tagName] = [];
+          tags[tagName].push(comment || "");
         }
       }
     }
-    if (!summary && Object.keys(tags).length === 0) return null
-    return { summary, tags }
+    if (!summary && Object.keys(tags).length === 0) return null;
+    return { summary, tags };
   }
 
   function attachJSDoc(name, node) {
-    if (!name || !node) return
-    const doc = extractJSDoc(node)
-    if (!doc) return
-    typeInfo.jsdoc[name] = doc
+    if (!name || !node) return;
+    const doc = extractJSDoc(node);
+    if (!doc) return;
+    typeInfo.jsdoc[name] = doc;
   }
 
   function visit(node) {
     // Function declarations
     if (ts.isFunctionDeclaration(node)) {
-      const isDefault = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
-      const name = node.name?.text || (isDefault ? "default" : null)
+      const isDefault = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.DefaultKeyword,
+      );
+      const name = node.name?.text || (isDefault ? "default" : null);
       if (name && shouldInclude(name)) {
-        const params = formatParams(node.parameters)
-        const returnType = formatType(node.type, 60)
-        typeInfo.functions[name] = { params, returnType }
-        attachJSDoc(name, node)
+        const params = formatParams(node.parameters);
+        const returnType = formatType(node.type, 60);
+        typeInfo.functions[name] = { params, returnType };
+        attachJSDoc(name, node);
       }
     }
 
     // Interface declarations
     if (ts.isInterfaceDeclaration(node)) {
-      const name = node.name.text
-      const isDefault = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
-      const exportName = isDefault ? "default" : name
+      const name = node.name.text;
+      const isDefault = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.DefaultKeyword,
+      );
+      const exportName = isDefault ? "default" : name;
       if (shouldInclude(exportName)) {
-        const props = []
+        const props = [];
         node.members.slice(0, 5).forEach((member) => {
           if (ts.isPropertySignature(member) && member.name) {
-            const propName = getNodeText(member.name)
-            const optional = member.questionToken ? "?" : ""
-            const propType = formatType(member.type, 30)
-            props.push(`${propName}${optional}: ${propType}`)
+            const propName = getNodeText(member.name);
+            const optional = member.questionToken ? "?" : "";
+            const propType = formatType(member.type, 30);
+            props.push(`${propName}${optional}: ${propType}`);
           }
-        })
+        });
         if (props.length > 0) {
-          typeInfo.interfaces[exportName] = props
-          attachJSDoc(exportName, node)
+          typeInfo.interfaces[exportName] = props;
+          attachJSDoc(exportName, node);
         }
       }
     }
 
     // Type aliases
     if (ts.isTypeAliasDeclaration(node)) {
-      const name = node.name.text
-      const isDefault = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
-      const exportName = isDefault ? "default" : name
+      const name = node.name.text;
+      const isDefault = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.DefaultKeyword,
+      );
+      const exportName = isDefault ? "default" : name;
       if (shouldInclude(exportName)) {
-        typeInfo.types[exportName] = formatType(node.type, 80)
-        attachJSDoc(exportName, node)
+        typeInfo.types[exportName] = formatType(node.type, 80);
+        attachJSDoc(exportName, node);
       }
     }
 
     // Class declarations
     if (ts.isClassDeclaration(node)) {
-      const isDefault = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
-      const name = node.name?.text || (isDefault ? "default" : null)
+      const isDefault = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.DefaultKeyword,
+      );
+      const name = node.name?.text || (isDefault ? "default" : null);
       if (name && shouldInclude(name)) {
-        let extendsClause = null
+        let extendsClause = null;
         if (node.heritageClauses) {
           for (const clause of node.heritageClauses) {
-            if (clause.token === ts.SyntaxKind.ExtendsKeyword && clause.types.length > 0) {
-              extendsClause = getNodeText(clause.types[0].expression)
+            if (
+              clause.token === ts.SyntaxKind.ExtendsKeyword &&
+              clause.types.length > 0
+            ) {
+              extendsClause = getNodeText(clause.types[0].expression);
             }
           }
         }
-        typeInfo.classes[name] = extendsClause
-        attachJSDoc(name, node)
+        typeInfo.classes[name] = extendsClause;
+        attachJSDoc(name, node);
       }
     }
 
     // Enum declarations
     if (ts.isEnumDeclaration(node)) {
-      const name = node.name.text
+      const name = node.name.text;
       if (shouldInclude(name)) {
-        const members = node.members.slice(0, 5).map((member) => getNodeText(member.name))
-        typeInfo.enums[name] = members
-        attachJSDoc(name, node)
+        const members = node.members
+          .slice(0, 5)
+          .map((member) => getNodeText(member.name));
+        typeInfo.enums[name] = members;
+        attachJSDoc(name, node);
       }
     }
 
     // Namespace/module declarations
     if (ts.isModuleDeclaration(node) && node.name) {
-      const name = getNodeText(node.name)
+      const name = getNodeText(node.name);
       if (shouldInclude(name)) {
-        typeInfo.namespaces[name] = true
-        attachJSDoc(name, node)
+        typeInfo.namespaces[name] = true;
+        attachJSDoc(name, node);
       }
     }
 
     // Variable statements (export const foo: Type)
     if (ts.isVariableStatement(node)) {
-      const isExported = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+      const isExported = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.ExportKeyword,
+      );
       if (isExported && node.declarationList.declarations) {
         for (const decl of node.declarationList.declarations) {
           if (ts.isIdentifier(decl.name)) {
-            const name = decl.name.text
+            const name = decl.name.text;
             if (shouldInclude(name) && decl.type) {
               // Check if it's a function type
               if (ts.isFunctionTypeNode(decl.type)) {
-                const params = formatParams(decl.type.parameters)
-                const returnType = formatType(decl.type.type, 60)
-                typeInfo.functions[name] = { params, returnType }
-                attachJSDoc(name, node)
+                const params = formatParams(decl.type.parameters);
+                const returnType = formatType(decl.type.type, 60);
+                typeInfo.functions[name] = { params, returnType };
+                attachJSDoc(name, node);
               }
             }
           }
@@ -326,16 +352,30 @@ export function parseDtsFile(dtsPath, filterList, visited = new Set()) {
 
     // export = Foo or export default Foo
     if (ts.isExportAssignment(node)) {
-      const assignment = getNodeText(node.expression)
+      const assignment = getNodeText(node.expression);
       if (assignment) {
-        typeInfo.defaults.push(assignment)
+        typeInfo.defaults.push(assignment);
       }
     }
 
-    ts.forEachChild(node, visit)
+    ts.forEachChild(node, visit);
   }
 
-  visit(sourceFile)
+  visit(sourceFile);
+
+  const mergeTypeInfo = (source) => {
+    if (!source) return;
+    Object.assign(typeInfo.functions, source.functions);
+    Object.assign(typeInfo.interfaces, source.interfaces);
+    Object.assign(typeInfo.types, source.types);
+    Object.assign(typeInfo.classes, source.classes);
+    Object.assign(typeInfo.enums, source.enums);
+    Object.assign(typeInfo.namespaces, source.namespaces);
+    Object.assign(typeInfo.jsdoc, source.jsdoc);
+    if (Array.isArray(source.defaults)) {
+      typeInfo.defaults.push(...source.defaults);
+    }
+  };
 
   // If we have a filter, try to follow re-exports for missing symbols
   if (filterList && filterList.length > 0) {
@@ -346,71 +386,57 @@ export function parseDtsFile(dtsPath, filterList, visited = new Set()) {
       ...Object.keys(typeInfo.classes),
       ...Object.keys(typeInfo.enums),
       ...Object.keys(typeInfo.namespaces),
-    ])
-    const missing = filterList.filter((name) => !found.has(name))
+    ]);
+    const missing = filterList.filter((name) => !found.has(name));
 
     if (missing.length > 0) {
-      const { named, wildcards } = findReExports(dtsPath, missing)
+      const { named, wildcards } = findReExports(dtsPath, missing);
 
       // Try named exports first
-      for (const [symbolName, sourcePath] of named) {
-        const subResult = parseDtsFile(sourcePath, [symbolName], visited)
-        if (subResult) {
-          Object.assign(typeInfo.functions, subResult.functions)
-          Object.assign(typeInfo.interfaces, subResult.interfaces)
-          Object.assign(typeInfo.types, subResult.types)
-          Object.assign(typeInfo.classes, subResult.classes)
-          Object.assign(typeInfo.enums, subResult.enums)
-          Object.assign(typeInfo.namespaces, subResult.namespaces)
-          Object.assign(typeInfo.jsdoc, subResult.jsdoc)
-          typeInfo.defaults.push(...subResult.defaults)
-        }
+      for (const [, sourcePath] of named) {
+        mergeTypeInfo(parseDtsFile(sourcePath, missing, visited));
       }
 
       // If still missing, try wildcard sources
-      if (wildcards.length > 0) {
-        for (const wildcardPath of wildcards) {
-          const subResult = parseDtsFile(wildcardPath, missing, visited)
-          if (subResult) {
-            Object.assign(typeInfo.functions, subResult.functions)
-          Object.assign(typeInfo.interfaces, subResult.interfaces)
-          Object.assign(typeInfo.types, subResult.types)
-          Object.assign(typeInfo.classes, subResult.classes)
-          Object.assign(typeInfo.enums, subResult.enums)
-          Object.assign(typeInfo.namespaces, subResult.namespaces)
-          Object.assign(typeInfo.jsdoc, subResult.jsdoc)
-          typeInfo.defaults.push(...subResult.defaults)
-        }
+      for (const wildcardPath of wildcards) {
+        mergeTypeInfo(parseDtsFile(wildcardPath, missing, visited));
       }
     }
-  }
+  } else if (!filterList) {
+    const { named, wildcards } = findReExports(dtsPath, null);
+    for (const [, sourcePath] of named) {
+      mergeTypeInfo(parseDtsFile(sourcePath, null, visited));
+    }
+    for (const wildcardPath of wildcards) {
+      mergeTypeInfo(parseDtsFile(wildcardPath, null, visited));
+    }
   }
 
-  return typeInfo
+  return typeInfo;
 }
 
 const isMain =
   typeof import.meta.main === "boolean"
     ? import.meta.main
-    : Boolean(process.argv?.[1] && process.argv[1].endsWith("parse-dts.mjs"))
+    : Boolean(process.argv?.[1] && process.argv[1].endsWith("parse-dts.mjs"));
 
 // CLI mode
 if (isMain) {
-  const dtsPath = process.argv[2]
-  const filter = process.argv[3]
+  const dtsPath = process.argv[2];
+  const filter = process.argv[3];
 
   if (!dtsPath) {
-    console.error("Usage: node parse-dts.mjs <path-to-dts> [filter]")
-    process.exit(1)
+    console.error("Usage: node parse-dts.mjs <path-to-dts> [filter]");
+    process.exit(1);
   }
 
-  const filterList = filter ? filter.split(",") : null
-  const result = parseDtsFile(dtsPath, filterList)
+  const filterList = filter ? filter.split(",") : null;
+  const result = parseDtsFile(dtsPath, filterList);
 
   if (result) {
-    console.log(JSON.stringify(result, null, 2))
+    console.log(JSON.stringify(result, null, 2));
   } else {
-    console.error("Failed to parse:", dtsPath)
-    process.exit(1)
+    console.error("Failed to parse:", dtsPath);
+    process.exit(1);
   }
 }