specvector 0.0.1 → 0.1.0

package/README.md

@@ -2,29 +2,155 @@
 
 > Context-aware AI code review using Model Context Protocol (MCP)
 
-🚧 **Coming Soon** — This package is under active development.
-
 ## What is SpecVector?
 
-SpecVector is an open-source AI code review tool that connects to your internal systems (Linear, ADRs, database schemas) to provide context-aware feedback on pull requests.
+SpecVector is an open-source AI code review tool that explores your codebase to provide context-aware feedback on pull requests.
+
+Unlike generic AI review tools that only see the diff, SpecVector:
+
+- **Reads related files** to understand context
+- **Searches for patterns** to find usages
+- **Explores project structure** to understand architecture
+- **Uses tool calling** for agentic code exploration
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Clone and install
+git clone https://github.com/nedlink/specvector.git
+cd specvector
+bun install
+```
+
+### 2. Set up API Key
+
+```bash
+# Create .env file
+cp .env.example .env
+
+# Add your OpenRouter API key
+echo "OPENROUTER_API_KEY=your-key-here" >> .env
+```
+
+Get a key at [openrouter.ai](https://openrouter.ai)
+
+### 3. Run a Review
+
+```bash
+# Review a PR (dry run - no posting)
+cd /path/to/repo-with-pr
+bun run /path/to/specvector/src/index.ts review 123 --dry-run
+
+# Or with mock review (no LLM calls)
+bun run /path/to/specvector/src/index.ts review 123 --mock --dry-run
+```
+
+## CLI Usage
+
+```
+SpecVector CLI v0.1.0
+Context-aware AI code review
+
+USAGE:
+  specvector review <pr-number>              Review a pull request
+  specvector review <pr-number> --dry-run    Preview review without posting
+  specvector review <pr-number> --mock       Use mock review (no LLM)
+  specvector --help                          Show this help
+  specvector --version                       Show version
 
-Unlike generic AI review tools that only see the diff, SpecVector understands:
+ENVIRONMENT:
+  OPENROUTER_API_KEY       API key for OpenRouter
+  SPECVECTOR_PROVIDER      LLM provider (openrouter or ollama)
+  SPECVECTOR_MODEL         Model to use
+```
+
+## GitHub Action
+
+Add to your repository:
+
+```yaml
+name: SpecVector Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
 
-- What ticket the PR is for
-- Your architectural decisions
-- Your database schema
-- Your coding standards
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-## Installation
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install SpecVector
+        run: |
+          git clone https://github.com/nedlink/specvector.git /tmp/specvector
+          cd /tmp/specvector && bun install
+
+      - name: Review PR
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cd ${{ github.workspace }}
+          bun run /tmp/specvector/src/index.ts review ${{ github.event.pull_request.number }}
+```
+
+## Local Development
 
 ```bash
-npx specvector --help
+# Run tests
+bun test
+
+# Type check
+bun run check
+
+# Test the agent
+bun run scripts/test-agent.ts
 ```
 
-## Documentation
+## LLM Providers
 
-Full documentation coming soon at [github.com/nedlink/specvector](https://github.com/nedlink/specvector)
+| Provider   | Use Case                               | Setup                |
+| ---------- | -------------------------------------- | -------------------- |
+| OpenRouter | Cloud access to Claude, GPT-4, Llama   | `OPENROUTER_API_KEY` |
+| Ollama     | Self-hosted, air-gapped, privacy-first | `ollama serve`       |
+
+```bash
+# Use Ollama instead of OpenRouter
+SPECVECTOR_PROVIDER=ollama SPECVECTOR_MODEL=llama3.2 bun run src/index.ts review 123 --dry-run
+```
+
+## Architecture
+
+```
+PR Diff ───→ Agent Loop ───→ LLM ───→ Review Comment
+                 ↓  ↑
+               Tools
+            (read_file,
+             grep,
+             list_dir)
+```
+
+The agent can:
+
+- **read_file** — Read source code files
+- **grep** — Search for patterns in the codebase
+- **list_dir** — Explore project structure
 
 ## License
 
 MIT
+
+## Contributing
+
+PRs welcome! Run `bun test` before submitting.

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "specvector",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Context-aware AI code review using Model Context Protocol (MCP)",
   "type": "module",
   "main": "src/index.ts",
   "bin": {
     "specvector": "src/index.ts"
   },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "start": "bun src/index.ts",
-    "test": "bun test"
+    "test": "bun test",
+    "check": "bun x tsc --noEmit"
   },
   "keywords": [
     "code-review",
@@ -19,17 +25,29 @@
     "model-context-protocol",
     "github-actions",
     "linear",
-    "anthropic"
+    "anthropic",
+    "openrouter"
   ],
   "author": "Dragos",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/nedlink/specvector"
+    "url": "git+https://github.com/Not-Diamond/specvector.git"
+  },
+  "homepage": "https://github.com/Not-Diamond/specvector#readme",
+  "bugs": {
+    "url": "https://github.com/Not-Diamond/specvector/issues"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@larryhudson/linear-mcp-server": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
   },
-  "dependencies": {},
-  "devDependencies": {}
+  "peerDependencies": {
+    "typescript": "^5"
+  }
 }

package/src/agent/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Agent module - Public API
+ */
+
+// Re-export types
+export type {
+  Tool,
+  ToolResult,
+  ToolError,
+  AgentConfig,
+  AgentError,
+  AgentErrorCode,
+  AgentResult,
+  AgentState,
+} from "./types";
+
+export {
+  DEFAULT_AGENT_CONFIG,
+  toolToLLMTool,
+  createAgentError,
+  AgentErrors,
+} from "./types";
+
+// Re-export loop
+export { AgentLoop, createAgentLoop } from "./loop";
+
+// Re-export tools
+export * from "./tools";

package/src/agent/loop.ts

@@ -0,0 +1,221 @@
+/**
+ * Agent Loop - Core agentic execution engine.
+ * 
+ * Implements a simple ReAct-style loop:
+ * 1. Send messages to LLM
+ * 2. If LLM returns tool_calls, execute them in parallel
+ * 3. Add tool results to messages and repeat
+ * 4. Stop when LLM returns content without tool_calls
+ * 
+ * Fixes applied:
+ * - M1: Parallel tool execution with Promise.all
+ * - M2: Tool errors sent back to LLM instead of aborting
+ * - L2: Per-tool timeout
+ */
+
+
+import { ok, err } from "../types/result";
+import type { Message, ToolCall } from "../types/llm";
+import type { LLMProvider, LLMError } from "../llm/provider";
+import type {
+  Tool,
+  AgentConfig,
+  AgentResult,
+  AgentError,
+} from "./types";
+import {
+  DEFAULT_AGENT_CONFIG,
+  toolToLLMTool,
+  AgentErrors,
+} from "./types";
+
+/** Default timeout for individual tool execution (30 seconds) */
+const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+
+/**
+ * Agent loop - manages LLM ↔ Tool interaction.
+ */
+export class AgentLoop {
+  private readonly provider: LLMProvider;
+  private readonly tools: Map<string, Tool>;
+  private readonly config: Required<AgentConfig>;
+
+  constructor(
+    provider: LLMProvider,
+    tools: Tool[],
+    config?: AgentConfig
+  ) {
+    this.provider = provider;
+    this.tools = new Map(tools.map((t) => [t.name, t]));
+    this.config = { ...DEFAULT_AGENT_CONFIG, ...config };
+  }
+
+  /**
+   * Run the agent loop with a task.
+   */
+  async run(task: string): Promise<AgentResult> {
+    const messages: Message[] = [
+      { role: "system", content: this.config.systemPrompt },
+      { role: "user", content: task },
+    ];
+
+    const startTime = Date.now();
+    let iteration = 0;
+
+    while (iteration < this.config.maxIterations) {
+      iteration++;
+
+      // Check timeout
+      if (Date.now() - startTime > this.config.timeoutMs) {
+        return err(AgentErrors.timeout());
+      }
+
+      // Get LLM response
+      const llmResult = await this.provider.chat(
+        messages,
+        {
+          tools: Array.from(this.tools.values()).map(toolToLLMTool),
+        }
+      );
+
+      if (!llmResult.ok) {
+        return err(this.mapLLMError(llmResult.error));
+      }
+
+      const response = llmResult.value;
+
+      // Check for tool calls
+      if (response.tool_calls && response.tool_calls.length > 0) {
+        // Add assistant message with tool calls
+        messages.push({
+          role: "assistant",
+          content: response.content,
+          tool_calls: response.tool_calls,
+        });
+
+        // Execute tools in parallel (M1 fix)
+        const toolMessages = await this.executeToolsParallel(response.tool_calls);
+        
+        // Add all tool results to messages (M2 fix: errors as messages, not aborts)
+        for (const msg of toolMessages) {
+          messages.push(msg);
+        }
+      } else {
+        // No tool calls - we have the final answer
+        return ok(response.content ?? "");
+      }
+    }
+
+    // Exceeded max iterations
+    return err(AgentErrors.maxIterationsExceeded(this.config.maxIterations));
+  }
+
+  /**
+   * Execute tool calls in parallel and return tool messages.
+   * Tool errors are returned as error messages to the LLM, not thrown.
+   */
+  private async executeToolsParallel(toolCalls: ToolCall[]): Promise<Message[]> {
+    const results = await Promise.all(
+      toolCalls.map(call => this.executeSingleTool(call))
+    );
+    return results;
+  }
+
+  /**
+   * Execute a single tool call with timeout.
+   * Returns a tool message (success or error content).
+   */
+  private async executeSingleTool(call: ToolCall): Promise<Message> {
+    const tool = this.tools.get(call.name);
+
+    if (!tool) {
+      // Tool not found - return error message to LLM
+      return {
+        role: "tool" as const,
+        content: `Error: Tool '${call.name}' not found. Available tools: ${Array.from(this.tools.keys()).join(", ")}`,
+        tool_call_id: call.id,
+        name: call.name,
+      };
+    }
+
+    // Parse arguments
+    let args: Record<string, unknown>;
+    try {
+      args = JSON.parse(call.arguments);
+    } catch {
+      return {
+        role: "tool" as const,
+        content: `Error: Invalid JSON arguments for tool '${call.name}'`,
+        tool_call_id: call.id,
+        name: call.name,
+      };
+    }
+
+    // Execute tool with timeout (L2 fix)
+    try {
+      const toolResult = await Promise.race([
+        tool.execute(args),
+        this.createToolTimeout(call.name),
+      ]);
+
+      if (!toolResult.ok) {
+        // Tool returned an error - send it back to LLM (M2 fix)
+        return {
+          role: "tool" as const,
+          content: `Error: ${toolResult.error.message}`,
+          tool_call_id: call.id,
+          name: call.name,
+        };
+      }
+
+      // Success
+      return {
+        role: "tool" as const,
+        content: toolResult.value,
+        tool_call_id: call.id,
+        name: call.name,
+      };
+    } catch (error) {
+      // Timeout or unexpected error
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return {
+        role: "tool" as const,
+        content: `Error: ${message}`,
+        tool_call_id: call.id,
+        name: call.name,
+      };
+    }
+  }
+
+  /**
+   * Create a timeout promise for tool execution.
+   */
+  private createToolTimeout(toolName: string): Promise<never> {
+    return new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Tool '${toolName}' timed out after ${DEFAULT_TOOL_TIMEOUT_MS}ms`));
+      }, DEFAULT_TOOL_TIMEOUT_MS);
+    });
+  }
+
+  /**
+   * Map LLM error to agent error.
+   */
+  private mapLLMError(error: LLMError): AgentError {
+    return AgentErrors.llmError(
+      `LLM error: ${error.message}`,
+      error.cause
+    );
+  }
+}
+
+/**
+ * Create an agent loop.
+ */
+export function createAgentLoop(
+  provider: LLMProvider,
+  tools: Tool[],
+  config?: AgentConfig
+): AgentLoop {
+  return new AgentLoop(provider, tools, config);
+}

package/src/agent/tools/find-symbol.ts

@@ -0,0 +1,224 @@
+/**
+ * Find Symbol Tool - Find where a symbol is defined.
+ * 
+ * Uses grep with smart patterns to find function, class, and variable definitions.
+ */
+
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { resolve } from "path";
+import type { Tool, ToolResult } from "../types";
+import { ok, err } from "../../types/result";
+
+const execFileAsync = promisify(execFile);
+
+/** Default timeout for symbol search (10 seconds) */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Maximum results to return */
+const MAX_RESULTS = 20;
+
+/** Configuration for find_symbol tool */
+export interface FindSymbolConfig {
+  /** Working directory for search */
+  workingDir: string;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+}
+
+/**
+ * Create the find_symbol tool.
+ */
+export function createFindSymbolTool(config: FindSymbolConfig): Tool {
+  const normalizedWorkingDir = resolve(config.workingDir);
+  const timeout = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    name: "find_symbol",
+    description: "Find where a function, class, or variable is defined. Use this to locate definitions when you see a symbol being used.",
+    parameters: {
+      type: "object",
+      properties: {
+        symbol: {
+          type: "string",
+          description: "Name of the function, class, or variable to find",
+        },
+        type: {
+          type: "string",
+          enum: ["function", "class", "variable", "any"],
+          description: "Type of symbol to find (optional, defaults to 'any')",
+        },
+      },
+      required: ["symbol"],
+    },
+
+    execute: async (args): Promise<ToolResult> => {
+      const symbolArg = args.symbol;
+      const typeArg = (args.type as string) ?? "any";
+
+      if (typeof symbolArg !== "string" || !symbolArg.trim()) {
+        return err({
+          code: "INVALID_SYMBOL",
+          message: "Symbol must be a non-empty string",
+        });
+      }
+
+      // SECURITY: Validate symbol name (alphanumeric + underscore only)
+      // This prevents: ReDoS (no regex metacharacters like +*?), command injection (no shell chars)
+      // Safe to embed in regex patterns after this check passes
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(symbolArg)) {
+        return err({
+          code: "INVALID_SYMBOL",
+          message: "Symbol must be a valid identifier",
+        });
+      }
+
+      // Build search patterns based on type
+      // SECURITY: symbolArg is validated above - only [a-zA-Z0-9_] chars allowed
+      const patterns = buildPatterns(symbolArg, typeArg);
+      
+      // Pre-compile regex patterns for efficient labeling (used in result processing)
+      const compiledPatterns = patterns.map(p => ({
+        regex: new RegExp(p.pattern),
+        label: p.label,
+      }));
+
+      const results: Array<{ file: string; line: number; content: string; type: string }> = [];
+
+      // Combine all patterns into single grep for performance
+      const combinedPattern = patterns.map(p => `(${p.pattern})`).join("|");
+
+      try {
+        const { stdout } = await execFileAsync(
+          "grep",
+          [
+            "-rn",           // Recursive with line numbers
+            "-E",            // Extended regex
+            "--include=*.ts",
+            "--include=*.tsx",
+            "--include=*.js",
+            "--include=*.jsx",
+            "--include=*.py",
+            "--include=*.go",
+            "--include=*.rs",
+            combinedPattern,
+            ".",
+          ],
+          {
+            cwd: normalizedWorkingDir,
+            timeout,
+            maxBuffer: 1024 * 1024, // 1MB
+          }
+        );
+
+        // Parse grep output (handles both Unix and Windows paths)
+        for (const line of stdout.split("\n")) {
+          if (!line.trim() || results.length >= MAX_RESULTS) continue;
+
+          // Match both ./path and .\path (Windows)
+          const match = line.match(/^\.[\\/](.+?):(\d+):(.*)$/);
+          if (match) {
+            const file = match[1];
+            const lineNum = match[2];
+            const content = match[3];
+            
+            if (!file || !lineNum) continue;
+            
+            // Skip node_modules and test files for cleaner results
+            // Handle both forward and back slashes
+            if (file.includes("node_modules") || file.includes(".test.")) {
+              continue;
+            }
+
+            // Determine which pattern matched for the label (using pre-compiled regex)
+            // Limit line length to prevent ReDoS on malformed grep output
+            const safeContent = (content ?? "").slice(0, 500);
+            const matchedPattern = compiledPatterns.find(p => p.regex.test(safeContent));
+            const label = matchedPattern?.label ?? "definition";
+
+            results.push({
+              file: file.replace(/\\/g, "/"), // Normalize to forward slashes
+              line: parseInt(lineNum, 10),
+              content: (content ?? "").trim().slice(0, 100),
+              type: label,
+            });
+          }
+        }
+      } catch (error) {
+        // grep returns exit code 1 when no matches - that's expected
+        const isExecError = (err: unknown): err is { code: number; stderr?: string } =>
+          err !== null && typeof err === "object" && "code" in err;
+        
+        if (isExecError(error) && error.code === 1 && !error.stderr) {
+          // No matches - continue to return empty results message
+        } else if (error instanceof Error) {
+          // Real error - log it for debugging
+          console.error(`find_symbol grep error: ${error.message}`);
+        }
+      }
+
+      if (results.length === 0) {
+        return ok(`No definition found for symbol '${symbolArg}'`);
+      }
+
+      // Format output
+      const output = results
+        .map(r => `${r.file}:${r.line} (${r.type})\n  ${r.content}`)
+        .join("\n\n");
+
+      return ok(`Found ${results.length} definition(s) for '${symbolArg}':\n\n${output}`);
+    },
+  };
+}
+
+interface SearchPattern {
+  pattern: string;
+  label: string;
+}
+
+function buildPatterns(symbol: string, type: string): SearchPattern[] {
+  const patterns: SearchPattern[] = [];
+
+  // Function patterns
+  if (type === "function" || type === "any") {
+    patterns.push(
+      // TypeScript/JavaScript
+      { pattern: `^(export\\s+)?(async\\s+)?function\\s+${symbol}\\s*\\(`, label: "function" },
+      { pattern: `^(export\\s+)?const\\s+${symbol}\\s*=\\s*(async\\s+)?\\([^)]*\\)\\s*=>`, label: "arrow fn" },
+      { pattern: `^(export\\s+)?const\\s+${symbol}\\s*=\\s*(async\\s+)?function`, label: "fn expr" },
+      // Python
+      { pattern: `^(async\\s+)?def\\s+${symbol}\\s*\\(`, label: "function" },
+      // Go
+      { pattern: `^func\\s+${symbol}\\s*\\(`, label: "function" },
+      // Rust
+      { pattern: `^(pub\\s+)?fn\\s+${symbol}\\s*[(<]`, label: "function" },
+    );
+  }
+
+  // Class patterns
+  if (type === "class" || type === "any") {
+    patterns.push(
+      // TypeScript/JavaScript
+      { pattern: `^(export\\s+)?(abstract\\s+)?class\\s+${symbol}\\b`, label: "class" },
+      // Python
+      { pattern: `^class\\s+${symbol}\\s*[:(]`, label: "class" },
+      // Go (struct)
+      { pattern: `^type\\s+${symbol}\\s+struct`, label: "struct" },
+      // Rust
+      { pattern: `^(pub\\s+)?struct\\s+${symbol}\\b`, label: "struct" },
+    );
+  }
+
+  // Variable/const patterns
+  if (type === "variable" || type === "any") {
+    patterns.push(
+      // TypeScript/JavaScript
+      { pattern: `^(export\\s+)?(const|let|var)\\s+${symbol}\\s*[=:]`, label: "variable" },
+      // Interface/Type
+      { pattern: `^(export\\s+)?interface\\s+${symbol}\\b`, label: "interface" },
+      { pattern: `^(export\\s+)?type\\s+${symbol}\\s*=`, label: "type" },
+    );
+  }
+
+  return patterns;
+}