@grafema/mcp 0.2.5-beta → 0.2.7

package/src/handlers/dataflow-handlers.ts

@@ -0,0 +1,193 @@
+/**
+ * MCP Dataflow Handlers
+ */
+
+import { ensureAnalyzed } from '../analysis.js';
+import { getProjectPath } from '../state.js';
+import {
+  serializeBigInt,
+  textResult,
+  errorResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  TraceAliasArgs,
+  TraceDataFlowArgs,
+  CheckInvariantArgs,
+  GraphNode,
+} from '../types.js';
+
+// === TRACE HANDLERS ===
+
+export async function handleTraceAlias(args: TraceAliasArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { variableName, file } = args;
+  const _projectPath = getProjectPath();
+
+  let varNode: GraphNode | null = null;
+
+  for await (const node of db.queryNodes({ type: 'VARIABLE' })) {
+    if (node.name === variableName && node.file?.includes(file || '')) {
+      varNode = node;
+      break;
+    }
+  }
+
+  if (!varNode) {
+    for await (const node of db.queryNodes({ type: 'CONSTANT' })) {
+      if (node.name === variableName && node.file?.includes(file || '')) {
+        varNode = node;
+        break;
+      }
+    }
+  }
+
+  if (!varNode) {
+    return errorResult(`Variable "${variableName}" not found in ${file || 'project'}`);
+  }
+
+  const chain: unknown[] = [];
+  const visited = new Set<string>();
+  let current: GraphNode | null = varNode;
+  const MAX_DEPTH = 20;
+
+  while (current && chain.length < MAX_DEPTH) {
+    if (visited.has(current.id)) {
+      chain.push({ type: 'CYCLE_DETECTED', id: current.id });
+      break;
+    }
+    visited.add(current.id);
+
+    chain.push({
+      type: current.type,
+      name: current.name,
+      file: current.file,
+      line: current.line,
+    });
+
+    const edges = await db.getOutgoingEdges(current.id, ['ASSIGNED_FROM']);
+    if (edges.length === 0) break;
+
+    current = await db.getNode(edges[0].dst);
+  }
+
+  return textResult(
+    `Alias chain for "${variableName}" (${chain.length} steps):\n\n${JSON.stringify(
+      serializeBigInt(chain),
+      null,
+      2
+    )}`
+  );
+}
+
+export async function handleTraceDataFlow(args: TraceDataFlowArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { source, direction = 'forward', max_depth = 10 } = args;
+
+  // Find source node
+  let sourceNode: GraphNode | null = null;
+
+  // Try to find by ID first
+  sourceNode = await db.getNode(source);
+
+  // If not found, search by name
+  if (!sourceNode) {
+    for await (const node of db.queryNodes({ name: source })) {
+      sourceNode = node;
+      break;
+    }
+  }
+
+  if (!sourceNode) {
+    return errorResult(`Source "${source}" not found`);
+  }
+
+  const visited = new Set<string>();
+  const paths: unknown[] = [];
+
+  async function trace(nodeId: string, depth: number, path: string[]): Promise<void> {
+    if (depth > max_depth || visited.has(nodeId)) return;
+    visited.add(nodeId);
+
+    const newPath = [...path, nodeId];
+
+    if (direction === 'forward' || direction === 'both') {
+      const outEdges = await db.getOutgoingEdges(nodeId, [
+        'ASSIGNED_FROM',
+        'DERIVES_FROM',
+        'PASSES_ARGUMENT',
+      ]);
+      for (const edge of outEdges) {
+        await trace(edge.dst, depth + 1, newPath);
+      }
+    }
+
+    if (direction === 'backward' || direction === 'both') {
+      const inEdges = await db.getIncomingEdges(nodeId, [
+        'ASSIGNED_FROM',
+        'DERIVES_FROM',
+        'PASSES_ARGUMENT',
+      ]);
+      for (const edge of inEdges) {
+        await trace(edge.src, depth + 1, newPath);
+      }
+    }
+
+    if (depth > 0) {
+      paths.push(newPath);
+    }
+  }
+
+  await trace(sourceNode.id, 0, []);
+
+  return textResult(
+    `Data flow from "${source}" (${paths.length} paths):\n\n${JSON.stringify(paths, null, 2)}`
+  );
+}
+
+export async function handleCheckInvariant(args: CheckInvariantArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { rule, name: description } = args;
+
+  if (!('checkGuarantee' in db)) {
+    return errorResult('Backend does not support Datalog queries');
+  }
+
+  try {
+    const checkFn = (db as unknown as { checkGuarantee: (q: string) => Promise<Array<{ bindings: Array<{ name: string; value: string }> }>> }).checkGuarantee;
+    const violations = await checkFn(rule);
+    const total = violations.length;
+
+    if (total === 0) {
+      return textResult(`✅ Invariant holds: ${description || 'No violations found'}`);
+    }
+
+    const enrichedViolations: unknown[] = [];
+    for (const v of violations.slice(0, 20)) {
+      const nodeId = v.bindings?.find((b: any) => b.name === 'X')?.value;
+      if (nodeId) {
+        const node = await db.getNode(nodeId);
+        if (node) {
+          enrichedViolations.push({
+            id: nodeId,
+            type: node.type,
+            name: node.name,
+            file: node.file,
+            line: node.line,
+          });
+        }
+      }
+    }
+
+    return textResult(
+      `❌ ${total} violation(s) found:\n\n${JSON.stringify(
+        serializeBigInt(enrichedViolations),
+        null,
+        2
+      )}${total > 20 ? `\n\n... and ${total - 20} more` : ''}`
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(message);
+  }
+}

package/src/handlers/documentation-handlers.ts

@@ -0,0 +1,89 @@
+/**
+ * MCP Documentation Handlers
+ */
+
+import { getOnboardingInstruction } from '@grafema/core';
+import {
+  textResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  GetDocumentationArgs,
+} from '../types.js';
+
+// === DOCUMENTATION ===
+
+export async function handleGetDocumentation(args: GetDocumentationArgs): Promise<ToolResult> {
+  const { topic = 'overview' } = args;
+
+  const docs: Record<string, string> = {
+    onboarding: getOnboardingInstruction(),
+    overview: `
+# Grafema Code Analysis
+
+Grafema is a static code analyzer that builds a graph of your codebase.
+
+## Key Tools
+- query_graph: Execute Datalog queries
+- find_calls: Find function/method calls
+- trace_alias: Trace variable aliases
+- check_invariant: Verify code invariants
+
+## Quick Start
+1. Use get_stats to see graph size
+2. Use find_nodes to explore the codebase
+3. Use query_graph for complex queries
+`,
+    queries: `
+# Datalog Queries
+
+## Syntax
+violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
+
+## Available Predicates
+- node(Id, Type) - match nodes
+- edge(Src, Dst, Type) - match edges
+- attr(Id, Name, Value) - match attributes
+- \\+ - negation (not)
+
+## Examples
+Find all functions:
+  violation(X) :- node(X, "FUNCTION").
+
+Find unresolved calls:
+  violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").
+`,
+    types: `
+# Node & Edge Types
+
+## Core Node Types
+- MODULE, FUNCTION, CLASS, METHOD, VARIABLE
+- CALL, PROPERTY_ACCESS, IMPORT, EXPORT, PARAMETER
+
+## HTTP/Network
+- http:route, http:request, db:query
+
+## Edge Types
+- CONTAINS, CALLS, DEPENDS_ON
+- ASSIGNED_FROM, INSTANCE_OF, PASSES_ARGUMENT
+`,
+    guarantees: `
+# Code Guarantees
+
+Guarantees are persistent code invariants.
+
+## Create
+Use create_guarantee with a name and Datalog rule.
+
+## Check
+Use check_guarantees to verify all guarantees.
+
+## Example
+Name: no-eval
+Rule: violation(X) :- node(X, "CALL"), attr(X, "name", "eval").
+`,
+  };
+
+  const content = docs[topic] || docs.overview;
+  return textResult(content.trim());
+}

package/src/handlers/guarantee-handlers.ts

@@ -0,0 +1,278 @@
+/**
+ * MCP Guarantee Handlers
+ */
+
+import { getOrCreateBackend, getGuaranteeManager, getGuaranteeAPI } from '../state.js';
+import {
+  textResult,
+  errorResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  CreateGuaranteeArgs,
+  CheckGuaranteesArgs,
+  DeleteGuaranteeArgs,
+} from '../types.js';
+import { isGuaranteeType } from '@grafema/core';
+
+// === GUARANTEE HANDLERS ===
+
+/**
+ * Create a new guarantee (Datalog-based or contract-based)
+ */
+export async function handleCreateGuarantee(args: CreateGuaranteeArgs): Promise<ToolResult> {
+  await getOrCreateBackend(); // Ensure managers are initialized
+
+  const { name, rule, type, priority, status, owner, schema, condition, description, governs, severity } = args;
+
+  try {
+    // Determine if this is a contract-based guarantee
+    if (type && isGuaranteeType(type)) {
+      // Contract-based guarantee
+      const api = getGuaranteeAPI();
+      if (!api) {
+        return errorResult('GuaranteeAPI not initialized');
+      }
+
+      const guarantee = await api.createGuarantee({
+        type,
+        name,
+        priority,
+        status,
+        owner,
+        schema,
+        condition,
+        description,
+        governs,
+      });
+
+      return textResult(
+        `✅ Created contract-based guarantee: ${guarantee.id}\n` +
+        `Type: ${guarantee.type}\n` +
+        `Priority: ${guarantee.priority}\n` +
+        `Status: ${guarantee.status}` +
+        (guarantee.description ? `\nDescription: ${guarantee.description}` : '')
+      );
+    } else {
+      // Datalog-based guarantee
+      if (!rule) {
+        return errorResult('Datalog-based guarantee requires "rule" field');
+      }
+
+      const manager = getGuaranteeManager();
+      if (!manager) {
+        return errorResult('GuaranteeManager not initialized');
+      }
+
+      const guarantee = await manager.create({
+        id: name,
+        name,
+        rule,
+        severity: severity || 'warning',
+        governs: governs || ['**/*.js'],
+      });
+
+      return textResult(
+        `✅ Created Datalog-based guarantee: ${guarantee.id}\n` +
+        `Rule: ${guarantee.rule}\n` +
+        `Severity: ${guarantee.severity}`
+      );
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to create guarantee: ${message}`);
+  }
+}
+
+/**
+ * List all guarantees (both Datalog-based and contract-based)
+ */
+export async function handleListGuarantees(): Promise<ToolResult> {
+  await getOrCreateBackend(); // Ensure managers are initialized
+
+  const results: string[] = [];
+
+  try {
+    // List Datalog-based guarantees
+    const manager = getGuaranteeManager();
+    if (manager) {
+      const datalogGuarantees = await manager.list();
+      if (datalogGuarantees.length > 0) {
+        results.push('## Datalog-based Guarantees\n');
+        for (const g of datalogGuarantees) {
+          results.push(`- **${g.id}** (${g.severity})`);
+          results.push(`  Rule: ${g.rule.substring(0, 80)}${g.rule.length > 80 ? '...' : ''}`);
+        }
+      }
+    }
+
+    // List contract-based guarantees
+    const api = getGuaranteeAPI();
+    if (api) {
+      const contractGuarantees = await api.findGuarantees();
+      if (contractGuarantees.length > 0) {
+        if (results.length > 0) results.push('\n');
+        results.push('## Contract-based Guarantees\n');
+        for (const g of contractGuarantees) {
+          results.push(`- **${g.id}** [${g.priority}] (${g.status})`);
+          if (g.description) results.push(`  ${g.description}`);
+        }
+      }
+    }
+
+    if (results.length === 0) {
+      return textResult('No guarantees defined yet.');
+    }
+
+    return textResult(results.join('\n'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to list guarantees: ${message}`);
+  }
+}
+
+/**
+ * Check guarantees (both Datalog-based and contract-based)
+ */
+export async function handleCheckGuarantees(args: CheckGuaranteesArgs): Promise<ToolResult> {
+  await getOrCreateBackend(); // Ensure managers are initialized
+
+  const { names } = args;
+  const results: string[] = [];
+  let totalPassed = 0;
+  let totalFailed = 0;
+
+  try {
+    const manager = getGuaranteeManager();
+    const api = getGuaranteeAPI();
+
+    if (names && names.length > 0) {
+      // Check specific guarantees
+      for (const name of names) {
+        // Try Datalog-based first
+        if (manager) {
+          try {
+            const result = await manager.check(name);
+            if (result.passed) {
+              totalPassed++;
+              results.push(`✅ ${result.guaranteeId}: PASSED`);
+            } else {
+              totalFailed++;
+              results.push(`❌ ${result.guaranteeId}: FAILED (${result.violationCount} violations)`);
+              for (const v of result.violations.slice(0, 5)) {
+                results.push(`   - ${v.file}:${v.line} (${v.type})`);
+              }
+              if (result.violationCount > 5) {
+                results.push(`   ... and ${result.violationCount - 5} more`);
+              }
+            }
+            continue;
+          } catch {
+            // Not a Datalog guarantee, try contract-based
+          }
+        }
+
+        // Try contract-based
+        if (api) {
+          try {
+            const result = await api.checkGuarantee(name);
+            if (result.passed) {
+              totalPassed++;
+              results.push(`✅ ${result.id}: PASSED`);
+            } else {
+              totalFailed++;
+              results.push(`❌ ${result.id}: FAILED`);
+              for (const err of result.errors.slice(0, 5)) {
+                results.push(`   - ${err}`);
+              }
+            }
+          } catch {
+            results.push(`⚠️ ${name}: Not found`);
+          }
+        }
+      }
+    } else {
+      // Check all guarantees
+      if (manager) {
+        const datalogResult = await manager.checkAll();
+        totalPassed += datalogResult.passed;
+        totalFailed += datalogResult.failed;
+
+        if (datalogResult.total > 0) {
+          results.push('## Datalog Guarantees\n');
+          for (const r of datalogResult.results) {
+            if (r.passed) {
+              results.push(`✅ ${r.guaranteeId}: PASSED`);
+            } else {
+              results.push(`❌ ${r.guaranteeId}: FAILED (${r.violationCount} violations)`);
+            }
+          }
+        }
+      }
+
+      if (api) {
+        const contractResult = await api.checkAllGuarantees();
+        totalPassed += contractResult.passed;
+        totalFailed += contractResult.failed;
+
+        if (contractResult.total > 0) {
+          if (results.length > 0) results.push('\n');
+          results.push('## Contract Guarantees\n');
+          for (const r of contractResult.results) {
+            if (r.passed) {
+              results.push(`✅ ${r.id}: PASSED`);
+            } else {
+              results.push(`❌ ${r.id}: FAILED`);
+            }
+          }
+        }
+      }
+    }
+
+    if (results.length === 0) {
+      return textResult('No guarantees to check.');
+    }
+
+    const summary = `\n---\nTotal: ${totalPassed + totalFailed} | ✅ Passed: ${totalPassed} | ❌ Failed: ${totalFailed}`;
+    return textResult(results.join('\n') + summary);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to check guarantees: ${message}`);
+  }
+}
+
+/**
+ * Delete a guarantee
+ */
+export async function handleDeleteGuarantee(args: DeleteGuaranteeArgs): Promise<ToolResult> {
+  await getOrCreateBackend(); // Ensure managers are initialized
+
+  const { name } = args;
+
+  try {
+    // Try Datalog-based first
+    const manager = getGuaranteeManager();
+    if (manager) {
+      try {
+        await manager.delete(name);
+        return textResult(`✅ Deleted Datalog guarantee: ${name}`);
+      } catch {
+        // Not found in Datalog, try contract-based
+      }
+    }
+
+    // Try contract-based
+    const api = getGuaranteeAPI();
+    if (api) {
+      const deleted = await api.deleteGuarantee(name);
+      if (deleted) {
+        return textResult(`✅ Deleted contract guarantee: ${name}`);
+      }
+    }
+
+    return errorResult(`Guarantee not found: ${name}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResult(`Failed to delete guarantee: ${message}`);
+  }
+}

package/src/handlers/guard-handlers.ts

@@ -0,0 +1,100 @@
+/**
+ * MCP Guard Handlers
+ */
+
+import { getOrCreateBackend } from '../state.js';
+import {
+  serializeBigInt,
+  textResult,
+  errorResult,
+} from '../utils.js';
+import type {
+  ToolResult,
+  FindGuardsArgs,
+  GuardInfo,
+} from '../types.js';
+
+// === FIND GUARDS (REG-274) ===
+
+/**
+ * Find conditional guards protecting a node.
+ *
+ * Walks up the containment tree via CONTAINS edges, collecting
+ * SCOPE nodes that have conditional=true (if_statement, else_statement, etc.).
+ *
+ * Returns guards in inner-to-outer order.
+ */
+export async function handleFindGuards(args: FindGuardsArgs): Promise<ToolResult> {
+  const db = await getOrCreateBackend();
+  const { nodeId } = args;
+
+  // Verify target node exists
+  const targetNode = await db.getNode(nodeId);
+  if (!targetNode) {
+    return errorResult(`Node not found: ${nodeId}`);
+  }
+
+  const guards: GuardInfo[] = [];
+  const visited = new Set<string>();
+  let currentId = nodeId;
+
+  // Walk up the containment tree
+  while (true) {
+    if (visited.has(currentId)) break;
+    visited.add(currentId);
+
+    // Get parent via incoming CONTAINS edge
+    const incomingEdges = await db.getIncomingEdges(currentId, ['CONTAINS']);
+    if (incomingEdges.length === 0) break;
+
+    const parentId = incomingEdges[0].src;
+    const parentNode = await db.getNode(parentId);
+
+    if (!parentNode) break;
+
+    // Check if this is a conditional scope
+    if (parentNode.conditional) {
+      // Parse constraints if stored as string
+      let constraints = parentNode.constraints;
+      if (typeof constraints === 'string') {
+        try {
+          constraints = JSON.parse(constraints);
+        } catch {
+          // Keep as string if not valid JSON
+        }
+      }
+
+      guards.push({
+        scopeId: parentNode.id,
+        scopeType: (parentNode.scopeType as string) || 'unknown',
+        condition: parentNode.condition as string | undefined,
+        constraints: constraints as unknown[] | undefined,
+        file: parentNode.file || '',
+        line: (parentNode.line as number) || 0,
+      });
+    }
+
+    currentId = parentId;
+  }
+
+  if (guards.length === 0) {
+    return textResult(
+      `No guards found for node: ${nodeId}\n` +
+      `The node is not protected by any conditional scope (if/else/switch/etc.).`
+    );
+  }
+
+  const summary = guards.map((g, i) => {
+    const indent = '  '.repeat(i);
+    return `${indent}${i + 1}. ${g.scopeType} at ${g.file}:${g.line}` +
+      (g.condition ? `\n${indent}   condition: ${g.condition}` : '');
+  }).join('\n');
+
+  return textResult(
+    `Found ${guards.length} guard(s) for node: ${nodeId}\n` +
+    `(inner to outer order)\n\n` +
+    summary +
+    `\n\n` +
+    JSON.stringify(serializeBigInt(guards), null, 2)
+  );
+}

package/src/handlers/index.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP Tool Handlers — barrel export
+ */
+
+export { handleQueryGraph, handleFindCalls, handleFindNodes } from './query-handlers.js';
+export { handleTraceAlias, handleTraceDataFlow, handleCheckInvariant } from './dataflow-handlers.js';
+export { handleAnalyzeProject, handleGetAnalysisStatus, handleGetStats, handleGetSchema } from './analysis-handlers.js';
+export { handleCreateGuarantee, handleListGuarantees, handleCheckGuarantees, handleDeleteGuarantee } from './guarantee-handlers.js';
+export { handleGetFunctionDetails, handleGetContext, handleGetFileOverview } from './context-handlers.js';
+export { handleReadProjectStructure, handleWriteConfig } from './project-handlers.js';
+export { handleGetCoverage } from './coverage-handlers.js';
+export { handleFindGuards } from './guard-handlers.js';
+export { handleGetDocumentation } from './documentation-handlers.js';
+export { handleReportIssue } from './issue-handlers.js';