specvector 0.1.9 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specvector",
-  "version": "0.1.9",
+  "version": "0.3.1",
   "description": "Context-aware AI code review using Model Context Protocol (MCP)",
   "type": "module",
   "main": "src/index.ts",
@@ -44,9 +44,7 @@
   "engines": {
     "bun": ">=1.0.0"
   },
-  "dependencies": {
-    "@larryhudson/linear-mcp-server": "0.1.4"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/bun": "latest"
   },

package/src/agent/loop.ts

@@ -17,6 +17,7 @@
 import { ok, err } from "../types/result";
 import type { Message, ToolCall } from "../types/llm";
 import type { LLMProvider, LLMError } from "../llm/provider";
+import { withRetry } from "../llm/provider";
 import type {
   Tool,
   AgentConfig,
@@ -70,12 +71,15 @@ export class AgentLoop {
         return err(AgentErrors.timeout());
       }
 
-      // Get LLM response
-      const llmResult = await this.provider.chat(
-        messages,
-        {
-          tools: Array.from(this.tools.values()).map(toolToLLMTool),
-        }
+      // Get LLM response with retry on transient errors
+      const llmResult = await withRetry(
+        () => this.provider.chat(
+          messages,
+          {
+            tools: Array.from(this.tools.values()).map(toolToLLMTool),
+          }
+        ),
+        { maxRetries: 1, delayMs: 2000 }
       );
 
       if (!llmResult.ok) {

package/src/context/linear.ts

@@ -1,9 +1,10 @@
 /**
  * Linear Context Provider - Fetches ticket context for reviews.
  *
- * Extracts ticket ID from branch name/PR and fetches details via Linear GraphQL API.
+ * 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";
 
@@ -12,12 +13,12 @@ import { ok, err } from "../types/result";
 // ============================================================================
 
 export interface LinearTicket {
-  identifier?: string;
-  title?: string;
-  description?: string;
-  state?: { name?: string };
-  priority?: number;
-  labels?: { nodes?: Array<{ name?: string }> };
+  id: string;
+  title: string;
+  description: string;
+  state: string;
+  priority: number;
+  labels: string[];
 }
 
 export interface LinearContextError {
@@ -72,14 +73,21 @@ export function extractTicketId(
 // Linear Context Fetching
 // ============================================================================
 
+/** Extended ticket data from Linear MCP */
+export interface LinearTicketData {
+  context: string;
+  title?: string;
+  url?: string;
+}
+
 /**
  * Fetch Linear ticket context for a review.
  *
- * Uses Linear's GraphQL API directly - simpler and more reliable than MCP.
+ * Returns formatted context string and extracted metadata.
  */
 export async function fetchLinearContext(
   ticketId: string
-): Promise<Result<string, LinearContextError>> {
+): Promise<Result<LinearTicketData, LinearContextError>> {
   // Check for API token
   const apiToken = process.env.LINEAR_API_TOKEN;
   if (!apiToken) {
@@ -89,85 +97,83 @@ export async function fetchLinearContext(
     });
   }
 
-  try {
-    // Use Linear GraphQL API directly
-    const response = await fetch("https://api.linear.app/graphql", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: apiToken,
-      },
-      body: JSON.stringify({
-        query: `
-          query GetIssue($id: String!) {
-            issue(id: $id) {
-              identifier
-              title
-              description
-              state { name }
-              priority
-              labels { nodes { name } }
-            }
-          }
-        `,
-        variables: { id: ticketId },
-      }),
+  // 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;
 
-    if (!response.ok) {
+  try {
+    // Fetch issue details using Linear MCP
+    const ticketResult = await client.callTool("get_issue", { issue_id: ticketId });
+
+    if (!ticketResult.ok) {
       return err({
         code: "FETCH_FAILED",
-        message: `Linear API error: ${response.status}`,
+        message: ticketResult.error.message,
       });
     }
 
-    const data = await response.json() as { data?: { issue?: LinearTicket | null }; errors?: Array<{ message: string }> };
+    // Parse the response
+    const content = ticketResult.value.content;
+    const textContent = content.find(c => c.type === "text");
     
-    if (data.errors?.length) {
+    if (!textContent?.text) {
       return err({
         code: "FETCH_FAILED",
-        message: data.errors[0]?.message ?? "GraphQL error",
+        message: "No ticket data returned",
       });
     }
 
-    const issue = data.data?.issue;
-    if (!issue) {
-      return err({
-        code: "FETCH_FAILED",
-        message: `Issue ${ticketId} not found`,
-      });
-    }
+    const ticketText = textContent.text;
+    
+    // Extract URL from MCP response if present (Linear API includes url field)
+    // Pattern matches: "url": "https://linear.app/..." or URL: https://linear.app/...
+    const urlMatch = ticketText.match(/"?url"?:\s*"?(https:\/\/linear\.app\/[^"\s]+)"?/i);
+    const extractedUrl = urlMatch?.[1];
+    
+    // Extract title from MCP response if present
+    const titleMatch = ticketText.match(/"?title"?:\s*"([^"]+)"/i);
+    const extractedTitle = titleMatch?.[1];
 
     // Format the context for the review prompt
-    const contextBlock = formatLinearContext(ticketId, issue);
-    return ok(contextBlock);
-
-  } catch (error) {
-    return err({
-      code: "FETCH_FAILED",
-      message: error instanceof Error ? error.message : "Unknown error",
+    const contextBlock = formatLinearContext(ticketId, ticketText);
+    
+    return ok({
+      context: contextBlock,
+      title: extractedTitle,
+      url: extractedUrl,
     });
+
+  } finally {
+    await client.close();
   }
 }
 
 /**
- * Format Linear issue data as context for review prompt.
+ * Format Linear ticket data as context for review prompt.
  */
-function formatLinearContext(ticketId: string, issue: { title?: string; description?: string; state?: { name?: string }; priority?: number; labels?: { nodes?: Array<{ name?: string }> } }): string {
-  const labels = issue.labels?.nodes?.map(l => l.name).filter(Boolean).join(", ") || "none";
-  const priority = issue.priority ?? 0;
-  const priorityLabels = ["", "Urgent", "High", "Medium", "Low", "No Priority"];
-
+function formatLinearContext(ticketId: string, ticketData: string): string {
   return `
 ## Linear Ticket Context: ${ticketId}
 
-**Title:** ${issue.title ?? "Untitled"}
-**Status:** ${issue.state?.name ?? "Unknown"}
-**Priority:** ${priorityLabels[priority] ?? "Unknown"}
-**Labels:** ${labels}
+The following is the context from the linked Linear ticket. Use this to understand the business requirements and acceptance criteria for this PR.
 
-### Description
-${issue.description ?? "No description provided."}
+${ticketData}
 
 ---
 When reviewing, check that the PR changes align with the ticket requirements above.
@@ -184,7 +190,7 @@ export async function getLinearContextForReview(
   branchName?: string,
   prTitle?: string,
   prBody?: string
-): Promise<{ context: string | null; ticketId: string | null; warning?: string }> {
+): Promise<{ context: string | null; ticketId: string | null; ticketTitle?: string; ticketUrl?: string; warning?: string }> {
   // Extract ticket ID
   const ticketId = extractTicketId(branchName, prTitle, prBody);
 
@@ -212,8 +218,14 @@ export async function getLinearContextForReview(
     };
   }
 
+  const { context, title, url } = result.value;
+  
   return {
-    context: result.value,
+    context,
     ticketId,
+    // Use extracted title from MCP if available, fallback to generic
+    ticketTitle: title ?? `Linear Ticket ${ticketId}`,
+    // Use extracted URL from MCP if available (no fallback - better to have no link than broken link)
+    ticketUrl: url,
   };
 }

package/src/llm/index.ts

@@ -33,8 +33,8 @@ export type {
 } from "../types/llm";
 
 // Re-export provider interface and errors
-export type { LLMProvider, LLMError, LLMErrorCode } from "./provider";
-export { LLMErrors, isRetryableError, createLLMError } from "./provider";
+export type { LLMProvider, LLMError, LLMErrorCode, RetryConfig } from "./provider";
+export { LLMErrors, isRetryableError, createLLMError, withRetry } from "./provider";
 
 // Re-export factory
 export {

package/src/llm/provider.ts

@@ -131,3 +131,70 @@ export const LLMErrors = {
       retryable: false,
     }),
 };
+
+/**
+ * Retry configuration for LLM calls.
+ */
+export interface RetryConfig {
+  /** Maximum number of retries (default: 1) */
+  maxRetries?: number;
+  /** Delay between retries in ms (default: 2000) */
+  delayMs?: number;
+  /** Whether to log retry attempts (default: true) */
+  logRetries?: boolean;
+}
+
+/**
+ * Wrap an async function with retry logic for transient errors.
+ * 
+ * @param fn - Async function returning Result<T, LLMError>
+ * @param config - Retry configuration
+ * @returns Result with success value or final error
+ */
+export async function withRetry<T>(
+  fn: () => Promise<Result<T, LLMError>>,
+  config: RetryConfig = {}
+): Promise<Result<T, LLMError>> {
+  const maxRetries = config.maxRetries ?? 1;
+  const delayMs = config.delayMs ?? 2000;
+  const logRetries = config.logRetries ?? true;
+
+  let lastError: LLMError | undefined;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await fn();
+    
+    if (result.ok) {
+      return result;
+    }
+    
+    lastError = result.error;
+    
+    // Check if we should retry
+    if (attempt < maxRetries && isRetryableError(result.error)) {
+      const retryDelay = result.error.retryAfterMs ?? delayMs;
+      
+      if (logRetries) {
+        console.warn(
+          `⚠️  LLM call failed (${result.error.code}), retrying in ${retryDelay}ms... (${attempt + 1}/${maxRetries})`
+        );
+      }
+      
+      await sleep(retryDelay);
+      continue;
+    }
+    
+    // Non-retryable error or max retries reached
+    return result;
+  }
+  
+  // Should not reach here, but return last error if we do
+  return { ok: false, error: lastError! };
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/review/engine.ts

@@ -16,7 +16,7 @@ import { createListDirTool } from "../agent/tools/list-dir";
 import { createOutlineTool } from "../agent/tools/outline";
 import { createFindSymbolTool } from "../agent/tools/find-symbol";
 import { calculateStats, determineRecommendation } from "../types/review";
-import type { ReviewResult, ReviewFinding, Severity } from "../types/review";
+import type { ReviewResult, ReviewFinding, Severity, ContextSource } from "../types/review";
 import type { Result } from "../types/result";
 import { ok, err } from "../types/result";
 import { loadConfig, getStrictnessModifier } from "../config";
@@ -100,6 +100,9 @@ export async function runReview(
   const strictnessGuidance = getStrictnessModifier(strictness);
   let systemPrompt = REVIEW_SYSTEM_PROMPT + `\n\n## Strictness Setting: ${strictness.toUpperCase()}\n${strictnessGuidance}`;
 
+  // Track context sources for citation
+  const contextSources: ContextSource[] = [];
+
   // Fetch Linear context if available
   const linearResult = await getLinearContextForReview(
     config.branchName,
@@ -110,6 +113,16 @@ export async function runReview(
   if (linearResult.context) {
     systemPrompt = linearResult.context + "\n\n" + systemPrompt;
     console.log(`📎 Loaded Linear context for ticket: ${linearResult.ticketId}`);
+    
+    // Track Linear as a context source (only if we have a valid ticket ID)
+    if (linearResult.ticketId) {
+      contextSources.push({
+        type: "linear",
+        id: linearResult.ticketId,
+        title: linearResult.ticketTitle,
+        url: linearResult.ticketUrl,
+      });
+    }
   } else if (linearResult.warning) {
     console.warn(`⚠️  ${linearResult.warning}`);
   }
@@ -119,12 +132,21 @@ export async function runReview(
   if (adrResult) {
     systemPrompt = adrResult.formatted + "\n\n" + systemPrompt;
     console.log(`📚 Loaded ${adrResult.context.count} ADR files from ${adrResult.context.path}`);
+    
+    // Track each ADR file as a context source
+    for (const adrFile of adrResult.context.files) {
+      contextSources.push({
+        type: "adr",
+        id: adrFile.name,
+        title: adrFile.name.replace(".md", ""),
+      });
+    }
   }
 
   // Create agent
   const agent = createAgentLoop(providerResult.value, tools, {
     maxIterations: config.maxIterations || fileConfig.maxIterations || 15,
-    timeoutMs: 3 * 60 * 1000, // 3 minutes
+    timeoutMs: 15 * 60 * 1000, // 15 minutes for larger PRs with slower models
     systemPrompt,
   });
 
@@ -142,7 +164,7 @@ export async function runReview(
   }
 
   // Parse the response into structured findings
-  const reviewResult = parseReviewResponse(agentResult.value, diffSummary);
+  const reviewResult = parseReviewResponse(agentResult.value, diffSummary, contextSources);
 
   return ok(reviewResult);
 }
@@ -214,7 +236,7 @@ ${diff.length > 15000 ? "\n(diff truncated, use tools to read full files if need
 /**
  * Parse the agent's response into structured findings.
  */
-function parseReviewResponse(response: string, diffSummary: string): ReviewResult {
+function parseReviewResponse(response: string, diffSummary: string, contextSources: ContextSource[] = []): ReviewResult {
   const findings: ReviewFinding[] = [];
   
   // Extract summary
@@ -270,5 +292,6 @@ function parseReviewResponse(response: string, diffSummary: string): ReviewResul
     recommendation,
     stats,
     filesReviewed: parseInt(filesReviewed, 10) || 0,
+    contextSources: contextSources.length > 0 ? contextSources : undefined,
   };
 }

package/src/review/formatter.ts

@@ -3,7 +3,7 @@
  * Converts ReviewResult into markdown for PR comments.
  */
 
-import type { ReviewFinding, ReviewResult, Severity } from "../types/review";
+import type { ReviewFinding, ReviewResult, Severity, ContextSource } from "../types/review";
 
 /**
  * Severity emoji indicators.
@@ -60,6 +60,14 @@ export function formatReviewComment(result: ReviewResult): string {
   lines.push(result.summary);
   lines.push("");
 
+  // Context Used section (if any context was used)
+  if (result.contextSources && result.contextSources.length > 0) {
+    lines.push("### Context Used");
+    lines.push("");
+    lines.push(...formatContextSources(result.contextSources));
+    lines.push("");
+  }
+
   // Findings by severity (only include sections with findings)
   if (result.stats.critical > 0) {
     lines.push("---");
@@ -134,6 +142,35 @@ function formatFindings(findings: ReviewFinding[], severity: Severity): string[]
   return lines;
 }
 
+/**
+ * Format context sources for the Context Used section.
+ * Renders Linear tickets with clickable links and ADR files as a list.
+ */
+function formatContextSources(sources: ContextSource[]): string[] {
+  const lines: string[] = [];
+  
+  // Group sources by type
+  const linearSources = sources.filter(s => s.type === "linear");
+  const adrSources = sources.filter(s => s.type === "adr");
+  
+  // Format Linear tickets
+  for (const source of linearSources) {
+    if (source.url) {
+      lines.push(`- **Linear ticket:** [${source.id}](${source.url})`);
+    } else {
+      lines.push(`- **Linear ticket:** ${source.id}`);
+    }
+  }
+  
+  // Format ADR files
+  if (adrSources.length > 0) {
+    const adrList = adrSources.map(s => `\`${s.id}\``).join(", ");
+    lines.push(`- **ADRs referenced:** ${adrList}`);
+  }
+  
+  return lines;
+}
+
 /**
  * Format recommendation as human-readable text.
  */

package/src/types/review.ts

@@ -32,6 +32,25 @@ export interface ReviewFinding {
  */
 export type Recommendation = "APPROVE" | "REQUEST_CHANGES" | "COMMENT";
 
+/**
+ * Type of external context source used in the review.
+ */
+export type ContextSourceType = "linear" | "adr";
+
+/**
+ * External context source that informed the review.
+ */
+export interface ContextSource {
+  /** Type of context source */
+  type: ContextSourceType;
+  /** Identifier (ticket ID or file path) */
+  id: string;
+  /** Display title */
+  title?: string;
+  /** URL for clickable link (Linear tickets) */
+  url?: string;
+}
+
 /**
  * Statistics about the review findings.
  */
@@ -57,6 +76,8 @@ export interface ReviewResult {
   stats: ReviewStats;
   /** Files that were reviewed */
   filesReviewed: number;
+  /** External context sources used in the review */
+  contextSources?: ContextSource[];
 }
 
 /**