@comfanion/usethis_search 4.3.1 → 4.5.0

package/tools/graph.ts

@@ -0,0 +1,265 @@
+/**
+ * Graph Exploration Tool
+ *
+ * explore — navigate the code knowledge graph from a chunk/file node.
+ *   Shows all edges (imports, extends, used_by, similar_to, has_method, etc.)
+ *   and auto-attaches neighbor chunks to workspace.
+ */
+
+import { tool } from "@opencode-ai/plugin"
+
+import { getIndexer, releaseIndexer } from "../vectorizer/index.ts"
+import { workspaceCache } from "../cache/manager.ts"
+import { buildWorkspaceOutput } from "./workspace-state.ts"
+import { isStructuralPredicate } from "../vectorizer/graph-builder.ts"
+import type { Triple } from "../vectorizer/graph-db.ts"
+
+// ── explore ─────────────────────────────────────────────────────────────────
+
+export const explore = tool({
+  description: `Explore code connections from a chunk or file using the knowledge graph.
+
+Shows all graph edges (imports, extends, used_by, calls, similar_to, has_method, contains)
+and auto-attaches neighbor chunks to workspace for deeper exploration.
+
+USE THIS WHEN:
+- You found a chunk via search() and want to see what it imports/extends/calls
+- You want to understand dependencies of a file or function
+- You need to navigate from a known symbol to related code
+- You want to explore "who uses this?" (incoming edges)
+
+The graph contains edges built from:
+- Static analysis: imports, extends, implements, calls
+- Structural: file → class → method hierarchy
+- Semantic similarity: similar_to (high cosine similarity between chunks)
+
+Workflow:
+1. search({ query: "authentication" }) → find relevant chunks
+2. explore({ node: "chunk:src/auth.ts::AuthService" }) → see imports, methods, callers
+3. explore({ node: "chunk:src/types/User.ts::User" }) → go deeper into dependencies
+4. search({ queries: ["chunk:src/auth.ts::login", "src/types/User.ts"] }) → attach specific items
+
+The node parameter accepts:
+- Chunk ID from search results: "chunk:src/auth.ts::AuthService"
+- File node: "file:src/auth.ts" (shows all edges for the file)
+- Short file path: "src/auth.ts" (auto-prefixed to "file:src/auth.ts")
+
+Examples:
+- explore({ node: "chunk:src/auth.ts::login" })
+- explore({ node: "file:src/auth.ts" })
+- explore({ node: "src/auth.ts" })
+- explore({ node: "chunk:src/auth.ts::AuthService", depth: 2 })`,
+
+  args: {
+    node: tool.schema.string().describe("Chunk ID, file node, or file path to explore"),
+    depth: tool.schema.number().optional().describe("Graph depth (default: 1, max: 2)"),
+    index: tool.schema.string().optional().default("code").describe("Which index to use (default: 'code')"),
+  },
+
+  async execute(args) {
+    const projectRoot = process.cwd()
+    const depth = Math.min(args.depth ?? 1, 2)
+    const indexName = args.index || "code"
+
+    // Normalize node ID
+    let nodeId = args.node
+    if (!nodeId.startsWith("chunk:") && !nodeId.startsWith("file:") && !nodeId.startsWith("meta:")) {
+      nodeId = `file:${nodeId}`
+    }
+
+    const indexer = await getIndexer(projectRoot, indexName)
+    try {
+      const graphDB = (indexer as any).graphDB
+      if (!graphDB) {
+        return `Graph not available for index "${indexName}". The index may not have been built with graph support.`
+      }
+
+      // Collect edges via BFS at requested depth
+      const visited = new Set<string>()
+      const allEdges: Array<{
+        from: string
+        predicate: string
+        to: string
+        weight: number
+        direction: "outgoing" | "incoming"
+        depth: number
+      }> = []
+
+      const queue: Array<{ id: string; currentDepth: number }> = [{ id: nodeId, currentDepth: 0 }]
+
+      while (queue.length > 0) {
+        const { id, currentDepth } = queue.shift()!
+        if (visited.has(id) || currentDepth >= depth) continue
+        visited.add(id)
+
+        try {
+          const [outgoing, incoming]: [Triple[], Triple[]] = await Promise.all([
+            graphDB.getOutgoing(id),
+            graphDB.getIncoming(id),
+          ])
+
+          for (const t of outgoing) {
+            if (t.predicate === "graph_built") continue
+            allEdges.push({
+              from: id,
+              predicate: t.predicate,
+              to: t.object,
+              weight: t.weight,
+              direction: "outgoing",
+              depth: currentDepth,
+            })
+            if (currentDepth + 1 < depth && !isStructuralPredicate(t.predicate) && t.predicate !== "belongs_to") {
+              queue.push({ id: t.object, currentDepth: currentDepth + 1 })
+            }
+          }
+
+          for (const t of incoming) {
+            if (t.predicate === "graph_built") continue
+            allEdges.push({
+              from: t.subject,
+              predicate: t.predicate,
+              to: id,
+              weight: t.weight,
+              direction: "incoming",
+              depth: currentDepth,
+            })
+            if (currentDepth + 1 < depth && !isStructuralPredicate(t.predicate) && t.predicate !== "belongs_to") {
+              queue.push({ id: t.subject, currentDepth: currentDepth + 1 })
+            }
+          }
+        } catch {
+          // Node may not exist in graph — skip
+        }
+      }
+
+      if (allEdges.length === 0) {
+        return `No graph edges found for "${nodeId}".\n\nMake sure:\n1. The node ID is correct (use chunk IDs from search results)\n2. The file is indexed with graph support\n3. Try "file:path" format for file-level edges` + buildWorkspaceOutput()
+      }
+
+      // Group edges
+      const outgoing = allEdges.filter(e => e.direction === "outgoing" && e.from === nodeId)
+      const incoming = allEdges.filter(e => e.direction === "incoming" && e.to === nodeId)
+      const deeper = allEdges.filter(e => e.depth > 0)
+
+      // ── Auto-attach neighbor chunks ────────────────────────────────────
+      const attachedChunks: string[] = []
+      const neighborChunkIds = new Set<string>()
+
+      for (const edge of allEdges) {
+        const targetId = edge.direction === "outgoing" ? edge.to : edge.from
+        if (targetId !== nodeId && targetId.startsWith("chunk:")) {
+          neighborChunkIds.add(targetId)
+        }
+      }
+
+      for (const chunkId of neighborChunkIds) {
+        if (workspaceCache.has(chunkId)) continue
+
+        try {
+          const chunk = await indexer.findChunkById(chunkId)
+          if (chunk && chunk.content) {
+            workspaceCache.attach({
+              chunkId,
+              path: chunk.file,
+              content: chunk.content,
+              chunkIndex: chunk.chunk_index ?? 0,
+              role: "search-graph",
+              attachedAt: Date.now(),
+              attachedBy: `explore(${nodeId})`,
+              metadata: {
+                language: chunk.language,
+                function_name: chunk.function_name,
+                class_name: chunk.class_name,
+                startLine: chunk.start_line,
+                endLine: chunk.end_line,
+                relation: "graph_neighbor",
+                mainChunkId: nodeId,
+              },
+            })
+            attachedChunks.push(chunkId)
+          }
+        } catch {
+          // Chunk not found — skip
+        }
+      }
+
+      if (attachedChunks.length > 0) {
+        workspaceCache.save().catch(() => {})
+      }
+
+      // ── Build output ──────────────────────────────────────────────────
+      let output = `## Explore: ${nodeId}\n\n`
+
+      if (outgoing.length > 0) {
+        output += `### Outgoing (${nodeId} →)\n\n`
+        const byPredicate = new Map<string, typeof outgoing>()
+        for (const e of outgoing) {
+          const arr = byPredicate.get(e.predicate) || []
+          arr.push(e)
+          byPredicate.set(e.predicate, arr)
+        }
+        for (const [predicate, edges] of byPredicate) {
+          output += `**${predicate}** (${edges.length}):\n`
+          for (const e of edges.sort((a, b) => b.weight - a.weight)) {
+            const inWs = workspaceCache.has(e.to) ? " ✓ws" : ""
+            output += `- → ${e.to} (weight: ${e.weight.toFixed(2)})${inWs}\n`
+          }
+          output += `\n`
+        }
+      }
+
+      if (incoming.length > 0) {
+        output += `### Incoming (→ ${nodeId})\n\n`
+        const byPredicate = new Map<string, typeof incoming>()
+        for (const e of incoming) {
+          const arr = byPredicate.get(e.predicate) || []
+          arr.push(e)
+          byPredicate.set(e.predicate, arr)
+        }
+        for (const [predicate, edges] of byPredicate) {
+          output += `**${predicate}** (${edges.length}):\n`
+          for (const e of edges.sort((a, b) => b.weight - a.weight)) {
+            const inWs = workspaceCache.has(e.from) ? " ✓ws" : ""
+            output += `- ← ${e.from} (weight: ${e.weight.toFixed(2)})${inWs}\n`
+          }
+          output += `\n`
+        }
+      }
+
+      if (deeper.length > 0) {
+        output += `### Depth 2 (${deeper.length} edges)\n\n`
+        for (const e of deeper.slice(0, 20)) {
+          const arrow = e.direction === "outgoing" ? "→" : "←"
+          output += `- ${e.from} ${arrow} **${e.predicate}** ${arrow} ${e.to}\n`
+        }
+        if (deeper.length > 20) {
+          output += `- ... and ${deeper.length - 20} more\n`
+        }
+        output += `\n`
+      }
+
+      output += `---\n`
+      output += `**Summary:** ${outgoing.length} outgoing, ${incoming.length} incoming`
+      if (deeper.length > 0) output += `, ${deeper.length} at depth 2`
+      output += `\n`
+
+      if (attachedChunks.length > 0) {
+        output += `**Attached ${attachedChunks.length} neighbor chunk(s) to workspace.**\n`
+      }
+
+      output += `\n**Next:**\n`
+      if (neighborChunkIds.size > 0) {
+        const example = [...neighborChunkIds][0]
+        output += `- Go deeper: \`explore({ node: "${example}" })\`\n`
+      }
+      output += `- Attach chunks: \`search({ queries: ["chunk-id-1", "chunk-id-2"] })\`\n`
+      output += `- Clean up: \`forget({ queries: ["old-file.ts", "5"] })\`\n`
+
+      output += buildWorkspaceOutput()
+      return output
+
+    } finally {
+      releaseIndexer(projectRoot, indexName)
+    }
+  },
+})

package/tools/read-interceptor.ts

@@ -2,7 +2,7 @@ import { tool } from "@opencode-ai/plugin"
 import path from "path"
 import fs from "fs/promises"
 
-import { CodebaseIndexer } from "../vectorizer/index.ts"
+import { getIndexer, releaseIndexer } from "../vectorizer/index.ts"
 
 // FR-043: Logging for intercepted Read() calls
 const DEBUG = process.env.DEBUG?.includes("vectorizer") || process.env.DEBUG === "*"
@@ -48,6 +48,9 @@ async function logReadInterception(projectRoot: string, entry: ReadLogEntry): Pr
   }
 }
 
+// STATUS: DISABLED — not registered in plugin index.ts tool:{} map.
+// The workspace-injection approach (v6) handles read context.
+// Kept for potential future re-enablement.
 export default tool({
   description: `Read file with graph-aware context attachment. When available, this tool searches the file in the index and returns content + related context from the graph (imports, links, etc.).
 
@@ -74,7 +77,7 @@ Use this instead of the standard Read tool for better context awareness.`,
     let searchFailed = false
 
     try {
-      const indexer = await new CodebaseIndexer(projectRoot, "code").init()
+      const indexer = await getIndexer(projectRoot, "code")
       try {
         const results = await indexer.search(relPath, 20, false, {})
         fileChunks = results.filter((r: any) => r.file === relPath)
@@ -87,8 +90,9 @@ Use this instead of the standard Read tool for better context awareness.`,
           console.log(`[read-interceptor] Search failed for "${relPath}": ${searchErr.message}`)
         }
         searchFailed = true
+      } finally {
+        releaseIndexer(projectRoot, "code")
       }
-      await indexer.unloadModel()
     } catch (initErr: any) {
       if (DEBUG) {
         console.log(`[read-interceptor] Indexer init failed: ${initErr.message}`)