specvector 0.0.1 → 0.1.2

package/src/context/linear.ts

@@ -0,0 +1,201 @@
+/**
+ * Linear Context Provider - Fetches ticket context for reviews.
+ *
+ * Extracts ticket ID from branch name/PR and fetches details via MCP.
+ */
+
+import { createMCPClient } from "../mcp";
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LinearTicket {
+  id: string;
+  title: string;
+  description: string;
+  state: string;
+  priority: number;
+  labels: string[];
+}
+
+export interface LinearContextError {
+  code: "NO_TOKEN" | "NO_TICKET_ID" | "CONNECTION_FAILED" | "FETCH_FAILED";
+  message: string;
+}
+
+// ============================================================================
+// Ticket ID Extraction
+// ============================================================================
+
+/**
+ * Extract Linear ticket ID from various sources.
+ *
+ * Patterns supported:
+ * - Branch: D6N-5/add-mcp-support or feat/SPC-123-feature
+ * - PR Title: [SPC-123] Feature or SPC-123: Feature
+ * - PR Body: "Linear: SPC-123" or "Closes SPC-123"
+ */
+export function extractTicketId(
+  branchName?: string,
+  prTitle?: string,
+  prBody?: string
+): string | null {
+  // Linear ticket pattern: 2-4 alphanumeric chars (at least one letter), hyphen, 1+ digits
+  // Examples: SPC-123, D6N-5, ABC-42
+  const ticketPattern = /\b([A-Z0-9]{2,4}-\d+)\b/;
+
+  // Try branch name first (most reliable)
+  if (branchName) {
+    const match = branchName.match(ticketPattern);
+    if (match) return match[1] ?? null;
+  }
+
+  // Try PR title
+  if (prTitle) {
+    const match = prTitle.match(ticketPattern);
+    if (match) return match[1] ?? null;
+  }
+
+  // Try PR body
+  if (prBody) {
+    const match = prBody.match(ticketPattern);
+    if (match) return match[1] ?? null;
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Linear Context Fetching
+// ============================================================================
+
+/**
+ * Fetch Linear ticket context for a review.
+ *
+ * Returns formatted context string to inject into review prompt.
+ */
+export async function fetchLinearContext(
+  ticketId: string
+): Promise<Result<string, LinearContextError>> {
+  // Check for API token
+  const apiToken = process.env.LINEAR_API_TOKEN;
+  if (!apiToken) {
+    return err({
+      code: "NO_TOKEN",
+      message: "LINEAR_API_TOKEN not set",
+    });
+  }
+
+  // Create MCP client
+  const clientResult = await createMCPClient({
+    name: "linear",
+    command: "npx",
+    args: ["linear-mcp-server"],
+    env: {
+      LINEAR_API_KEY: apiToken,
+    },
+    timeout: 30000,
+  });
+
+  if (!clientResult.ok) {
+    return err({
+      code: "CONNECTION_FAILED",
+      message: clientResult.error.message,
+    });
+  }
+
+  const client = clientResult.value;
+
+  try {
+    // Fetch ticket details
+    const ticketResult = await client.callTool("get_ticket", { ticket_id: ticketId });
+
+    if (!ticketResult.ok) {
+      return err({
+        code: "FETCH_FAILED",
+        message: ticketResult.error.message,
+      });
+    }
+
+    // Parse the response
+    const content = ticketResult.value.content;
+    const textContent = content.find(c => c.type === "text");
+    
+    if (!textContent?.text) {
+      return err({
+        code: "FETCH_FAILED",
+        message: "No ticket data returned",
+      });
+    }
+
+    // Format the context for the review prompt
+    const contextBlock = formatLinearContext(ticketId, textContent.text);
+    return ok(contextBlock);
+
+  } finally {
+    await client.close();
+  }
+}
+
+/**
+ * Format Linear ticket data as context for review prompt.
+ */
+function formatLinearContext(ticketId: string, ticketData: string): string {
+  return `
+## Linear Ticket Context: ${ticketId}
+
+The following is the context from the linked Linear ticket. Use this to understand the business requirements and acceptance criteria for this PR.
+
+${ticketData}
+
+---
+When reviewing, check that the PR changes align with the ticket requirements above.
+`;
+}
+
+/**
+ * Get Linear context if available, with graceful degradation.
+ *
+ * This is the main entry point for the review engine.
+ * Returns context string or null if not available.
+ */
+export async function getLinearContextForReview(
+  branchName?: string,
+  prTitle?: string,
+  prBody?: string
+): Promise<{ context: string | null; ticketId: string | null; warning?: string }> {
+  // Extract ticket ID
+  const ticketId = extractTicketId(branchName, prTitle, prBody);
+
+  if (!ticketId) {
+    return { context: null, ticketId: null };
+  }
+
+  // Check for API token first (fast fail)
+  if (!process.env.LINEAR_API_TOKEN) {
+    return {
+      context: null,
+      ticketId,
+      warning: `Found ticket ${ticketId} but LINEAR_API_TOKEN not set`,
+    };
+  }
+
+  // Fetch context
+  const result = await fetchLinearContext(ticketId);
+
+  if (!result.ok) {
+    return {
+      context: null,
+      ticketId,
+      warning: `Failed to fetch ${ticketId}: ${result.error.message}`,
+    };
+  }
+
+  return {
+    context: result.value,
+    ticketId,
+  };
+}

package/src/github/comment.ts

@@ -0,0 +1,102 @@
+/**
+ * GitHub CLI wrapper for posting PR comments.
+ * Uses `gh pr comment` to post review feedback.
+ */
+
+import { $ } from "bun";
+import { tmpdir } from "os";
+import { join } from "path";
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+
+export interface CommentError {
+  code: "NOT_FOUND" | "AUTH_ERROR" | "COMMAND_FAILED" | "CONTENT_TOO_LARGE";
+  message: string;
+}
+
+/**
+ * Maximum comment size for GitHub (65536 characters).
+ */
+const MAX_COMMENT_SIZE = 65536;
+
+/**
+ * Post a comment to a pull request.
+ * 
+ * Uses --body-file to avoid shell injection from comment body content.
+ * 
+ * @param prNumber - The PR number to comment on
+ * @param body - The markdown content of the comment
+ * @returns Result with success boolean or error
+ */
+export async function postPRComment(
+  prNumber: number,
+  body: string
+): Promise<Result<boolean, CommentError>> {
+  // Check comment size
+  if (body.length > MAX_COMMENT_SIZE) {
+    return err({
+      code: "CONTENT_TOO_LARGE",
+      message: `Comment too large (${body.length} chars, max ${MAX_COMMENT_SIZE})`,
+    });
+  }
+
+  // Write body to temp file to prevent shell injection
+  const tempFile = join(tmpdir(), `specvector-comment-${Date.now()}.md`);
+  
+  try {
+    await Bun.write(tempFile, body);
+    
+    // Use --body-file instead of --body to avoid shell metacharacter issues
+    const result = await $`gh pr comment ${prNumber} --body-file ${tempFile}`.quiet();
+
+    // Clean up temp file
+    await Bun.file(tempFile).exists() && await $`rm ${tempFile}`.quiet();
+
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString();
+
+      // Check for common error patterns
+      if (stderr.includes("Could not find pull request")) {
+        return err({
+          code: "NOT_FOUND",
+          message: `PR #${prNumber} not found`,
+        });
+      }
+
+      if (stderr.includes("authentication") || stderr.includes("gh auth login")) {
+        return err({
+          code: "AUTH_ERROR",
+          message: "GitHub CLI not authenticated. Run: gh auth login",
+        });
+      }
+
+      return err({
+        code: "COMMAND_FAILED",
+        message: `gh pr comment failed: ${stderr}`,
+      });
+    }
+
+    return ok(true);
+  } catch (error) {
+    // Clean up temp file on error
+    try {
+      await $`rm ${tempFile}`.quiet();
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    const message = error instanceof Error ? error.message : "Unknown error";
+
+    if (message.includes("not found") || message.includes("ENOENT")) {
+      return err({
+        code: "COMMAND_FAILED",
+        message: "GitHub CLI (gh) not installed. Install from: https://cli.github.com/",
+      });
+    }
+
+    return err({
+      code: "COMMAND_FAILED",
+      message: `Failed to post comment: ${message}`,
+    });
+  }
+}

package/src/github/diff.ts

@@ -0,0 +1,90 @@
+/**
+ * GitHub CLI wrapper for diff extraction.
+ * Uses `gh pr diff` to get PR changes.
+ */
+
+import { $ } from "bun";
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+
+export interface DiffError {
+  code: "NOT_FOUND" | "AUTH_ERROR" | "COMMAND_FAILED";
+  message: string;
+}
+
+/**
+ * Get the raw diff for a pull request using gh CLI.
+ * 
+ * @param prNumber - The PR number to get diff for
+ * @returns Result containing raw diff string or error
+ */
+export async function getPRDiff(prNumber: number): Promise<Result<string, DiffError>> {
+  try {
+    // Use Bun's shell operator to run gh pr diff
+    const result = await $`gh pr diff ${prNumber}`.quiet();
+    
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString();
+      
+      // Check for common error patterns
+      if (stderr.includes("Could not find pull request")) {
+        return err({
+          code: "NOT_FOUND",
+          message: `PR #${prNumber} not found`,
+        });
+      }
+      
+      if (stderr.includes("authentication") || stderr.includes("gh auth login")) {
+        return err({
+          code: "AUTH_ERROR",
+          message: "GitHub CLI not authenticated. Run: gh auth login",
+        });
+      }
+      
+      return err({
+        code: "COMMAND_FAILED",
+        message: `gh pr diff failed: ${stderr}`,
+      });
+    }
+    
+    return ok(result.stdout.toString());
+  } catch (error) {
+    // Handle case where gh CLI is not installed
+    const message = error instanceof Error ? error.message : "Unknown error";
+    
+    if (message.includes("not found") || message.includes("ENOENT")) {
+      return err({
+        code: "COMMAND_FAILED",
+        message: "GitHub CLI (gh) not installed. Install from: https://cli.github.com/",
+      });
+    }
+    
+    return err({
+      code: "COMMAND_FAILED",
+      message: `Failed to get diff: ${message}`,
+    });
+  }
+}
+
+/**
+ * Check if gh CLI is available and authenticated.
+ */
+export async function checkGHCLI(): Promise<Result<boolean, DiffError>> {
+  try {
+    const result = await $`gh auth status`.quiet();
+    
+    if (result.exitCode !== 0) {
+      return err({
+        code: "AUTH_ERROR",
+        message: "GitHub CLI not authenticated. Run: gh auth login",
+      });
+    }
+    
+    return ok(true);
+  } catch {
+    return err({
+      code: "COMMAND_FAILED",
+      message: "GitHub CLI (gh) not installed",
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env bun
+
+/**
+ * SpecVector CLI - Context-aware AI code review
+ */
+
+import { getPRDiff } from "./github/diff";
+import { postPRComment } from "./github/comment";
+import { parseDiff, getDiffSummary } from "./review/diff-parser";
+import { formatReviewComment, formatReviewSummary } from "./review/formatter";
+import { runReview } from "./review/engine";
+
+const VERSION = "0.1.0";
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // Handle --help and --version
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(`SpecVector v${VERSION}`);
+    return;
+  }
+
+  // Parse command
+  const command = args[0];
+
+  if (!command) {
+    printHelp();
+    return;
+  }
+
+  if (command === "review") {
+    await handleReview(args.slice(1));
+  } else {
+    console.error(`Unknown command: ${command}`);
+    console.error("Run with --help for usage information.");
+    process.exit(1);
+  }
+}
+
+function printHelp(): void {
+  console.log(`SpecVector CLI v${VERSION}
+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
+
+OPTIONS:
+  --dry-run    Preview the review comment without posting to GitHub
+  --mock       Use mock review instead of LLM (for testing)
+
+ENVIRONMENT:
+  OPENROUTER_API_KEY       API key for OpenRouter
+  SPECVECTOR_PROVIDER      LLM provider (openrouter or ollama)
+  SPECVECTOR_MODEL         Model to use
+
+EXAMPLES:
+  specvector review 123             Review PR #123 with AI and post comment
+  specvector review 123 --dry-run   Preview AI review for PR #123
+  specvector review 123 --mock      Use mock review (no LLM calls)
+`);
+}
+
+async function handleReview(args: string[]): Promise<void> {
+  const dryRun = args.includes("--dry-run");
+  const useMock = args.includes("--mock");
+  const prNumberArg = args.find((arg) => !arg.startsWith("--"));
+
+  if (!prNumberArg) {
+    console.error("Error: PR number required");
+    console.error("Usage: specvector review <pr-number>");
+    process.exit(1);
+  }
+
+  const prNumber = parseInt(prNumberArg, 10);
+
+  if (isNaN(prNumber) || prNumber <= 0) {
+    console.error(`Error: Invalid PR number: ${prNumberArg}`);
+    process.exit(1);
+  }
+
+  console.log(`🔍 Reviewing PR #${prNumber}...`);
+  if (dryRun) {
+    console.log("   (dry run - will not post comment)");
+  }
+  if (useMock) {
+    console.log("   (mock mode - no LLM calls)");
+  }
+  console.log("");
+
+  // Step 1: Get the diff
+  console.log("📥 Fetching diff...");
+  const diffResult = await getPRDiff(prNumber);
+
+  if (!diffResult.ok) {
+    console.error(`❌ ${diffResult.error.message}`);
+    process.exit(1);
+  }
+
+  const rawDiff = diffResult.value;
+
+  if (!rawDiff.trim()) {
+    console.log("ℹ️  No changes found in this PR.");
+    return;
+  }
+
+  // Step 2: Parse the diff
+  console.log("📊 Parsing diff...");
+  const parsedDiff = parseDiff(rawDiff);
+  const diffSummary = getDiffSummary(parsedDiff);
+
+  console.log("");
+  console.log("📋 Diff Summary:");
+  console.log("─".repeat(40));
+  console.log(diffSummary);
+  console.log("─".repeat(40));
+  console.log("");
+
+  // Step 3: Generate review (AI or mock)
+  if (useMock) {
+    console.log("🤖 Generating mock review...");
+    const mockReview = generateMockReview(parsedDiff.filesChanged);
+    displayAndPostReview(mockReview, prNumber, dryRun);
+  } else {
+    console.log("🤖 Running AI review...");
+    console.log("   (this may take 15-30 seconds)");
+    console.log("");
+
+    // Get branch name for Linear context
+    // In GitHub Actions PRs, GITHUB_HEAD_REF contains the branch name
+    // Fallback to git command for local development
+    let branchName: string | undefined = process.env.GITHUB_HEAD_REF;
+    if (!branchName) {
+      try {
+        const { stdout } = Bun.spawnSync(["git", "rev-parse", "--abbrev-ref", "HEAD"]);
+        const branch = new TextDecoder().decode(stdout).trim();
+        if (branch && branch !== "HEAD") {
+          branchName = branch;
+        }
+      } catch {
+        // Ignore - branch extraction is optional
+      }
+    }
+    if (branchName) {
+      console.log(`📌 Branch: ${branchName}`);
+    }
+
+    const reviewResult = await runReview(rawDiff, diffSummary, {
+      workingDir: process.cwd(),
+      branchName,
+    });
+
+    if (!reviewResult.ok) {
+      console.error(`❌ Review failed: ${reviewResult.error.message}`);
+      console.error("");
+      console.error("Tip: Run with --mock to test without LLM");
+      process.exit(1);
+    }
+
+    displayAndPostReview(reviewResult.value, prNumber, dryRun);
+  }
+}
+
+async function displayAndPostReview(
+  reviewResult: import("./types/review").ReviewResult,
+  prNumber: number,
+  dryRun: boolean
+): Promise<void> {
+  // Display review summary
+  console.log("");
+  console.log("📝 Review Result:");
+  console.log("─".repeat(40));
+  console.log(formatReviewSummary(reviewResult));
+  console.log("─".repeat(40));
+  console.log("");
+
+  // Post or preview comment
+  if (dryRun) {
+    console.log("📄 Comment Preview:");
+    console.log("═".repeat(50));
+    console.log(formatReviewComment(reviewResult));
+    console.log("═".repeat(50));
+    console.log("");
+    console.log("✅ Dry run complete (no comment posted)");
+  } else {
+    console.log("💬 Posting comment to PR...");
+    const commentBody = formatReviewComment(reviewResult);
+    const postResult = await postPRComment(prNumber, commentBody);
+
+    if (!postResult.ok) {
+      console.error(`❌ Failed to post comment: ${postResult.error.message}`);
+      process.exit(1);
+    }
+
+    console.log("✅ Review posted successfully!");
+  }
+}
+
+/**
+ * Generate a mock review result (for testing without LLM).
+ */
+function generateMockReview(filesReviewed: number): import("./types/review").ReviewResult {
+  const { calculateStats, determineRecommendation } = require("./types/review");
+  
+  const findings: import("./types/review").ReviewFinding[] = [
+    {
+      severity: "MEDIUM" as const,
+      category: "Code Quality",
+      title: "Consider adding error handling",
+      description: "The function does not handle potential edge cases.",
+      suggestion: "Add try/catch block or validate inputs.",
+    },
+    {
+      severity: "LOW" as const,
+      category: "Documentation",
+      title: "Missing JSDoc comment",
+      description: "Public functions should have JSDoc comments.",
+      suggestion: "Add JSDoc describing parameters and return value.",
+    },
+  ];
+
+  const stats = calculateStats(findings);
+  const recommendation = determineRecommendation(stats);
+
+  return {
+    findings,
+    summary: "This is a mock review for testing. Run without --mock for AI-powered review.",
+    recommendation,
+    stats,
+    filesReviewed,
+  };
+}
+
+// Run the CLI
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});