skannr 0.2.0 → 0.2.2

package/src/cli.ts

@@ -483,6 +483,102 @@ cacheCommand
     console.log(`    Dir: ${cacheManager.getCacheDir()}\n`);
   });
 
+// ---------------------------------------------------------------------------
+// Subcommand: guard
+// ---------------------------------------------------------------------------
+const guardCommand = program
+  .command('guard')
+  .description('Review staged changes against team-defined rules')
+  .option('--root <path>', 'project root directory', process.cwd())
+  .option('--fix', 'apply auto-fixes for fixable violations')
+  .option('--dry-run', 'show what --fix would change without writing')
+  .option('--pr-mode', 'review full PR diff vs base branch')
+  .option('--diff-only', 'skip cross-file context (faster, cheaper)')
+  .option('--no-cache', 'ignore symbol cache')
+  .option('--json', 'output as JSON')
+  .action(async (cmdOpts: {
+    root: string;
+    fix?: boolean;
+    dryRun?: boolean;
+    prMode?: boolean;
+    diffOnly?: boolean;
+    noCache?: boolean;
+    json?: boolean;
+  }) => {
+    try {
+      const { runGuard, formatGuardText, formatGuardJson } = await import('./guard/index');
+      const { result, exitCode } = await runGuard({
+        root: cmdOpts.root,
+        fix: cmdOpts.fix,
+        dryRun: cmdOpts.dryRun,
+        prMode: cmdOpts.prMode,
+        diffOnly: cmdOpts.diffOnly,
+        noCache: cmdOpts.noCache,
+        json: cmdOpts.json,
+      });
+
+      const output = cmdOpts.json
+        ? formatGuardJson(result)
+        : formatGuardText(result);
+
+      process.stdout.write(output + (output.endsWith('\n') ? '' : '\n'));
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(
+        'Error running guard:',
+        error instanceof Error ? error.message : error,
+      );
+      process.exit(2);
+    }
+  });
+
+guardCommand
+  .command('install')
+  .description('Install git pre-commit hook')
+  .option('--root <path>', 'project root directory', process.cwd())
+  .action(async (cmdOpts: { root: string }) => {
+    const { installHook } = await import('./guard/index');
+    const { installed, message } = installHook(path.resolve(cmdOpts.root));
+    console.log(message);
+    process.exit(installed ? 0 : 1);
+  });
+
+guardCommand
+  .command('uninstall')
+  .description('Remove git pre-commit hook')
+  .option('--root <path>', 'project root directory', process.cwd())
+  .action(async (cmdOpts: { root: string }) => {
+    const { uninstallHook } = await import('./guard/index');
+    const { removed, message } = uninstallHook(path.resolve(cmdOpts.root));
+    console.log(message);
+    process.exit(removed ? 0 : 1);
+  });
+
+guardCommand
+  .command('config')
+  .description('Show loaded rules and provider config')
+  .option('--root <path>', 'project root directory', process.cwd())
+  .action(async (cmdOpts: { root: string }) => {
+    const { loadRules, loadGuardConfig } = await import('./guard/index');
+    const root = path.resolve(cmdOpts.root);
+    try {
+      const rules = loadRules(root);
+      const config = loadGuardConfig(root);
+      console.log('\n  Guard Config:');
+      console.log(`    Provider: ${config.provider}`);
+      console.log(`    Model: ${config.model}`);
+      console.log(`    API Key: ${config.apiKey ? '***' + config.apiKey.slice(-4) : 'not set'}`);
+      console.log(`\n  Rules (${rules.length}):`);
+      for (const r of rules) {
+        console.log(`    [${r.id}] ${r.severity} | fixable=${r.fixable} | ${r.description}`);
+      }
+      console.log('');
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : error);
+      process.exit(2);
+    }
+  });
+
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
@@ -499,6 +595,11 @@ Examples:
   skannr risk --diff feature.patch         Impact of a patch file
   skannr risk -n 3 --json                  3 hops, JSON for CI
 
+  skannr guard                             Review staged changes against rules
+  skannr guard --fix                       Auto-fix fixable violations
+  skannr guard --pr-mode --json            Review PR diff, JSON output
+  skannr guard install                     Install pre-commit hook
+
   skannr report                            Repo health summary
   skannr agent                             Interactive mode
   skannr cache stats                       Cache hit rate

package/src/guard/call-context.ts

@@ -0,0 +1,101 @@
+/**
+ * Pull caller/callee context from the existing dependency graph.
+ * Enriches SymbolDiffUnit[] with cross-file relationship information
+ * so the LLM can detect breakages beyond the changed file.
+ */
+
+import * as path from 'path';
+import { scanFiles, readFileContent } from '../scanner';
+import { analyzeDependencyGraph } from '../ranker-enhanced';
+import { getAdapter } from '../languages/registry';
+import { buildReverseGraph } from '../blast-radius';
+import { loadConfig } from '../config';
+import type { SymbolDiffUnit } from './types';
+
+/**
+ * Enrich symbol diff units with caller and callee context.
+ * Uses the project's dependency graph to find:
+ * - callers: files that import the changed file (reverse deps)
+ * - callees: files that the changed file imports (forward deps)
+ */
+export function enrichWithCallContext(
+  units: SymbolDiffUnit[],
+  root: string,
+): SymbolDiffUnit[] {
+  if (units.length === 0) return units;
+
+  // Scan project files and build dependency graph
+  const config = loadConfig(root);
+  const allFiles = scanFiles(root, {
+    extensions: config.extensions,
+    exclude: config.exclude,
+  });
+
+  const forwardGraph = analyzeDependencyGraph(allFiles, root);
+  const reverseGraph = buildReverseGraph(forwardGraph);
+
+  // Group units by file
+  const fileSet = new Set(units.map((u) => u.file));
+
+  for (const unit of units) {
+    const fileRel = unit.file;
+    const fileNoExt = fileRel.replace(/\.[^.]+$/, '');
+    const fileBase = path.basename(fileRel, path.extname(fileRel));
+
+    // Find callers (files that import this file)
+    const callers: string[] = [];
+    for (const [key, importers] of reverseGraph.entries()) {
+      const normalizedKey = key.split(path.sep).join('/');
+      if (
+        normalizedKey === fileRel ||
+        normalizedKey === fileNoExt ||
+        normalizedKey.endsWith('/' + fileBase)
+      ) {
+        for (const importer of importers) {
+          callers.push(importer);
+        }
+      }
+    }
+
+    // Find callees (files this file imports)
+    const callees: string[] = [];
+    const normalizedFileRel = fileRel.split(path.sep).join('/');
+    for (const [key, imports] of forwardGraph.entries()) {
+      const normalizedKey = key.split(path.sep).join('/');
+      if (normalizedKey === normalizedFileRel) {
+        callees.push(...imports);
+        break;
+      }
+    }
+
+    // Format as "file:symbol" where possible
+    unit.callers = [...new Set(callers)].slice(0, 10).map((c) => formatCallerRef(c, root));
+    unit.callees = [...new Set(callees)].slice(0, 10);
+  }
+
+  return units;
+}
+
+/**
+ * Format a caller file reference, attempting to identify which symbols
+ * in that file actually reference the changed file.
+ */
+function formatCallerRef(callerFile: string, root: string): string {
+  const absPath = path.join(root, callerFile);
+  const content = readFileContent(absPath);
+  if (!content) return callerFile;
+
+  const adapter = getAdapter(absPath);
+  const symbols = adapter.extractSymbols(content);
+
+  // Return the file with its top exported symbols for context
+  const topSymbols = symbols
+    .filter((s) => s.kind === 'function' || s.kind === 'class')
+    .slice(0, 3)
+    .map((s) => s.name);
+
+  if (topSymbols.length > 0) {
+    return `${callerFile}:${topSymbols.join(',')}`;
+  }
+  return callerFile;
+}

package/src/guard/fix-applier.ts

@@ -0,0 +1,172 @@
+/**
+ * Fix applier — applies suggested fixes ONLY for fixable:true violations
+ * from the current review run. Never expands scope beyond what was reviewed.
+ *
+ * Two-phase consent:
+ * 1. Default: show a dry-run diff of what would change
+ * 2. Only write when explicitly confirmed (--fix flag on same invocation)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { Violation } from './types';
+
+export interface FixResult {
+  file: string;
+  symbol: string;
+  rule_id: string;
+  applied: boolean;
+  diff: string;
+}
+
+/**
+ * Filter violations to only fixable ones with a suggested fix.
+ */
+export function getFixableViolations(violations: Violation[]): Violation[] {
+  return violations.filter((v) => v.fixable && v.suggested_fix);
+}
+
+/**
+ * Generate a dry-run preview of what fixes would be applied.
+ * Does NOT write to disk.
+ */
+export function previewFixes(violations: Violation[], root: string): FixResult[] {
+  const fixable = getFixableViolations(violations);
+  const results: FixResult[] = [];
+
+  for (const v of fixable) {
+    const absPath = path.join(root, v.file);
+    if (!fs.existsSync(absPath)) {
+      results.push({
+        file: v.file,
+        symbol: v.symbol,
+        rule_id: v.rule_id,
+        applied: false,
+        diff: `[file not found: ${v.file}]`,
+      });
+      continue;
+    }
+
+    const content = fs.readFileSync(absPath, 'utf-8');
+    const lines = content.split('\n');
+    const startIdx = Math.max(0, v.line_start - 1);
+    const endIdx = Math.min(lines.length, v.line_end);
+    const originalLines = lines.slice(startIdx, endIdx);
+
+    results.push({
+      file: v.file,
+      symbol: v.symbol,
+      rule_id: v.rule_id,
+      applied: false,
+      diff: [
+        `  ${v.file}:${v.line_start}-${v.line_end} (${v.rule_id})`,
+        `  - ${originalLines.join('\n  - ')}`,
+        `  + ${v.suggested_fix}`,
+      ].join('\n'),
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Apply fixes to disk. Only touches fixable:true violations with a suggested_fix.
+ * Returns a summary of what was applied.
+ *
+ * IMPORTANT: This only applies fixes from violations passed in — never does a
+ * fresh analysis pass. The caller is responsible for scoping.
+ */
+export function applyFixes(violations: Violation[], root: string): FixResult[] {
+  const fixable = getFixableViolations(violations);
+  const results: FixResult[] = [];
+
+  // Group by file to minimize reads/writes
+  const byFile = new Map<string, Violation[]>();
+  for (const v of fixable) {
+    const existing = byFile.get(v.file) ?? [];
+    existing.push(v);
+    byFile.set(v.file, existing);
+  }
+
+  for (const [file, fileViolations] of byFile.entries()) {
+    const absPath = path.join(root, file);
+    if (!fs.existsSync(absPath)) {
+      for (const v of fileViolations) {
+        results.push({
+          file: v.file,
+          symbol: v.symbol,
+          rule_id: v.rule_id,
+          applied: false,
+          diff: `[file not found: ${v.file}]`,
+        });
+      }
+      continue;
+    }
+
+    let content = fs.readFileSync(absPath, 'utf-8');
+    const lines = content.split('\n');
+
+    // Apply fixes in reverse line order to avoid offset drift
+    const sorted = [...fileViolations].sort((a, b) => b.line_start - a.line_start);
+
+    for (const v of sorted) {
+      if (!v.suggested_fix) continue;
+
+      const startIdx = Math.max(0, v.line_start - 1);
+      const endIdx = Math.min(lines.length, v.line_end);
+      const originalLines = lines.slice(startIdx, endIdx);
+
+      // Replace the affected lines with the suggested fix
+      lines.splice(startIdx, endIdx - startIdx, v.suggested_fix);
+
+      results.push({
+        file: v.file,
+        symbol: v.symbol,
+        rule_id: v.rule_id,
+        applied: true,
+        diff: [
+          `  ${v.file}:${v.line_start}-${v.line_end} (${v.rule_id})`,
+          `  - ${originalLines.join('\n  - ')}`,
+          `  + ${v.suggested_fix}`,
+        ].join('\n'),
+      });
+    }
+
+    // Write the modified content back
+    content = lines.join('\n');
+    fs.writeFileSync(absPath, content, 'utf-8');
+  }
+
+  return results;
+}
+
+/**
+ * Format fix results for terminal output.
+ */
+export function formatFixResults(results: FixResult[], dryRun: boolean): string {
+  if (results.length === 0) {
+    return '  No fixable violations to apply.';
+  }
+
+  const lines: string[] = [];
+  const prefix = dryRun ? '  [DRY RUN] Would apply:' : '  Applied fixes:';
+  lines.push(prefix);
+  lines.push('');
+
+  for (const r of results) {
+    lines.push(r.diff);
+    lines.push('');
+  }
+
+  if (!dryRun) {
+    const files = [...new Set(results.filter((r) => r.applied).map((r) => r.file))];
+    if (files.length > 0) {
+      lines.push('  Changes are unstaged. To discard:');
+      for (const f of files) {
+        lines.push(`    git checkout -- ${f}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/guard/hook-installer.ts

@@ -0,0 +1,96 @@
+/**
+ * Git hook installer for skannr guard.
+ * Appends to existing hooks using markers — never overwrites.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const HOOK_START_MARKER = '# >>> skannr-guard start >>>';
+const HOOK_END_MARKER = '# <<< skannr-guard end <<<';
+
+const HOOK_CONTENT = `
+${HOOK_START_MARKER}
+# Run skannr guard on staged files before committing.
+# Exit code 1 blocks the commit; exit code 2 is a tool error (non-blocking).
+npx skannr guard
+GUARD_EXIT=$?
+if [ $GUARD_EXIT -eq 1 ]; then
+  echo ""
+  echo "  Commit blocked by skannr guard. Fix violations or use --no-verify to skip."
+  echo ""
+  exit 1
+fi
+${HOOK_END_MARKER}
+`;
+
+/**
+ * Install the pre-commit hook (append-safe).
+ */
+export function installHook(root: string): { installed: boolean; message: string } {
+  const hooksDir = path.join(root, '.git', 'hooks');
+  if (!fs.existsSync(path.join(root, '.git'))) {
+    return { installed: false, message: 'Not a git repository (no .git directory found).' };
+  }
+
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  const hookPath = path.join(hooksDir, 'pre-commit');
+
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf-8');
+
+    // Already installed?
+    if (existing.includes(HOOK_START_MARKER)) {
+      return { installed: true, message: 'Hook already installed.' };
+    }
+
+    // Append to existing hook
+    const updated = existing.trimEnd() + '\n\n' + HOOK_CONTENT.trim() + '\n';
+    fs.writeFileSync(hookPath, updated, { mode: 0o755 });
+  } else {
+    // Create new hook
+    const content = '#!/bin/sh\n' + HOOK_CONTENT;
+    fs.writeFileSync(hookPath, content, { mode: 0o755 });
+  }
+
+  return { installed: true, message: `Hook installed at ${hookPath}` };
+}
+
+/**
+ * Uninstall the pre-commit hook (remove only our markers).
+ */
+export function uninstallHook(root: string): { removed: boolean; message: string } {
+  const hookPath = path.join(root, '.git', 'hooks', 'pre-commit');
+
+  if (!fs.existsSync(hookPath)) {
+    return { removed: false, message: 'No pre-commit hook found.' };
+  }
+
+  const content = fs.readFileSync(hookPath, 'utf-8');
+  if (!content.includes(HOOK_START_MARKER)) {
+    return { removed: false, message: 'Skannr guard hook not found in pre-commit.' };
+  }
+
+  // Remove everything between (and including) the markers
+  const startIdx = content.indexOf(HOOK_START_MARKER);
+  const endIdx = content.indexOf(HOOK_END_MARKER);
+  if (startIdx === -1 || endIdx === -1) {
+    return { removed: false, message: 'Malformed hook markers.' };
+  }
+
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + HOOK_END_MARKER.length).trimStart();
+  const updated = (before + '\n' + after).trim();
+
+  if (updated === '#!/bin/sh' || updated === '') {
+    // Hook is now empty — remove the file
+    fs.unlinkSync(hookPath);
+  } else {
+    fs.writeFileSync(hookPath, updated + '\n', { mode: 0o755 });
+  }
+
+  return { removed: true, message: 'Skannr guard hook removed.' };
+}

package/src/guard/index.ts

@@ -0,0 +1,134 @@
+/**
+ * Skannr Guard — entry point.
+ * Reviews staged changes against team-defined rules using symbol-level analysis.
+ */
+
+import * as path from 'path';
+import { runGuardReview } from './review-runner';
+import { previewFixes, applyFixes, formatFixResults } from './fix-applier';
+import { installHook, uninstallHook } from './hook-installer';
+import { loadRules, loadGuardConfig } from './rules-loader';
+import type { GuardResult, Violation } from './types';
+
+export interface GuardCliOptions {
+  root: string;
+  fix?: boolean;
+  dryRun?: boolean;
+  prMode?: boolean;
+  diffOnly?: boolean;
+  noCache?: boolean;
+  json?: boolean;
+}
+
+/**
+ * Run the guard review and return the result + exit code.
+ * Exit codes: 0 = pass, 1 = fail (violations), 2 = tool error.
+ */
+export async function runGuard(options: GuardCliOptions): Promise<{ result: GuardResult; exitCode: number }> {
+  const { root, fix = false, dryRun = false, prMode = false, diffOnly = false, noCache = false } = options;
+  const absoluteRoot = path.resolve(root);
+
+  // Get PR diff if in --pr-mode
+  let diffContent: string | undefined;
+  if (prMode) {
+    const { execSync } = await import('child_process');
+    try {
+      diffContent = execSync('git diff origin/main...HEAD', {
+        cwd: absoluteRoot,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    } catch {
+      diffContent = execSync('git diff main...HEAD', {
+        cwd: absoluteRoot,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    }
+  }
+
+  const result = await runGuardReview({
+    root: absoluteRoot,
+    diffContent,
+    diffOnly,
+    noCache,
+  });
+
+  // Handle --fix
+  if (fix && result.response.violations.length > 0) {
+    if (dryRun) {
+      const previews = previewFixes(result.response.violations, absoluteRoot);
+      const output = formatFixResults(previews, true);
+      process.stdout.write(output + '\n');
+    } else {
+      const applied = applyFixes(result.response.violations, absoluteRoot);
+      const output = formatFixResults(applied, false);
+      process.stdout.write(output + '\n');
+    }
+  }
+
+  const exitCode = result.response.status === 'fail' ? 1 : 0;
+  return { result, exitCode };
+}
+
+/**
+ * Format the guard result for terminal output.
+ */
+export function formatGuardText(result: GuardResult): string {
+  const lines: string[] = [];
+  const { response } = result;
+
+  lines.push('');
+  lines.push('  Skannr Guard');
+  lines.push('  ' + '─'.repeat(50));
+  lines.push('');
+  lines.push(`  Status: ${response.status.toUpperCase()}`);
+  lines.push(`  ${response.summary}`);
+  lines.push(`  Reviewed ${result.symbolsReviewed} symbol(s) against ${result.rulesUsed.length} rule(s) in ${result.durationMs}ms`);
+  lines.push('');
+
+  if (response.violations.length > 0) {
+    lines.push('  Violations:');
+    lines.push('');
+
+    for (const v of response.violations) {
+      const fixTag = v.fixable ? ' [FIXABLE]' : '';
+      const confTag = `(${Math.round(v.confidence * 100)}% confidence)`;
+      lines.push(`    ${v.severity.toUpperCase()} ${v.file}:${v.line_start} ${confTag}${fixTag}`);
+      lines.push(`      Rule: ${v.rule_id}`);
+      lines.push(`      Symbol: ${v.symbol}`);
+      lines.push(`      ${v.message}`);
+      if (v.suggested_fix) {
+        lines.push(`      Fix: ${v.suggested_fix}`);
+      }
+      lines.push('');
+    }
+
+    const fixableCount = response.violations.filter((v) => v.fixable).length;
+    if (fixableCount > 0) {
+      lines.push(`  ${fixableCount} violation(s) are auto-fixable. Run: skannr guard --fix`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the guard result as JSON.
+ */
+export function formatGuardJson(result: GuardResult): string {
+  return JSON.stringify({
+    status: result.response.status,
+    summary: result.response.summary,
+    violations: result.response.violations,
+    symbolsReviewed: result.symbolsReviewed,
+    rulesUsed: result.rulesUsed.length,
+    durationMs: result.durationMs,
+  }, null, 2);
+}
+
+// Re-export for CLI/MCP wiring
+export { installHook, uninstallHook } from './hook-installer';
+export { loadRules, loadGuardConfig } from './rules-loader';
+export type { GuardResult, Violation } from './types';