skannr 0.2.0 → 0.2.2

package/src/guard/provider.ts

@@ -0,0 +1,209 @@
+/**
+ * LLM provider abstraction for guard reviews.
+ * Supports Gemini (existing dep) and OpenAI-compatible APIs.
+ * Enforces structured JSON output — never parses free text.
+ */
+
+import { ReviewResponseSchema } from './schema';
+import type { GuardConfig, GuardRule, ReviewResponse, SymbolDiffUnit } from './types';
+
+/** Maximum number of retry attempts when LLM returns invalid JSON. */
+const MAX_RETRIES = 1;
+
+/**
+ * Build the system prompt for the guard review.
+ */
+function buildSystemPrompt(rules: GuardRule[]): string {
+  const rulesText = rules
+    .map((r) => `- [${r.id}] (${r.severity}, fixable=${r.fixable}): ${r.description}`)
+    .join('\n');
+
+  return [
+    'You are a code review tool. Review the provided symbol-level diffs against the rules below.',
+    'For each violation found, output a structured JSON object matching the exact schema.',
+    '',
+    'Rules:',
+    rulesText,
+    '',
+    'Response format (strict JSON, no text before or after):',
+    '{',
+    '  "violations": [{ "rule_id": "...", "file": "...", "symbol": "...", "line_start": N, "line_end": N, "severity": "...", "confidence": 0.0-1.0, "fixable": bool, "message": "...", "suggested_fix": "..." }],',
+    '  "status": "pass" | "fail",',
+    '  "summary": "..."',
+    '}',
+    '',
+    'IMPORTANT:',
+    '- Only flag violations for rules listed above.',
+    '- The "fixable" field MUST match the rule definition — do not override it.',
+    '- "confidence" reflects how certain you are this is a real violation (0.0-1.0).',
+    '- "suggested_fix" is required only when fixable=true.',
+    '- If no violations found, return status "pass" with an empty violations array.',
+    '- Return ONLY the JSON object. No markdown, no explanation, no preamble.',
+  ].join('\n');
+}
+
+/**
+ * Build the user prompt with symbol diff units.
+ */
+function buildUserPrompt(units: SymbolDiffUnit[]): string {
+  const parts: string[] = ['Review these symbol-level changes:\n'];
+
+  for (const unit of units) {
+    parts.push(`--- ${unit.file} :: ${unit.symbol} (${unit.changeType}) ---`);
+    if (unit.oldSignature) parts.push(`Old: ${unit.oldSignature}`);
+    if (unit.newSignature) parts.push(`New: ${unit.newSignature}`);
+    if (unit.callers.length > 0) parts.push(`Callers: ${unit.callers.join(', ')}`);
+    if (unit.callees.length > 0) parts.push(`Callees: ${unit.callees.join(', ')}`);
+    parts.push('');
+    // Include a trimmed diff (first 100 lines to avoid token explosion)
+    const diffLines = unit.diffText.split('\n').slice(0, 100);
+    parts.push(diffLines.join('\n'));
+    parts.push('');
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Extract JSON from a response that might have text before/after.
+ * This handles the exact failure mode from gga: providers prepending
+ * acknowledgment text before the actual JSON response.
+ */
+function extractJson(text: string): string {
+  // Try to find a JSON object in the response
+  const firstBrace = text.indexOf('{');
+  const lastBrace = text.lastIndexOf('}');
+  if (firstBrace === -1 || lastBrace === -1 || lastBrace <= firstBrace) {
+    throw new Error('No JSON object found in response');
+  }
+  return text.slice(firstBrace, lastBrace + 1);
+}
+
+/**
+ * Call Gemini API with structured output enforcement.
+ */
+async function callGemini(
+  config: GuardConfig,
+  systemPrompt: string,
+  userPrompt: string,
+): Promise<string> {
+  const { GoogleGenerativeAI } = await import('@google/generative-ai');
+
+  if (!config.apiKey) {
+    throw new Error('No API key. Set GEMINI_API_KEY or SKANNR_GUARD_API_KEY.');
+  }
+
+  const genAI = new GoogleGenerativeAI(config.apiKey);
+  const model = genAI.getGenerativeModel({
+    model: config.model,
+    generationConfig: {
+      responseMimeType: 'application/json',
+    },
+  });
+
+  const result = await model.generateContent({
+    contents: [{ role: 'user', parts: [{ text: userPrompt }] }],
+    systemInstruction: { role: 'system', parts: [{ text: systemPrompt }] },
+  });
+
+  return result.response.text();
+}
+
+/**
+ * Call OpenAI-compatible API with structured output enforcement.
+ */
+async function callOpenAI(
+  config: GuardConfig,
+  systemPrompt: string,
+  userPrompt: string,
+): Promise<string> {
+  const baseUrl = config.baseUrl || 'https://api.openai.com/v1';
+  const url = `${baseUrl}/chat/completions`;
+
+  if (!config.apiKey) {
+    throw new Error('No API key. Set OPENAI_API_KEY or SKANNR_GUARD_API_KEY.');
+  }
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.apiKey}`,
+    },
+    body: JSON.stringify({
+      model: config.model,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+      ],
+      response_format: { type: 'json_object' },
+      temperature: 0.1,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`OpenAI API error: ${response.status} ${response.statusText}`);
+  }
+
+  const data = await response.json() as any;
+  return data.choices?.[0]?.message?.content ?? '';
+}
+
+/**
+ * Run the LLM review and return a validated response.
+ * Retries once on validation failure with a correction prompt.
+ */
+export async function runLlmReview(
+  config: GuardConfig,
+  rules: GuardRule[],
+  units: SymbolDiffUnit[],
+): Promise<ReviewResponse> {
+  const systemPrompt = buildSystemPrompt(rules);
+  const userPrompt = buildUserPrompt(units);
+
+  let lastError: string | null = null;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const prompt = attempt === 0
+      ? userPrompt
+      : `${userPrompt}\n\n[RETRY: Your last response didn't match the required schema. Error: ${lastError}. Return ONLY valid JSON matching the schema.]`;
+
+    let rawResponse: string;
+    try {
+      rawResponse = config.provider === 'openai'
+        ? await callOpenAI(config, systemPrompt, prompt)
+        : await callGemini(config, systemPrompt, prompt);
+    } catch (err) {
+      throw new Error(
+        `Provider call failed (${config.provider}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    // Extract and validate JSON
+    try {
+      const jsonStr = extractJson(rawResponse);
+      const parsed = JSON.parse(jsonStr);
+      const result = ReviewResponseSchema.safeParse(parsed);
+
+      if (result.success) {
+        // Enforce: fixable field must match the rule definition
+        for (const violation of result.data.violations) {
+          const rule = rules.find((r) => r.id === violation.rule_id);
+          if (rule) {
+            violation.fixable = rule.fixable;
+          }
+        }
+        return result.data;
+      }
+
+      lastError = result.error.issues
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ');
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+  }
+
+  // All retries exhausted
+  throw new Error(`LLM response failed schema validation after ${MAX_RETRIES + 1} attempts: ${lastError}`);
+}

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,131 @@
+/**
+ * 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',
+];
+
+/** Built-in default rules used when no .skannr/rules.json exists. */
+const DEFAULT_RULES: GuardRule[] = [
+  {
+    id: 'no-any-type',
+    description: 'Do not use the `any` type in TypeScript; use explicit types or `unknown`.',
+    severity: 'high',
+    fixable: true,
+    category: 'type-safety',
+  },
+  {
+    id: 'no-console-log',
+    description: 'Remove console.log statements before committing; use a proper logger in production code.',
+    severity: 'medium',
+    fixable: true,
+    category: 'code-quality',
+  },
+  {
+    id: 'error-handling',
+    description: 'Async functions that can throw should have error handling (try/catch or .catch()).',
+    severity: 'high',
+    fixable: false,
+    category: 'reliability',
+  },
+  {
+    id: 'no-hardcoded-secrets',
+    description: 'Do not hardcode API keys, passwords, tokens, or connection strings. Use environment variables.',
+    severity: 'critical',
+    fixable: false,
+    category: 'security',
+  },
+  {
+    id: 'function-complexity',
+    description: 'Functions should not exceed ~40 lines. Extract helper functions for complex logic.',
+    severity: 'medium',
+    fixable: false,
+    category: 'maintainability',
+  },
+  {
+    id: 'unused-imports',
+    description: 'Remove unused imports.',
+    severity: 'low',
+    fixable: true,
+    category: 'code-quality',
+  },
+];
+
+/** Load and validate rules from the project root. Falls back to defaults if no file exists. */
+export function loadRules(root: string): GuardRule[] {
+  const rulesPath = findRulesFile(root);
+  if (!rulesPath) {
+    return DEFAULT_RULES;
+  }
+
+  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(),
+});