Merge pull request #490 from DashBot-0001/opt/verified-wins

perf+robustness: eight verified hot-path fixes for large graphs (tour-gen O(n²)→O(n), single-parse, louvain crash, …)

Author: Lum1104

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "understand-anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.1",
+  "version": "2.9.2",
   "author": {
     "name": "Egonex"
   },

.copilot-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "understand-anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.1",
+  "version": "2.9.2",
   "author": {
     "name": "Egonex"
   },

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "understand-anything",
   "displayName": "Understand Anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.1",
+  "version": "2.9.2",
   "author": {
     "name": "Egonex"
   },

understand-anything-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "understand-anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.1",
+  "version": "2.9.2",
   "author": {
     "name": "Egonex"
   },

understand-anything-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@understand-anything/skill",
-  "version": "2.9.1",
+  "version": "2.9.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

understand-anything-plugin/packages/core/src/__tests__/plugin-registry.test.ts

@@ -112,6 +112,38 @@ describe("PluginRegistry", () => {
     expect(result).toBeNull();
   });
 
+  it("analyzeFileFull delegates when the plugin implements it", () => {
+    const registry = new PluginRegistry();
+    const plugin = createMockPlugin("ts-plugin", ["typescript"]);
+    plugin.analyzeFileFull = () => ({
+      structure: {
+        ...emptyAnalysis,
+        functions: [{ name: "hello", lineRange: [1, 5], params: [] }],
+      },
+      callGraph: [{ caller: "hello", callee: "world", lineNumber: 2 }],
+    });
+    registry.register(plugin);
+
+    const result = registry.analyzeFileFull("src/test.ts", "const x = 1;");
+    expect(result).not.toBeNull();
+    expect(result!.structure.functions).toHaveLength(1);
+    expect(result!.callGraph).toHaveLength(1);
+  });
+
+  it("analyzeFileFull returns null when the plugin lacks the method (caller falls back)", () => {
+    const registry = new PluginRegistry();
+    registry.register(createMockPlugin("ts-plugin", ["typescript"]));
+    const result = registry.analyzeFileFull("src/test.ts", "const x = 1;");
+    expect(result).toBeNull();
+  });
+
+  it("analyzeFileFull returns null for unsupported files", () => {
+    const registry = new PluginRegistry();
+    registry.register(createMockPlugin("ts-plugin", ["typescript"]));
+    const result = registry.analyzeFileFull("main.py", "print('hello')");
+    expect(result).toBeNull();
+  });
+
   it("unregister rebuilds language map correctly", () => {
     const registry = new PluginRegistry();
     const plugin1 = createMockPlugin("plugin1", ["typescript", "javascript"]);

understand-anything-plugin/packages/core/src/analyzer/layer-detector.ts

@@ -104,24 +104,28 @@ function matchFileToLayer(filePath: string): string | null {
  */
 export function detectLayers(graph: KnowledgeGraph): Layer[] {
   const layerMap = new Map<string, string[]>(); // layerName -> nodeIds
+  // file nodes without filePath go to "Core" *after* the main pass, so a
+  // single sweep over graph.nodes replaces the previous two full passes while
+  // preserving the original ordering (all with-path entries first, then
+  // path-less ones) and the Map key-insertion order.
+  const corePathless: string[] = [];
 
   for (const node of graph.nodes) {
     if (node.type !== "file") continue;
-    if (!node.filePath) continue;
+    if (!node.filePath) {
+      corePathless.push(node.id);
+      continue;
+    }
 
     const layerName = matchFileToLayer(node.filePath) ?? "Core";
     const existing = layerMap.get(layerName) ?? [];
     existing.push(node.id);
     layerMap.set(layerName, existing);
   }
 
-  // Also catch file nodes without filePath
-  for (const node of graph.nodes) {
-    if (node.type !== "file") continue;
-    if (node.filePath) continue;
-
+  if (corePathless.length > 0) {
     const existing = layerMap.get("Core") ?? [];
-    existing.push(node.id);
+    for (const id of corePathless) existing.push(id);
     layerMap.set("Core", existing);
   }
 

understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts

@@ -165,8 +165,11 @@ export function generateHeuristicTour(graph: KnowledgeGraph): TourStep[] {
   }
 
   const topoOrder: string[] = [];
-  while (queue.length > 0) {
-    const current = queue.shift()!;
+  // Index cursor instead of queue.shift(): shift() is O(n) (re-indexes the
+  // whole array) → O(n²) over the BFS. A head pointer makes each dequeue O(1).
+  let head = 0;
+  while (head < queue.length) {
+    const current = queue[head++];
     topoOrder.push(current);
 
     for (const neighbor of adjacency.get(current) ?? []) {
@@ -178,10 +181,15 @@ export function generateHeuristicTour(graph: KnowledgeGraph): TourStep[] {
     }
   }
 
-  // Add any nodes not reached by topological sort (isolated nodes or cycles)
+  // Add any nodes not reached by topological sort (isolated nodes or cycles).
+  // `topoOrder.includes()` per node was O(n²) over the full node set; a Set
+  // membership test makes it O(n). Mirror the array-grows semantics by adding
+  // to the set on push so a duplicate node id is still de-duplicated.
+  const inTopo = new Set(topoOrder);
   for (const node of codeNodes) {
-    if (!topoOrder.includes(node.id)) {
+    if (!inTopo.has(node.id)) {
       topoOrder.push(node.id);
+      inTopo.add(node.id);
     }
   }
 

understand-anything-plugin/packages/core/src/embedding-search.ts

@@ -29,6 +29,30 @@ export function cosineSimilarity(a: number[], b: number[]): number {
   return dot / (magA * magB);
 }
 
+/**
+ * Cosine similarity when the query vector's magnitude is already known.
+ * The query is constant across an entire search() sweep, so recomputing its
+ * magnitude (and re-squaring every query component) per candidate node is
+ * pure waste. Same arithmetic, same order as cosineSimilarity → bit-identical
+ * results, but it skips the per-node magA loop.
+ */
+function cosineSimilarityWithQueryMag(
+  query: number[],
+  queryMag: number,
+  vec: number[],
+): number {
+  if (queryMag === 0) return 0;
+  let dot = 0;
+  let magB = 0;
+  for (let i = 0; i < query.length; i++) {
+    dot += query[i] * vec[i];
+    magB += vec[i] * vec[i];
+  }
+  magB = Math.sqrt(magB);
+  if (magB === 0) return 0;
+  return dot / (queryMag * magB);
+}
+
 /**
  * Semantic search engine using vector embeddings.
  * Stores pre-computed embeddings for graph nodes and performs
@@ -61,13 +85,24 @@ export class SemanticSearchEngine {
 
     const scored: Array<{ nodeId: string; score: number }> = [];
 
+    // Hoist the query magnitude out of the per-node loop — it's invariant.
+    let queryMag = 0;
+    for (let i = 0; i < queryEmbedding.length; i++) {
+      queryMag += queryEmbedding[i] * queryEmbedding[i];
+    }
+    queryMag = Math.sqrt(queryMag);
+
     for (const node of this.nodes) {
       if (typeFilter && !typeFilter.includes(node.type)) continue;
 
       const embedding = this.embeddings.get(node.id);
       if (!embedding) continue;
 
-      const similarity = cosineSimilarity(queryEmbedding, embedding);
+      const similarity = cosineSimilarityWithQueryMag(
+        queryEmbedding,
+        queryMag,
+        embedding,
+      );
       if (similarity >= threshold) {
         scored.push({ nodeId: node.id, score: 1 - similarity });
       }

understand-anything-plugin/packages/core/src/plugins/registry.ts

@@ -71,6 +71,20 @@ export class PluginRegistry {
     return plugin.extractCallGraph(filePath, content);
   }
 
+  /**
+   * Single-parse fast path: returns both structure and call graph from one
+   * parse when the resolved plugin supports it, else null so the caller can
+   * fall back to separate analyzeFile + extractCallGraph calls.
+   */
+  analyzeFileFull(
+    filePath: string,
+    content: string,
+  ): { structure: StructuralAnalysis; callGraph: CallGraphEntry[] } | null {
+    const plugin = this.getPluginForFile(filePath);
+    if (!plugin?.analyzeFileFull) return null;
+    return plugin.analyzeFileFull(filePath, content);
+  }
+
   getPlugins(): AnalyzerPlugin[] {
     return [...this.plugins];
   }