forge-server 0.1.0

package/src/tools/graph-tools.ts

@@ -0,0 +1,295 @@
+// graph-tools.ts — Swarm Learning Phase 1
+// MCP tool handlers for graph-based code analysis.
+// Tools: get_impact_graph, search_logic_flow
+
+import { z } from 'zod';
+import type { GraphStore } from '../storage/interfaces.js';
+import {
+  QUERY_INBOUND_IMPACT,
+  QUERY_OUTBOUND_IMPACT,
+  QUERY_SHORTEST_PATH,
+} from '../query/graph-queries.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const getImpactGraphSchema = z.object({
+  symbol: z.string().min(1, 'symbol name is required'),
+  repo_id: z.string().min(1, 'repo_id is required'),
+  direction: z.enum(['inbound', 'outbound', 'both']).default('both'),
+  depth: z.number().int().min(1).max(5).default(3),
+});
+
+export const searchLogicFlowSchema = z.object({
+  from_symbol: z.string().min(1, 'from_symbol is required'),
+  to_symbol: z.string().min(1, 'to_symbol is required'),
+  repo_id: z.string().min(1, 'repo_id is required'),
+  max_depth: z.number().int().min(1).max(10).default(5),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createGraphTools(graphStore: GraphStore | null) {
+  return {
+    'get_impact_graph': {
+      schema: getImpactGraphSchema,
+      description: 'Get the impact graph (callers/dependents) for a code symbol. PREFER THIS over manual Grep for "who uses X" questions — it traverses the actual call/import graph with depth control, not just text matches. Requires FalkorDB graph store.',
+      handler: async (input: z.infer<typeof getImpactGraphSchema>) => {
+        if (!graphStore) {
+          return {
+            error: 'GRAPH_UNAVAILABLE',
+            message: 'FalkorDB graph store is not available. Impact graph requires a running FalkorDB instance.',
+          };
+        }
+
+        const healthy = await graphStore.isHealthy();
+        if (!healthy) {
+          return {
+            error: 'GRAPH_UNAVAILABLE',
+            message: 'FalkorDB is not healthy. Impact graph unavailable.',
+          };
+        }
+
+        try {
+          const nodes: Array<{ name: string; label: string; file_path?: string }> = [];
+          const edges: Array<{ from: string; to: string; type: string; depth: number }> = [];
+
+          // Inbound: who calls/imports/uses this symbol?
+          if (input.direction === 'inbound' || input.direction === 'both') {
+            try {
+              const result = await graphStore.query(
+                QUERY_INBOUND_IMPACT(input.symbol, input.repo_id, input.depth)
+              );
+              parseImpactResult(result, nodes, edges, 'inbound');
+            } catch (err) {
+              logger.warn('get_impact_graph: inbound query failed', { error: String(err) });
+            }
+          }
+
+          // Outbound: what does this symbol depend on?
+          if (input.direction === 'outbound' || input.direction === 'both') {
+            try {
+              const result = await graphStore.query(
+                QUERY_OUTBOUND_IMPACT(input.symbol, input.repo_id, input.depth)
+              );
+              parseImpactResult(result, nodes, edges, 'outbound');
+            } catch (err) {
+              logger.warn('get_impact_graph: outbound query failed', { error: String(err) });
+            }
+          }
+
+          // Deduplicate nodes by name
+          const uniqueNodes = deduplicateNodes(nodes);
+
+          logger.debug('graph-tools.get_impact_graph: completed', {
+            symbol: input.symbol,
+            direction: input.direction,
+            nodes: uniqueNodes.length,
+            edges: edges.length,
+          });
+
+          return {
+            symbol: input.symbol,
+            direction: input.direction,
+            nodes: uniqueNodes,
+            edges,
+            total_nodes: uniqueNodes.length,
+            total_edges: edges.length,
+          };
+        } catch (err) {
+          logger.error('graph-tools.get_impact_graph: error', { error: String(err) });
+          return {
+            error: 'GET_IMPACT_GRAPH_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'search_logic_flow': {
+      schema: searchLogicFlowSchema,
+      description: 'Find the shortest path between two code symbols in the call/dependency graph. Use this to understand how data or control flows from A to B through the codebase — much faster than manually tracing imports. Requires FalkorDB graph store.',
+      handler: async (input: z.infer<typeof searchLogicFlowSchema>) => {
+        if (!graphStore) {
+          return {
+            error: 'GRAPH_UNAVAILABLE',
+            message: 'FalkorDB graph store is not available. Logic flow search requires a running FalkorDB instance.',
+          };
+        }
+
+        const healthy = await graphStore.isHealthy();
+        if (!healthy) {
+          return {
+            error: 'GRAPH_UNAVAILABLE',
+            message: 'FalkorDB is not healthy. Logic flow search unavailable.',
+          };
+        }
+
+        try {
+          const result = await graphStore.query(
+            QUERY_SHORTEST_PATH(input.from_symbol, input.to_symbol, input.repo_id, input.max_depth)
+          );
+
+          const paths = parsePathResult(result);
+
+          logger.debug('graph-tools.search_logic_flow: completed', {
+            from: input.from_symbol,
+            to: input.to_symbol,
+            pathCount: paths.length,
+          });
+
+          return {
+            from_symbol: input.from_symbol,
+            to_symbol: input.to_symbol,
+            paths,
+            connected: paths.length > 0,
+          };
+        } catch (err) {
+          logger.error('graph-tools.search_logic_flow: error', { error: String(err) });
+          return {
+            error: 'SEARCH_LOGIC_FLOW_FAILED',
+            message: String(err),
+            from_symbol: input.from_symbol,
+            to_symbol: input.to_symbol,
+            paths: [],
+            connected: false,
+          };
+        }
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Result parsers for FalkorDB raw responses
+// ---------------------------------------------------------------------------
+
+interface GraphQueryResult {
+  nodes: Array<{ label: string; properties: Record<string, unknown> }>;
+  edges: Array<{ type: string; from: string; to: string; properties?: Record<string, unknown> }>;
+  raw?: unknown[];
+}
+
+function parseImpactResult(
+  result: GraphQueryResult,
+  nodes: Array<{ name: string; label: string; file_path?: string }>,
+  edges: Array<{ from: string; to: string; type: string; depth: number }>,
+  _direction: 'inbound' | 'outbound',
+): void {
+  // Parse nodes from the result
+  for (const node of result.nodes ?? []) {
+    const name = String(node.properties?.['name'] ?? '');
+    const filePath = node.properties?.['file_path'] as string | undefined;
+    if (name) {
+      nodes.push({ name, label: node.label, file_path: filePath });
+    }
+  }
+
+  // Parse edges from the result
+  for (const edge of result.edges ?? []) {
+    edges.push({
+      from: edge.from,
+      to: edge.to,
+      type: edge.type,
+      depth: 1,
+    });
+  }
+
+  // Also try to parse from raw results (FalkorDB returns varying formats)
+  for (const row of result.raw ?? []) {
+    if (!row || !Array.isArray(row)) continue;
+
+    // Expected columns: [caller/dep, relationship_array, depth]
+    const entity = row[0];
+    const depth = typeof row[2] === 'number' ? row[2] : 1;
+
+    if (entity && typeof entity === 'object') {
+      const props = (entity as Record<string, unknown>).properties as Record<string, unknown> | undefined;
+      if (props) {
+        const name = String(props['name'] ?? '');
+        const filePath = props['file_path'] as string | undefined;
+        if (name) {
+          nodes.push({ name, label: 'unknown', file_path: filePath });
+        }
+      }
+    }
+  }
+}
+
+function parsePathResult(
+  result: GraphQueryResult,
+): Array<{ nodes: string[]; edges: string[]; length: number }> {
+  const paths: Array<{ nodes: string[]; edges: string[]; length: number }> = [];
+
+  // Try to parse from raw results
+  for (const row of result.raw ?? []) {
+    if (!row) continue;
+
+    // The QUERY_SHORTEST_PATH returns path objects
+    // Different FalkorDB parsers represent these differently
+    if (Array.isArray(row)) {
+      const pathObj = row[0];
+      if (pathObj && typeof pathObj === 'object') {
+        const pathNodes: string[] = [];
+        const pathEdges: string[] = [];
+
+        // Extract from FalkorDB path representation
+        const pNodes = (pathObj as Record<string, unknown>).nodes as Array<Record<string, unknown>> | undefined;
+        const pEdges = (pathObj as Record<string, unknown>).edges as Array<Record<string, unknown>> | undefined;
+
+        if (pNodes) {
+          for (const n of pNodes) {
+            const props = n.properties as Record<string, unknown> | undefined;
+            pathNodes.push(String(props?.['name'] ?? 'unknown'));
+          }
+        }
+
+        if (pEdges) {
+          for (const e of pEdges) {
+            pathEdges.push(String(e.type ?? e.relation ?? 'unknown'));
+          }
+        }
+
+        if (pathNodes.length > 0) {
+          paths.push({
+            nodes: pathNodes,
+            edges: pathEdges,
+            length: pathNodes.length - 1,
+          });
+        }
+      }
+    }
+  }
+
+  // Fallback: build from the standard node/edge arrays
+  if (paths.length === 0 && (result.nodes.length > 0 || result.edges.length > 0)) {
+    const nodeNames = result.nodes.map(n => String(n.properties?.['name'] ?? 'unknown'));
+    const edgeTypes = result.edges.map(e => e.type);
+
+    if (nodeNames.length > 0) {
+      paths.push({
+        nodes: nodeNames,
+        edges: edgeTypes,
+        length: Math.max(0, nodeNames.length - 1),
+      });
+    }
+  }
+
+  return paths;
+}
+
+function deduplicateNodes(
+  nodes: Array<{ name: string; label: string; file_path?: string }>,
+): Array<{ name: string; label: string; file_path?: string }> {
+  const seen = new Map<string, { name: string; label: string; file_path?: string }>();
+  for (const node of nodes) {
+    if (!seen.has(node.name)) {
+      seen.set(node.name, node);
+    }
+  }
+  return Array.from(seen.values());
+}

package/src/tools/ingestion-tools.ts

@@ -0,0 +1,122 @@
+// ingestion-tools.ts — Swarm Learning Phase 4
+// MCP tool handlers for ingesting external data into the graph store.
+// Tools: submit_lsp_edges
+// Designed for VS Code extension and CI pipelines to push type-resolved
+// call edges that supplement the static AST parsing.
+
+import { z } from 'zod';
+import type { GraphStore } from '../storage/interfaces.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+const lspEdgeSchema = z.object({
+  from_file: z.string().min(1),
+  from_symbol: z.string().min(1),
+  to_file: z.string().min(1),
+  to_symbol: z.string().min(1),
+  edge_type: z.string().min(1),
+});
+
+export const submitLspEdgesSchema = z.object({
+  repo_id: z.string().min(1, 'repo_id is required'),
+  edges: z.array(lspEdgeSchema).min(1, 'at least one edge is required'),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createIngestionTools(graphStore: GraphStore | null) {
+  return {
+    'submit_lsp_edges': {
+      schema: submitLspEdgesSchema,
+      description:
+        'Submit LSP-resolved call/reference edges to enrich the code graph. ' +
+        'Designed for the VS Code extension and CI pipelines. Each edge describes ' +
+        'a typed relationship between two symbols (e.g. calls, imports, implements).',
+      handler: async (input: z.infer<typeof submitLspEdgesSchema>) => {
+        if (!graphStore) {
+          return {
+            error: 'GRAPH_UNAVAILABLE',
+            message:
+              'FalkorDB graph store is not available. LSP edges require a running FalkorDB instance.',
+          };
+        }
+
+        const healthy = await graphStore.isHealthy();
+        if (!healthy) {
+          return {
+            error: 'GRAPH_UNAVAILABLE',
+            message: 'FalkorDB is not healthy. Cannot ingest LSP edges.',
+          };
+        }
+
+        let accepted = 0;
+        let failed = 0;
+        const errors: string[] = [];
+
+        for (const edge of input.edges) {
+          try {
+            // Upsert the source node (Symbol)
+            await graphStore.upsertNode(
+              'Symbol',
+              { name: edge.from_symbol, repo_id: input.repo_id },
+              { file_path: edge.from_file, source: 'lsp' },
+            );
+
+            // Upsert the target node (Symbol)
+            await graphStore.upsertNode(
+              'Symbol',
+              { name: edge.to_symbol, repo_id: input.repo_id },
+              { file_path: edge.to_file, source: 'lsp' },
+            );
+
+            // Upsert the edge between the two symbols
+            await graphStore.upsertEdge(
+              'Symbol',
+              { name: edge.from_symbol, repo_id: input.repo_id },
+              edge.edge_type,
+              { source: 'lsp', repo_id: input.repo_id },
+              'Symbol',
+              { name: edge.to_symbol, repo_id: input.repo_id },
+            );
+
+            accepted++;
+          } catch (err) {
+            failed++;
+            const msg = `${edge.from_symbol} -[${edge.edge_type}]-> ${edge.to_symbol}: ${String(err)}`;
+            errors.push(msg);
+            logger.warn('ingestion-tools.submit_lsp_edges: edge failed', {
+              from: edge.from_symbol,
+              to: edge.to_symbol,
+              edgeType: edge.edge_type,
+              error: String(err),
+            });
+          }
+        }
+
+        logger.debug('ingestion-tools.submit_lsp_edges: completed', {
+          repoId: input.repo_id,
+          total: input.edges.length,
+          accepted,
+          failed,
+        });
+
+        const result: { accepted: number; failed: number; errors?: string[] } = {
+          accepted,
+          failed,
+        };
+
+        if (errors.length > 0) {
+          // Cap error messages to avoid oversized responses
+          result.errors = errors.slice(0, 20);
+        }
+
+        return result;
+      },
+    },
+  };
+}

package/src/tools/learning-tools.ts

@@ -0,0 +1,181 @@
+// learning-tools.ts — B17
+// MCP tool handlers for knowledge retrieval and confidence management.
+// Tools: get_patterns, get_gotchas, boost_knowledge, decay_knowledge
+
+import { z } from 'zod';
+import type { KnowledgeSearch } from '../knowledge/search.js';
+import type { ConfidenceManager } from '../learning/confidence.js';
+import type { QdrantVectorStore } from '../storage/qdrant-store.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const getPatternsSchema = z.object({
+  domain: z.string().optional(),
+  min_confidence: z.number().min(0).max(1).default(0.5),
+  limit: z.number().int().min(1).max(50).default(20),
+});
+
+export const getGotchasSchema = z.object({
+  stack: z.array(z.string()).optional(),
+  min_confidence: z.number().min(0).max(1).default(0.3),
+  limit: z.number().int().min(1).max(50).default(20),
+});
+
+export const boostKnowledgeSchema = z.object({
+  knowledge_id: z.string().min(1, 'knowledge_id is required'),
+  amount: z.number().min(0).max(1).default(0.05),
+  reason: z.string().optional(),
+});
+
+export const decayKnowledgeSchema = z.object({
+  decay_rate: z.number().min(0).max(1).default(0.01),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createLearningTools(
+  knowledgeSearch: KnowledgeSearch,
+  confidenceManager?: ConfidenceManager,
+  vectorStore?: QdrantVectorStore | null,
+) {
+  return {
+    'get_patterns': {
+      schema: getPatternsSchema,
+      description: 'Retrieve established code patterns from the knowledge base. PREFER THIS over ad-hoc code exploration when looking for "how do we do X in this codebase" — it returns curated, high-confidence patterns from past pipeline runs. Optionally filtered by domain/stack.',
+      handler: async (input: z.infer<typeof getPatternsSchema>) => {
+        try {
+          const patterns = await knowledgeSearch.getPatterns(input.domain, input.limit, input.min_confidence);
+
+          logger.debug('learning-tools.get_patterns: completed', {
+            domain: input.domain,
+            count: patterns.length,
+          });
+
+          return {
+            patterns: patterns.map(p => ({
+              title: p.title,
+              content: p.content,
+              confidence: p.confidence,
+              stack_tags: Array.isArray(p.stack_tags) ? p.stack_tags : [],
+              source_repo: (p as { source_repo?: string }).source_repo ?? p.source_agent ?? 'unknown',
+              times_confirmed: 1, // Qdrant payload doesn't track this yet
+            })),
+          };
+        } catch (err) {
+          logger.error('learning-tools.get_patterns: error', { error: String(err) });
+          return {
+            error: 'GET_PATTERNS_FAILED',
+            message: String(err),
+            patterns: [],
+          };
+        }
+      },
+    },
+
+    'get_gotchas': {
+      schema: getGotchasSchema,
+      description: 'Retrieve known gotchas and pitfalls from the knowledge base. ALWAYS CHECK THIS before starting implementation in an indexed repo — avoids repeating past mistakes. Optionally filtered by stack tags.',
+      handler: async (input: z.infer<typeof getGotchasSchema>) => {
+        try {
+          const gotchas = await knowledgeSearch.getGotchas(input.stack, input.limit, input.min_confidence);
+
+          logger.debug('learning-tools.get_gotchas: completed', {
+            stack: input.stack,
+            count: gotchas.length,
+          });
+
+          return {
+            gotchas: gotchas.map(g => ({
+              title: g.title,
+              content: g.content,
+              confidence: g.confidence,
+              stack_tags: Array.isArray(g.stack_tags) ? g.stack_tags : [],
+              source_repo: (g as { source_repo?: string }).source_repo ?? g.source_agent ?? 'unknown',
+            })),
+          };
+        } catch (err) {
+          logger.error('learning-tools.get_gotchas: error', { error: String(err) });
+          return {
+            error: 'GET_GOTCHAS_FAILED',
+            message: String(err),
+            gotchas: [],
+          };
+        }
+      },
+    },
+
+    'boost_knowledge': {
+      schema: boostKnowledgeSchema,
+      description: 'Boost the confidence score of a specific knowledge item. Used by Knowledge Keeper when a knowledge item proves valuable.',
+      handler: async (input: z.infer<typeof boostKnowledgeSchema>) => {
+        if (!confidenceManager || !vectorStore) {
+          return {
+            error: 'CONFIDENCE_UNAVAILABLE',
+            message: 'ConfidenceManager or vector store not available. Qdrant may be down.',
+          };
+        }
+
+        try {
+          await confidenceManager.boost(vectorStore, input.knowledge_id, input.amount);
+
+          logger.debug('learning-tools.boost_knowledge: completed', {
+            knowledge_id: input.knowledge_id,
+            amount: input.amount,
+            reason: input.reason,
+          });
+
+          return {
+            knowledge_id: input.knowledge_id,
+            boosted: true,
+            amount: input.amount,
+            reason: input.reason,
+          };
+        } catch (err) {
+          logger.error('learning-tools.boost_knowledge: error', { error: String(err) });
+          return {
+            error: 'BOOST_KNOWLEDGE_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+
+    'decay_knowledge': {
+      schema: decayKnowledgeSchema,
+      description: 'Apply time-based confidence decay to all knowledge items. Items not accessed within 30 days lose confidence. Used by Knowledge Keeper for maintenance.',
+      handler: async (input: z.infer<typeof decayKnowledgeSchema>) => {
+        if (!confidenceManager || !vectorStore) {
+          return {
+            error: 'CONFIDENCE_UNAVAILABLE',
+            message: 'ConfidenceManager or vector store not available. Qdrant may be down.',
+          };
+        }
+
+        try {
+          const decayedCount = await confidenceManager.decayAll(vectorStore, input.decay_rate);
+
+          logger.debug('learning-tools.decay_knowledge: completed', {
+            decay_rate: input.decay_rate,
+            decayed_count: decayedCount,
+          });
+
+          return {
+            decayed_count: decayedCount,
+            decay_rate: input.decay_rate,
+          };
+        } catch (err) {
+          logger.error('learning-tools.decay_knowledge: error', { error: String(err) });
+          return {
+            error: 'DECAY_KNOWLEDGE_FAILED',
+            message: String(err),
+          };
+        }
+      },
+    },
+  };
+}