skannr 0.2.0 → 0.2.1

package/src/guard/review-runner.ts

@@ -0,0 +1,110 @@
+/**
+ * Review runner — orchestrates the full guard pipeline:
+ * build symbol diffs → enrich with call context → batch → call LLM → validate.
+ */
+
+import { loadRules, loadGuardConfig } from './rules-loader';
+import { buildSymbolDiffs, buildSymbolDiffsFromDiff } from './symbol-diff';
+import { enrichWithCallContext } from './call-context';
+import { runLlmReview } from './provider';
+import type { GuardResult, ReviewResponse, SymbolDiffUnit } from './types';
+
+/** Maximum symbols to include in a single LLM call. */
+const BATCH_SIZE = 15;
+
+export interface RunOptions {
+  /** Project root directory. */
+  root: string;
+  /** If provided, review this diff instead of staged files. */
+  diffContent?: string;
+  /** Skip cross-file caller/callee context (faster, cheaper). */
+  diffOnly?: boolean;
+  /** Skip symbol cache. */
+  noCache?: boolean;
+}
+
+/**
+ * Run the full guard review pipeline.
+ * Returns a GuardResult with violations, or throws with exit code 2 errors.
+ */
+export async function runGuardReview(options: RunOptions): Promise<GuardResult> {
+  const { root, diffContent, diffOnly = false } = options;
+  const started = Date.now();
+
+  // 1. Load rules
+  const rules = loadRules(root);
+
+  // 2. Load provider config
+  const config = loadGuardConfig(root);
+
+  // 3. Build symbol-level diffs
+  let units: SymbolDiffUnit[];
+  if (diffContent) {
+    units = buildSymbolDiffsFromDiff(root, diffContent);
+  } else {
+    units = buildSymbolDiffs(root);
+  }
+
+  if (units.length === 0) {
+    return {
+      response: {
+        violations: [],
+        status: 'pass',
+        summary: 'No staged changes with identifiable symbols to review.',
+      },
+      rulesUsed: rules,
+      symbolsReviewed: 0,
+      durationMs: Date.now() - started,
+    };
+  }
+
+  // 4. Enrich with call context (unless --diff-only)
+  if (!diffOnly) {
+    units = enrichWithCallContext(units, root);
+  }
+
+  // 5. Batch and review
+  const allViolations: ReviewResponse['violations'] = [];
+  const batches = batchUnits(units, BATCH_SIZE);
+
+  // Run batches concurrently (up to 3 in parallel)
+  const CONCURRENCY = 3;
+  for (let i = 0; i < batches.length; i += CONCURRENCY) {
+    const chunk = batches.slice(i, i + CONCURRENCY);
+    const results = await Promise.all(
+      chunk.map((batch) => runLlmReview(config, rules, batch)),
+    );
+    for (const result of results) {
+      allViolations.push(...result.violations);
+    }
+  }
+
+  // 6. Determine status
+  const hasHighConfidenceFail = allViolations.some(
+    (v) => v.confidence >= 0.7 && (v.severity === 'high' || v.severity === 'critical'),
+  );
+
+  const response: ReviewResponse = {
+    violations: allViolations,
+    status: hasHighConfidenceFail ? 'fail' : 'pass',
+    summary: allViolations.length === 0
+      ? `All ${units.length} symbol(s) pass review.`
+      : `${allViolations.length} violation(s) found across ${units.length} symbol(s).`,
+  };
+
+  return {
+    response,
+    rulesUsed: rules,
+    symbolsReviewed: units.length,
+    durationMs: Date.now() - started,
+  };
+}
+
+/** Split units into batches of the given size. */
+function batchUnits(units: SymbolDiffUnit[], size: number): SymbolDiffUnit[][] {
+  const batches: SymbolDiffUnit[][] = [];
+  for (let i = 0; i < units.length; i += size) {
+    batches.push(units.slice(i, i + size));
+  }
+  return batches;
+}

package/src/guard/rules-loader.ts

@@ -0,0 +1,97 @@
+/**
+ * Load and validate the rules file (.skannr/rules.json or .skannr/rules.yaml).
+ * Returns validated rules or throws with a clear error message.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { RulesFileSchema } from './schema';
+import type { GuardRule, GuardConfig } from './types';
+import { GuardConfigSchema } from './schema';
+
+/** Default locations to search for the rules file. */
+const RULES_PATHS = [
+  '.skannr/rules.json',
+  '.skannr/rules.yaml',
+  '.skannr/rules.yml',
+];
+
+/** Load and validate rules from the project root. */
+export function loadRules(root: string): GuardRule[] {
+  const rulesPath = findRulesFile(root);
+  if (!rulesPath) {
+    throw new Error(
+      `No rules file found. Create .skannr/rules.json with your team's review rules.\n` +
+      `Example:\n` +
+      `{\n` +
+      `  "rules": [{\n` +
+      `    "id": "no-any-type",\n` +
+      `    "description": "Do not use the \`any\` type in TypeScript.",\n` +
+      `    "severity": "high",\n` +
+      `    "fixable": true,\n` +
+      `    "category": "type-safety"\n` +
+      `  }]\n` +
+      `}`,
+    );
+  }
+
+  const raw = fs.readFileSync(rulesPath, 'utf-8');
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Failed to parse rules file as JSON: ${rulesPath}`);
+  }
+
+  const result = RulesFileSchema.safeParse(parsed);
+  if (!result.success) {
+    const errors = result.error.issues
+      .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+      .join('\n');
+    throw new Error(`Invalid rules file (${rulesPath}):\n${errors}`);
+  }
+
+  return result.data.rules;
+}
+
+/** Load guard provider configuration from .skannr/guard.json or env vars. */
+export function loadGuardConfig(root: string): GuardConfig {
+  const configPath = path.join(root, '.skannr', 'guard.json');
+
+  let rawConfig: Record<string, unknown> = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch {
+      // Fall through to defaults + env
+    }
+  }
+
+  // Env vars override file config
+  const provider = (process.env.SKANNR_GUARD_PROVIDER || rawConfig.provider || 'gemini') as string;
+  const model = (process.env.SKANNR_GUARD_MODEL || rawConfig.model || 'gemini-2.0-flash-exp') as string;
+  const apiKey = process.env.SKANNR_GUARD_API_KEY
+    || process.env.GEMINI_API_KEY
+    || process.env.OPENAI_API_KEY
+    || (rawConfig.apiKey as string | undefined);
+  const baseUrl = process.env.OPENAI_BASE_URL || (rawConfig.baseUrl as string | undefined);
+
+  const result = GuardConfigSchema.safeParse({ provider, model, apiKey, baseUrl });
+  if (!result.success) {
+    throw new Error(`Invalid guard config: ${result.error.issues.map((i) => i.message).join(', ')}`);
+  }
+
+  return result.data as GuardConfig;
+}
+
+/** Find the first existing rules file in the project. */
+function findRulesFile(root: string): string | null {
+  for (const rel of RULES_PATHS) {
+    const full = path.join(root, rel);
+    if (fs.existsSync(full)) {
+      return full;
+    }
+  }
+  return null;
+}

package/src/guard/schema.ts

@@ -0,0 +1,59 @@
+/**
+ * Zod schemas for rules file validation and LLM response contract enforcement.
+ * These ensure we never parse free text — all LLM output is validated against
+ * a strict schema before being used.
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Rules file schema
+// ---------------------------------------------------------------------------
+
+export const SeveritySchema = z.enum(['low', 'medium', 'high', 'critical']);
+
+export const RuleSchema = z.object({
+  id: z.string().min(1),
+  description: z.string().min(1),
+  severity: SeveritySchema,
+  fixable: z.boolean(),
+  category: z.string().min(1),
+});
+
+export const RulesFileSchema = z.object({
+  rules: z.array(RuleSchema).min(1),
+});
+
+// ---------------------------------------------------------------------------
+// Violation / LLM response schema
+// ---------------------------------------------------------------------------
+
+export const ViolationSchema = z.object({
+  rule_id: z.string().min(1),
+  file: z.string().min(1),
+  symbol: z.string(),
+  line_start: z.number().int().nonnegative(),
+  line_end: z.number().int().nonnegative(),
+  severity: SeveritySchema,
+  confidence: z.number().min(0).max(1),
+  fixable: z.boolean(),
+  message: z.string().min(1),
+  suggested_fix: z.string().optional(),
+});
+
+export const ReviewResponseSchema = z.object({
+  violations: z.array(ViolationSchema),
+  status: z.enum(['pass', 'fail']),
+  summary: z.string().min(1),
+});
+
+// ---------------------------------------------------------------------------
+// Guard config schema (optional .skannr/guard.json)
+// ---------------------------------------------------------------------------
+
+export const GuardConfigSchema = z.object({
+  provider: z.enum(['gemini', 'openai']).default('gemini'),
+  model: z.string().default('gemini-2.0-flash-exp'),
+  apiKey: z.string().optional(),
+  baseUrl: z.string().optional(),
+});

package/src/guard/symbol-diff.ts

@@ -0,0 +1,227 @@
+/**
+ * Build symbol-level diff units from staged git changes.
+ * Uses Skannr's existing parser to identify which symbols changed,
+ * instead of working with raw file diffs.
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { execSync } from 'child_process';
+import { getAdapter } from '../languages/registry';
+import { readFileContent } from '../scanner';
+import type { Symbol } from '../languages/LanguageAdapter';
+import type { SymbolDiffUnit } from './types';
+
+/** Get the list of staged files (paths relative to root). */
+export function getStagedFiles(root: string): string[] {
+  try {
+    const output = execSync('git diff --cached --name-only --diff-filter=ACMR', {
+      cwd: root,
+      encoding: 'utf-8',
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** Get the diff text for a specific staged file. */
+function getStagedDiff(root: string, file: string): string {
+  try {
+    return execSync(`git diff --cached -- "${file}"`, {
+      cwd: root,
+      encoding: 'utf-8',
+      maxBuffer: 5 * 1024 * 1024,
+    });
+  } catch {
+    return '';
+  }
+}
+
+/** Get the old (HEAD) version of a file, or null if newly added. */
+function getHeadContent(root: string, file: string): string | null {
+  try {
+    return execSync(`git show HEAD:"${file}"`, {
+      cwd: root,
+      encoding: 'utf-8',
+      maxBuffer: 5 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** Extract changed line numbers from a unified diff. */
+function extractChangedLines(diff: string): Set<number> {
+  const lines = new Set<number>();
+  let currentLine = 0;
+
+  for (const line of diff.split('\n')) {
+    const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)/);
+    if (hunkMatch) {
+      currentLine = parseInt(hunkMatch[1], 10);
+      continue;
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      lines.add(currentLine);
+      currentLine++;
+    } else if (line.startsWith('-') && !line.startsWith('---')) {
+      // Deleted lines don't advance the new-file line counter
+    } else {
+      currentLine++;
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Determine which symbols in a file were affected by the staged changes.
+ * Matches symbols whose line range overlaps any changed line.
+ */
+function findAffectedSymbols(
+  symbols: Symbol[],
+  changedLines: Set<number>,
+  allSymbols: Symbol[],
+): Symbol[] {
+  if (changedLines.size === 0) return [];
+
+  // Build approximate end lines: each symbol extends until the next symbol starts
+  const sorted = [...allSymbols].sort((a, b) => a.line - b.line);
+  const affected: Symbol[] = [];
+
+  for (let i = 0; i < sorted.length; i++) {
+    const sym = sorted[i];
+    const startLine = sym.line;
+    const endLine = i + 1 < sorted.length ? sorted[i + 1].line - 1 : startLine + 50;
+
+    for (let line = startLine; line <= endLine; line++) {
+      if (changedLines.has(line)) {
+        affected.push(sym);
+        break;
+      }
+    }
+  }
+
+  return affected;
+}
+
+/**
+ * Build symbol-level diff units for all staged files in the project.
+ * This is the primary input to the review runner.
+ */
+export function buildSymbolDiffs(root: string): SymbolDiffUnit[] {
+  const stagedFiles = getStagedFiles(root);
+  const units: SymbolDiffUnit[] = [];
+
+  for (const relFile of stagedFiles) {
+    const absPath = path.join(root, relFile);
+    if (!fs.existsSync(absPath)) continue;
+
+    const adapter = getAdapter(absPath);
+    const newContent = readFileContent(absPath);
+    if (!newContent) continue;
+
+    const newSymbols = adapter.extractSymbols(newContent);
+    const oldContent = getHeadContent(root, relFile);
+    const oldSymbols = oldContent ? adapter.extractSymbols(oldContent) : [];
+
+    const diff = getStagedDiff(root, relFile);
+    const changedLines = extractChangedLines(diff);
+
+    // Find symbols that overlap changed lines in the new version
+    const affected = findAffectedSymbols(newSymbols, changedLines, newSymbols);
+
+    // Determine change type for each affected symbol
+    const oldSymbolNames = new Set(oldSymbols.map((s) => s.name));
+
+    for (const sym of affected) {
+      if (sym.kind === 'export') continue; // skip synthetic export markers
+
+      const changeType = oldSymbolNames.has(sym.name) ? 'modified' : 'added';
+      const oldSym = oldSymbols.find((s) => s.name === sym.name);
+
+      units.push({
+        file: relFile,
+        symbol: sym.name,
+        changeType,
+        oldSignature: oldSym ? `${oldSym.kind} ${oldSym.name}` : undefined,
+        newSignature: `${sym.kind} ${sym.name}`,
+        callers: [],  // populated by call-context module
+        callees: [],  // populated by call-context module
+        diffText: diff,
+      });
+    }
+
+    // Handle deleted symbols (in old but not in new)
+    if (oldContent) {
+      const newSymbolNames = new Set(newSymbols.map((s) => s.name));
+      for (const oldSym of oldSymbols) {
+        if (oldSym.kind === 'export') continue;
+        if (!newSymbolNames.has(oldSym.name)) {
+          units.push({
+            file: relFile,
+            symbol: oldSym.name,
+            changeType: 'deleted',
+            oldSignature: `${oldSym.kind} ${oldSym.name}`,
+            callers: [],
+            callees: [],
+            diffText: diff,
+          });
+        }
+      }
+    }
+  }
+
+  return units;
+}
+
+/**
+ * Build symbol diffs from a PR diff string (for --pr-mode).
+ */
+export function buildSymbolDiffsFromDiff(root: string, diffContent: string): SymbolDiffUnit[] {
+  const parseDiff = require('parse-diff');
+  const parsedFiles = parseDiff(diffContent);
+  const units: SymbolDiffUnit[] = [];
+
+  for (const file of parsedFiles) {
+    const raw = file.to ?? file.from;
+    if (!raw || raw === '/dev/null') continue;
+    const relFile = raw.replace(/^[ab]\//, '');
+    const absPath = path.join(root, relFile);
+    if (!fs.existsSync(absPath)) continue;
+
+    const adapter = getAdapter(absPath);
+    const content = readFileContent(absPath);
+    if (!content) continue;
+
+    const symbols = adapter.extractSymbols(content);
+    const changedLines = new Set<number>();
+
+    for (const chunk of file.chunks) {
+      for (const change of chunk.changes) {
+        if (change.type === 'add' || change.type === 'del') {
+          const ln = (change as any).ln;
+          if (typeof ln === 'number') changedLines.add(ln);
+        }
+      }
+    }
+
+    const affected = findAffectedSymbols(symbols, changedLines, symbols);
+
+    for (const sym of affected) {
+      if (sym.kind === 'export') continue;
+      units.push({
+        file: relFile,
+        symbol: sym.name,
+        changeType: 'modified',
+        newSignature: `${sym.kind} ${sym.name}`,
+        callers: [],
+        callees: [],
+        diffText: file.chunks.map((c: any) => c.content).join('\n'),
+      });
+    }
+  }
+
+  return units;
+}

package/src/guard/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared type definitions for the guard module.
+ */
+
+/** Severity levels for rules and violations. */
+export type Severity = 'low' | 'medium' | 'high' | 'critical';
+
+/** A team-defined review rule. */
+export interface GuardRule {
+  id: string;
+  description: string;
+  severity: Severity;
+  fixable: boolean;
+  category: string;
+}
+
+/** A single symbol-level diff unit sent to the LLM for review. */
+export interface SymbolDiffUnit {
+  file: string;
+  symbol: string;
+  changeType: 'added' | 'modified' | 'deleted';
+  oldSignature?: string;
+  newSignature?: string;
+  callers: string[];
+  callees: string[];
+  diffText: string;
+}
+
+/** A violation found by the review. */
+export interface Violation {
+  rule_id: string;
+  file: string;
+  symbol: string;
+  line_start: number;
+  line_end: number;
+  severity: Severity;
+  confidence: number;
+  fixable: boolean;
+  message: string;
+  suggested_fix?: string;
+}
+
+/** The structured response contract from the LLM. */
+export interface ReviewResponse {
+  violations: Violation[];
+  status: 'pass' | 'fail';
+  summary: string;
+}
+
+/** Result of a full guard run. */
+export interface GuardResult {
+  response: ReviewResponse;
+  rulesUsed: GuardRule[];
+  symbolsReviewed: number;
+  durationMs: number;
+}
+
+/** Guard configuration (provider, model, etc.). */
+export interface GuardConfig {
+  /** LLM provider: 'gemini' | 'openai' */
+  provider: 'gemini' | 'openai';
+  /** Model name (e.g. 'gemini-2.0-flash-exp', 'gpt-4o'). */
+  model: string;
+  /** API key (resolved from env if not set). */
+  apiKey?: string;
+  /** OpenAI-compatible base URL (for openai provider). */
+  baseUrl?: string;
+}

package/src/mcp-server.ts

@@ -84,6 +84,33 @@ export async function startMcpServer(): Promise<void> {
           required: ['root'],
         },
       },
+      {
+        name: 'guard_review',
+        description:
+          'Review staged or diff changes against team-defined rules. Returns structured violations with severity, confidence, and fixability.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            root: {
+              type: 'string',
+              description: 'Absolute path to the repo root',
+            },
+            diff: {
+              type: 'string',
+              description: 'Unified diff content (if omitted, reviews staged files)',
+            },
+            diff_only: {
+              type: 'boolean',
+              description: 'Skip cross-file context for faster review (default: false)',
+            },
+            fix: {
+              type: 'boolean',
+              description: 'Apply auto-fixes for fixable violations (default: false)',
+            },
+          },
+          required: ['root'],
+        },
+      },
     ],
   }));
 
@@ -143,6 +170,28 @@ export async function startMcpServer(): Promise<void> {
       };
     }
 
+    if (toolName === 'guard_review') {
+      const { runGuard, formatGuardJson } = await import('./guard/index');
+      const root = String(args.root ?? '');
+      const diffContent =
+        typeof args.diff === 'string' && args.diff.length > 0
+          ? args.diff
+          : undefined;
+      const diffOnly = args.diff_only === true;
+      const fix = args.fix === true;
+
+      const { result } = await runGuard({
+        root,
+        diffOnly,
+        fix,
+        ...(diffContent ? { prMode: false } : {}),
+      });
+
+      return {
+        content: [{ type: 'text', text: formatGuardJson(result) }],
+      };
+    }
+
     throw new Error(`Unknown tool: ${toolName}`);
   });