@aiready/ast-mcp-server 0.4.0 → 0.4.2

package/dist/index.js

@@ -55,6 +55,10 @@ var GetCallHierarchySchema = z.object({
   path: z.string().describe("Project root directory"),
   direction: z.enum(["incoming", "outgoing", "both"]).optional().default("both").describe("Direction of calls (default: both)")
 });
+var CheckSymbolGroundingSchema = z.object({
+  symbol: z.string().describe("Symbol name to assess grounding for"),
+  path: z.string().describe("Project root directory")
+});
 
 // src/adapters/typescript-adapter.ts
 import { Node as Node2 } from "ts-morph";
@@ -238,7 +242,7 @@ var SymbolIndex = class {
     const startTime = Date.now();
     const safeRoot = validateWorkspacePath(rootDir);
     const cachePath = this.getCachePath(safeRoot);
-    if (fs2.existsSync(cachePath)) {
+    if (fs2.existsSync(cachePath) && process.env.AST_DISABLE_CACHE !== "true") {
       try {
         const cached = JSON.parse(
           fs2.readFileSync(cachePath, "utf-8")
@@ -348,6 +352,7 @@ var WorkerPool = class {
   constructor(poolSize) {
     this.poolSize = poolSize;
   }
+  poolSize;
   workers = [];
   available = [];
   queue = [];
@@ -358,8 +363,8 @@ var WorkerPool = class {
     const workerPath = path3.join(__dirname2, "ast-worker.js");
     for (let i = 0; i < this.poolSize; i++) {
       const worker = new Worker(workerPath);
-      worker.on("message", (msg) => this.handleResult(msg));
-      worker.on("error", (err) => this.handleWorkerError(worker, err));
+      worker.on("message", (msg) => this.handleResult(worker, msg));
+      worker.on("error", (_err) => this.handleWorkerError(worker, _err));
       this.workers.push(worker);
       this.available.push(worker);
     }
@@ -380,7 +385,7 @@ var WorkerPool = class {
     this.activeJobs.set(task.id, task);
     worker.postMessage({ id: task.id, type: task.type, payload: task.payload });
   }
-  handleResult(msg) {
+  handleResult(worker, msg) {
     const task = this.activeJobs.get(msg.id);
     if (!task) return;
     this.activeJobs.delete(msg.id);
@@ -389,6 +394,12 @@ var WorkerPool = class {
     } else {
       task.resolve(msg.result);
     }
+    const nextTask = this.queue.shift();
+    if (nextTask) {
+      this.dispatch(worker, nextTask);
+    } else {
+      this.available.push(worker);
+    }
   }
   handleWorkerError(worker, err) {
     const idx = this.workers.indexOf(worker);
@@ -397,7 +408,7 @@ var WorkerPool = class {
       const __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
       const workerPath = path3.join(__dirname2, "ast-worker.js");
       const newWorker = new Worker(workerPath);
-      newWorker.on("message", (msg) => this.handleResult(msg));
+      newWorker.on("message", (msg) => this.handleResult(newWorker, msg));
       newWorker.on("error", (_e) => this.handleWorkerError(newWorker, _e));
       this.workers[idx] = newWorker;
       this.available.push(newWorker);
@@ -496,16 +507,12 @@ var TypeScriptAdapter = class {
     const project = projectManager.ensureProject(tsconfig);
     const sourceFile = project.addSourceFileAtPathIfExists(hit.file);
     if (!sourceFile) return { references: [], total_count: 0 };
-    const exported = sourceFile.getExportedDeclarations().get(symbolName);
-    if (!exported || exported.length === 0)
-      return { references: [], total_count: 0 };
-    const targetNode = exported[0];
     try {
       const { searchCode: searchCode2 } = await import("./search-code-63QOEFQN.js");
       const searchResults = await searchCode2(
         symbolName,
         path5,
-        "*.{ts,tsx,js,jsx}",
+        "**/*.{ts,tsx,js,jsx}",
         1e3,
         false
       );
@@ -513,8 +520,13 @@ var TypeScriptAdapter = class {
       for (const file of filesToLoad) {
         project.addSourceFileAtPathIfExists(file);
       }
+      project.resolveSourceFileDependencies();
     } catch (_e) {
     }
+    const exported = sourceFile.getExportedDeclarations().get(symbolName);
+    if (!exported || exported.length === 0)
+      return { references: [], total_count: 0 };
+    const targetNode = exported[0];
     const refSymbols = "findReferences" in targetNode && typeof targetNode.findReferences === "function" ? targetNode.findReferences() : void 0;
     if (!refSymbols) return { references: [], total_count: 0 };
     const results = [];
@@ -570,7 +582,7 @@ var TypeScriptAdapter = class {
         const searchResults = await searchCode2(
           symbolName,
           path5,
-          "*.{ts,tsx,js,jsx}",
+          "**/*.{ts,tsx,js,jsx}",
           1e3,
           false
         );
@@ -747,19 +759,30 @@ var TypeScriptAdapter = class {
 };
 var typescriptAdapter = new TypeScriptAdapter();
 
+// src/utils/tool-utils.ts
+async function wrapAdapterCall(methodName, symbol, path5, ...args) {
+  const method = typescriptAdapter[methodName];
+  return await method.apply(typescriptAdapter, [symbol, path5, ...args]);
+}
+
 // src/tools/resolve-definition.ts
 async function resolveDefinition(symbol, path5) {
-  return await typescriptAdapter.resolveDefinition(symbol, path5);
+  return await wrapAdapterCall(
+    "resolveDefinition",
+    symbol,
+    path5
+  );
 }
 
 // src/tools/find-references.ts
 async function findReferences(symbol, path5, limit = 50, offset = 0) {
-  return await typescriptAdapter.findReferences(symbol, path5, limit, offset);
+  return await wrapAdapterCall("findReferences", symbol, path5, limit, offset);
 }
 
 // src/tools/find-implementations.ts
 async function findImplementations(symbol, path5, limit = 50, offset = 0) {
-  return await typescriptAdapter.findImplementations(
+  return await wrapAdapterCall(
+    "findImplementations",
     symbol,
     path5,
     limit,
@@ -880,6 +903,84 @@ async function getCallHierarchy(symbolName, rootDir, direction = "both") {
   return results;
 }
 
+// src/tools/check-symbol-grounding.ts
+import { SyntaxKind as SyntaxKind3 } from "ts-morph";
+async function checkSymbolGrounding(symbol, filePath) {
+  const safePath = validateWorkspacePath(filePath);
+  const tsconfig = await projectManager.findNearestTsConfig(safePath);
+  if (!tsconfig) return void 0;
+  const project = projectManager.ensureProject(tsconfig);
+  const sourceFile = project.addSourceFileAtPathIfExists(safePath);
+  if (!sourceFile) return void 0;
+  const node = sourceFile.getDescendantsOfKind(SyntaxKind3.Identifier).find((id) => id.getText() === symbol);
+  if (!node) return void 0;
+  const decl = node.getSymbol()?.getDeclarations()?.[0];
+  if (!decl) return void 0;
+  let docScore = 0;
+  let typeScore = 0;
+  let depthScore = 30;
+  const recommendations = [];
+  const docs = typescriptAdapter.getSymbolDocs(decl);
+  if (docs) {
+    docScore += 10;
+    if (docs.documentation && docs.documentation.length > 20) docScore += 10;
+    const hasParams = docs.tags.some((t) => t.name === "param");
+    const hasReturns = docs.tags.some(
+      (t) => t.name === "returns" || t.name === "return"
+    );
+    if (hasParams) docScore += 10;
+    else
+      recommendations.push(
+        "Add @param tags to document implementation details for the agent."
+      );
+    if (hasReturns) docScore += 10;
+    else
+      recommendations.push("Add @returns tag to clarify output expectations.");
+  } else {
+    recommendations.push(
+      "Missing JSDoc. Agents need explicit documentation to understand intent without reading the source."
+    );
+  }
+  const typeText = decl.getType?.()?.getText?.() || "";
+  if (typeText) {
+    if (!typeText.includes("any")) typeScore += 15;
+    else
+      recommendations.push(
+        'Avoid "any" types. They break agentic reasoning and cause hallucinations.'
+      );
+    if (!typeText.includes("unknown")) typeScore += 15;
+    else
+      recommendations.push(
+        'Use specific interfaces instead of "unknown" to minimize agent probe requirements.'
+      );
+  }
+  const importCount = sourceFile.getImportDeclarations().length;
+  if (importCount > 10) {
+    const penalty = Math.min(20, (importCount - 10) * 2);
+    depthScore -= penalty;
+    recommendations.push(
+      `High dependency depth (${importCount} imports). Agents must load more files to understand this symbol's context.`
+    );
+  }
+  const totalScore = docScore + typeScore + depthScore;
+  let grade = "F";
+  if (totalScore >= 90) grade = "S (Agent-Native)";
+  else if (totalScore >= 80) grade = "A (Highly Grounded)";
+  else if (totalScore >= 70) grade = "B (Good)";
+  else if (totalScore >= 60) grade = "C (Acceptable)";
+  else if (totalScore >= 40) grade = "D (Poor)";
+  return {
+    score: totalScore,
+    grade,
+    breakdown: {
+      documentation: docScore,
+      typeClarity: typeScore,
+      depthImpact: depthScore
+    },
+    recommendations
+  };
+}
+
 // src/index.ts
 import {
   ListResourcesRequestSchema,
@@ -1046,16 +1147,28 @@ var ASTExplorerServer = class {
             inputSchema: {
               type: "object",
               properties: {
-                symbol: { type: "string", description: "Symbol name" },
-                path: { type: "string", description: "Project root" },
+                symbol: { type: "string" },
+                path: { type: "string" },
                 direction: {
                   type: "string",
-                  enum: ["incoming", "outgoing", "both"],
-                  default: "both"
+                  enum: ["incoming", "outgoing"],
+                  default: "outgoing"
                 }
               },
               required: ["symbol", "path"]
             }
+          },
+          {
+            name: "check_symbol_grounding",
+            description: "Assess a symbol's AI grounding quality (docs, type clarity, depth).",
+            inputSchema: {
+              type: "object",
+              properties: {
+                symbol: { type: "string" },
+                path: { type: "string" }
+              },
+              required: ["symbol", "path"]
+            }
           }
         ]
       };
@@ -1144,6 +1257,15 @@ var ASTExplorerServer = class {
               ]
             };
           }
+          case "check_symbol_grounding": {
+            const { symbol, path: path5 } = CheckSymbolGroundingSchema.parse(args);
+            const result = await checkSymbolGrounding(symbol, path5);
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(result, null, 2) }
+              ]
+            };
+          }
           default:
             throw new Error(`Unknown tool: ${name}`);
         }