specvector 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specvector",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Context-aware AI code review using Model Context Protocol (MCP)",
   "type": "module",
   "main": "src/index.ts",

package/src/config/index.ts

@@ -24,6 +24,8 @@ export interface SpecVectorConfig {
   maxFileSize: number;
   /** Maximum iterations for agent */
   maxIterations: number;
+  /** Path to ADR directory: string = use path, null = disabled, undefined = auto-detect */
+  adrPath?: string | null;
 }
 
 /** Default configuration */
@@ -47,6 +49,7 @@ export const DEFAULT_CONFIG: SpecVectorConfig = {
   strictness: "normal",
   maxFileSize: 100 * 1024, // 100KB
   maxIterations: 15,
+  // adrPath omitted = auto-detect; set to null to explicitly disable
 };
 
 /** Config file name */
@@ -112,7 +115,7 @@ function parseYamlConfig(content: string): Partial<SpecVectorConfig> {
   const lines = content.split("\n");
   const warnings: string[] = [];
   
-  const validKeys = ["provider", "model", "strictness", "maxFileSize", "maxIterations", "ignore"];
+  const validKeys = ["provider", "model", "strictness", "maxFileSize", "maxIterations", "ignore", "adrPath"];
   
   let currentKey: string | null = null;
   let currentArray: string[] = [];
@@ -199,6 +202,16 @@ function parseYamlConfig(content: string): Partial<SpecVectorConfig> {
             }
             break;
           }
+          case "adrPath": {
+            // Support explicit disable with null, false, none, or empty
+            const lower = cleanValue.toLowerCase();
+            if (lower === "null" || lower === "false" || lower === "none" || lower === "") {
+              result.adrPath = null; // Explicitly disabled
+            } else {
+              result.adrPath = cleanValue;
+            }
+            break;
+          }
         }
       }
     }

package/src/context/adr.ts

@@ -0,0 +1,249 @@
+/**
+ * ADR Context Provider - Reads Architecture Decision Records for reviews.
+ *
+ * Scans a configurable directory for markdown files and includes them
+ * as context in the review prompt.
+ */
+
+import { readdir, readFile, stat } from "fs/promises";
+import { join, basename, resolve, isAbsolute, relative } from "path";
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ADRFile {
+  /** Filename (e.g., "001-use-bun-runtime.md") */
+  name: string;
+  /** Full file content */
+  content: string;
+}
+
+export interface ADRContext {
+  /** List of ADR files found */
+  files: ADRFile[];
+  /** Number of files loaded */
+  count: number;
+  /** Path that was scanned */
+  path: string;
+}
+
+export interface ADRContextError {
+  code: "PATH_NOT_FOUND" | "READ_ERROR" | "NO_FILES";
+  message: string;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Maximum ADR file size (50KB) */
+const MAX_ADR_FILE_SIZE = 50 * 1024;
+
+/** Maximum number of ADR files to read */
+const MAX_ADR_FILES = 20;
+
+/** Supported file extensions */
+const ADR_EXTENSIONS = [".md", ".markdown"];
+
+/** Common paths to auto-detect (in priority order) */
+const AUTO_DETECT_PATHS = [
+  "_bmad-output/planning-artifacts",  // BMAD projects
+  "docs/adr",                          // Standard ADR location
+  "docs/architecture",                 // Common alternative
+  "adr",                               // Simple ADR folder
+];
+
+// ============================================================================
+// Main Function
+// ============================================================================
+
+/**
+ * Read ADR files from a directory.
+ *
+ * @param workingDir - The project root directory
+ * @param adrPath - Relative path to ADR directory (e.g., "docs/adr")
+ */
+export async function getADRContext(
+  workingDir: string,
+  adrPath: string
+): Promise<Result<ADRContext, ADRContextError>> {
+  // Security: reject absolute paths
+  if (isAbsolute(adrPath)) {
+    return err({
+      code: "PATH_NOT_FOUND",
+      message: `ADR path must be relative, not absolute: ${adrPath}`,
+    });
+  }
+
+  // Security: reject path traversal attempts
+  if (adrPath.includes("..")) {
+    return err({
+      code: "PATH_NOT_FOUND",
+      message: `ADR path cannot contain '..': ${adrPath}`,
+    });
+  }
+
+  const fullPath = resolve(workingDir, adrPath);
+  const resolvedWorkingDir = resolve(workingDir);
+
+  // Security: use path.relative for portable containment check
+  const relativePath = relative(resolvedWorkingDir, fullPath);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    return err({
+      code: "PATH_NOT_FOUND",
+      message: `ADR path must be within project directory: ${adrPath}`,
+    });
+  }
+
+  // Check if directory exists
+  try {
+    const stats = await stat(fullPath);
+    if (!stats.isDirectory()) {
+      return err({
+        code: "PATH_NOT_FOUND",
+        message: `ADR path is not a directory: ${adrPath}`,
+      });
+    }
+  } catch {
+    return err({
+      code: "PATH_NOT_FOUND",
+      message: `ADR directory not found: ${adrPath}`,
+    });
+  }
+
+  // Read directory contents
+  let entries: string[];
+  try {
+    entries = await readdir(fullPath);
+  } catch (error) {
+    return err({
+      code: "READ_ERROR",
+      message: `Failed to read ADR directory: ${error instanceof Error ? error.message : "Unknown error"}`,
+    });
+  }
+
+  // Filter to markdown files and sort
+  const mdFiles = entries
+    .filter((f) => ADR_EXTENSIONS.some((ext) => f.toLowerCase().endsWith(ext)))
+    .sort(); // Sort alphabetically (ADRs often numbered: 001-xxx.md)
+
+  if (mdFiles.length === 0) {
+    return err({
+      code: "NO_FILES",
+      message: `No ADR markdown files found in: ${adrPath}`,
+    });
+  }
+
+  // Read files until we have MAX_ADR_FILES (don't slice upfront)
+  const files: ADRFile[] = [];
+  for (const filename of mdFiles) {
+    if (files.length >= MAX_ADR_FILES) break;
+    
+    const filePath = join(fullPath, filename);
+    try {
+      const fileStats = await stat(filePath);
+      
+      // Skip files that are too large
+      if (fileStats.size > MAX_ADR_FILE_SIZE) {
+        console.log(`⚠️  Skipping large ADR: ${filename} (${Math.round(fileStats.size / 1024)}KB)`);
+        continue;
+      }
+
+      const content = await readFile(filePath, "utf-8");
+      files.push({
+        name: basename(filename),
+        content: content.trim(),
+      });
+    } catch {
+      // Skip files we can't read
+      console.log(`⚠️  Could not read ADR: ${filename}`);
+    }
+  }
+
+  if (files.length === 0) {
+    return err({
+      code: "NO_FILES",
+      message: `No readable ADR files in: ${adrPath}`,
+    });
+  }
+
+  return ok({
+    files,
+    count: files.length,
+    path: adrPath,
+  });
+}
+
+// ============================================================================
+// Formatting
+// ============================================================================
+
+/**
+ * Format ADR context for inclusion in review prompt.
+ */
+export function formatADRContext(context: ADRContext): string {
+  const lines: string[] = [
+    `## Architecture Decision Records (${context.count} files from ${context.path})`,
+    "",
+  ];
+
+  for (const file of context.files) {
+    lines.push(`### ${file.name}`);
+    lines.push("");
+    lines.push(file.content);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Get ADR context for a review, with graceful error handling.
+ * Returns null if ADRs are not available (no error thrown).
+ * 
+ * Behavior:
+ * - adrPath = string: use the specified path
+ * - adrPath = null: explicitly disabled, no ADR context
+ * - adrPath = undefined: auto-detect common paths
+ */
+export async function getADRContextForReview(
+  workingDir: string,
+  adrPath: string | null | undefined
+): Promise<{ context: ADRContext; formatted: string } | null> {
+  // Explicitly disabled with null
+  if (adrPath === null) {
+    return null;
+  }
+
+  // If path is explicitly set, use it
+  if (adrPath !== undefined) {
+    const result = await getADRContext(workingDir, adrPath);
+    if (!result.ok) {
+      console.log(`⚠️  ADR context unavailable: ${result.error.message}`);
+      return null;
+    }
+    return {
+      context: result.value,
+      formatted: formatADRContext(result.value),
+    };
+  }
+
+  // Auto-detect: try common paths in priority order (adrPath is undefined)
+  for (const path of AUTO_DETECT_PATHS) {
+    const result = await getADRContext(workingDir, path);
+    if (result.ok) {
+      return {
+        context: result.value,
+        formatted: formatADRContext(result.value),
+      };
+    }
+  }
+
+  // No docs found - this is fine, not all projects have ADRs
+  return null;
+}

package/src/context/index.ts

@@ -9,3 +9,12 @@ export {
   type LinearTicket,
   type LinearContextError,
 } from "./linear";
+
+export {
+  getADRContext,
+  getADRContextForReview,
+  formatADRContext,
+  type ADRContext,
+  type ADRFile,
+  type ADRContextError,
+} from "./adr";

package/src/review/engine.ts

@@ -20,7 +20,7 @@ import type { ReviewResult, ReviewFinding, Severity } from "../types/review";
 import type { Result } from "../types/result";
 import { ok, err } from "../types/result";
 import { loadConfig, getStrictnessModifier } from "../config";
-import { getLinearContextForReview } from "../context";
+import { getLinearContextForReview, getADRContextForReview } from "../context";
 
 /** Review engine configuration */
 export interface ReviewConfig {
@@ -109,12 +109,18 @@ export async function runReview(
 
   if (linearResult.context) {
     systemPrompt = linearResult.context + "\n\n" + systemPrompt;
-    // linearResult.ticketId available for future use (e.g., in review output)
     console.log(`📎 Loaded Linear context for ticket: ${linearResult.ticketId}`);
   } else if (linearResult.warning) {
     console.warn(`⚠️  ${linearResult.warning}`);
   }
 
+  // Fetch ADR context if configured
+  const adrResult = await getADRContextForReview(config.workingDir, fileConfig.adrPath);
+  if (adrResult) {
+    systemPrompt = adrResult.formatted + "\n\n" + systemPrompt;
+    console.log(`📚 Loaded ${adrResult.context.count} ADR files from ${adrResult.context.path}`);
+  }
+
   // Create agent
   const agent = createAgentLoop(providerResult.value, tools, {
     maxIterations: config.maxIterations || fileConfig.maxIterations || 15,