@vibecheckai/cli 3.7.0 → 3.8.0

package/bin/runners/lib/safelist/matcher.js

@@ -0,0 +1,696 @@
+/**
+ * vibecheck safelist - Matching Engine
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * Determines if findings should be suppressed based on safelist entries
+ * 
+ * Features:
+ * - Multiple matching strategies (ID, pattern, rule, file)
+ * - Command-scoped suppressions
+ * - Branch-aware matching
+ * - Match tracking and statistics
+ * - Dry-run preview support
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+
+"use strict";
+
+const path = require("path");
+const { SAFELIST_COMMANDS, LIMITS } = require("./schema");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// REGEX CACHE - Avoid recompiling patterns
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const regexCache = new Map();
+const MAX_CACHE_SIZE = 100;
+
+/**
+ * Get or create cached regex
+ */
+function getCachedRegex(pattern, flags = "i") {
+  const key = `${pattern}:${flags}`;
+  
+  if (regexCache.has(key)) {
+    return regexCache.get(key);
+  }
+  
+  try {
+    const regex = new RegExp(pattern, flags);
+    
+    // Evict oldest if cache is full
+    if (regexCache.size >= MAX_CACHE_SIZE) {
+      const firstKey = regexCache.keys().next().value;
+      regexCache.delete(firstKey);
+    }
+    
+    regexCache.set(key, regex);
+    return regex;
+  } catch (err) {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MATCHING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a finding matches a safelist entry
+ * @param {Object} finding - Finding to check
+ * @param {Object} entry - Safelist entry
+ * @param {Object} context - Context (filePath, command, branch, etc.)
+ * @returns {{ matches: boolean, reason: string|null, matchType: string|null, confidence: number }}
+ */
+function matchEntry(finding, entry, context = {}) {
+  const { filePath, command, projectRoot, branch, dryRun } = context;
+  
+  const noMatch = { matches: false, reason: null, matchType: null, confidence: 0 };
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // EXPIRY CHECK
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (entry.lifecycle?.expiresAt) {
+    const expiresAt = new Date(entry.lifecycle.expiresAt).getTime();
+    if (expiresAt < Date.now()) {
+      return { ...noMatch, reason: "Entry expired" };
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // COMMAND SCOPE CHECK
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (entry.scope?.commands && entry.scope.commands.length > 0) {
+    if (command && !entry.scope.commands.includes(command)) {
+      return { ...noMatch, reason: "Command not in scope" };
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BRANCH SCOPE CHECK
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (entry.scope?.type === "branch" && entry.scope?.branches) {
+    if (branch && !entry.scope.branches.some(b => matchBranch(b, branch))) {
+      return { ...noMatch, reason: "Branch not in scope" };
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // MATCH BY ENTRY TYPE
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  let result;
+  switch (entry.type) {
+    case "finding":
+      result = matchFindingEntry(finding, entry);
+      break;
+    case "pattern":
+      result = matchPatternEntry(finding, entry, { filePath, projectRoot });
+      break;
+    case "rule":
+      result = matchRuleEntry(finding, entry);
+      break;
+    case "file":
+      result = matchFileEntry(finding, entry, { filePath, projectRoot });
+      break;
+    default:
+      return { ...noMatch, reason: "Unknown entry type" };
+  }
+  
+  // Add match type and confidence
+  if (result.matches) {
+    result.matchType = entry.type;
+    result.confidence = calculateConfidence(finding, entry, result);
+  }
+  
+  return result;
+}
+
+/**
+ * Calculate match confidence (0-100)
+ * Higher = more specific match, less likely to be wrong
+ */
+function calculateConfidence(finding, entry, matchResult) {
+  let confidence = 50; // Base
+  
+  // Exact ID match = highest confidence
+  if (entry.type === "finding" && entry.target?.findingId === finding.id) {
+    confidence = 100;
+  }
+  
+  // Rule match = high confidence
+  if (entry.type === "rule") {
+    confidence = 90;
+  }
+  
+  // File + line match = high confidence
+  if (entry.type === "file" && entry.target?.lines) {
+    confidence = 85;
+  }
+  
+  // Pattern match = variable confidence
+  if (entry.type === "pattern") {
+    const pattern = entry.target?.pattern || "";
+    
+    // Longer patterns = more specific = higher confidence
+    if (pattern.length > 20) confidence += 15;
+    else if (pattern.length > 10) confidence += 5;
+    
+    // File-scoped patterns = higher confidence
+    if (entry.target?.file) confidence += 10;
+    
+    // Line-scoped patterns = highest confidence for patterns
+    if (entry.target?.lines) confidence += 15;
+  }
+  
+  return Math.min(100, Math.max(0, confidence));
+}
+
+/**
+ * Match branch name against pattern
+ */
+function matchBranch(pattern, branch) {
+  if (pattern === branch) return true;
+  if (pattern === "*") return true;
+  
+  // Support glob patterns
+  if (pattern.includes("*")) {
+    const regex = pattern
+      .replace(/\*/g, ".*")
+      .replace(/\?/g, ".");
+    return new RegExp(`^${regex}$`).test(branch);
+  }
+  
+  return false;
+}
+
+/**
+ * Match by specific finding ID
+ */
+function matchFindingEntry(finding, entry) {
+  if (!entry.target?.findingId) {
+    return { matches: false, reason: "No finding ID in entry" };
+  }
+  
+  if (finding.id === entry.target.findingId) {
+    return { matches: true, reason: entry.justification?.reason };
+  }
+  
+  return { matches: false, reason: null };
+}
+
+/**
+ * Match by regex pattern
+ */
+function matchPatternEntry(finding, entry, context) {
+  if (!entry.target?.pattern) {
+    return { matches: false, reason: "No pattern in entry" };
+  }
+  
+  // Use cached regex
+  const regex = getCachedRegex(entry.target.pattern, "i");
+  if (!regex) {
+    return { matches: false, reason: "Invalid regex pattern" };
+  }
+  
+  // Build list of targets to match against (ordered by specificity)
+  const targets = [];
+  
+  // Most specific - exact fields
+  if (finding.id) targets.push({ value: finding.id, field: "id" });
+  if (finding.ruleId) targets.push({ value: finding.ruleId, field: "ruleId" });
+  
+  // Medium specific - content fields
+  if (finding.message) targets.push({ value: finding.message, field: "message" });
+  if (finding.title) targets.push({ value: finding.title, field: "title" });
+  if (finding.description) targets.push({ value: finding.description, field: "description" });
+  
+  // Less specific - category/type
+  if (finding.category) targets.push({ value: finding.category, field: "category" });
+  if (finding.type) targets.push({ value: finding.type, field: "type" });
+  
+  // Context - file path
+  if (finding.file) targets.push({ value: finding.file, field: "file" });
+  
+  // Try to match
+  let matchedField = null;
+  const matched = targets.some(t => {
+    if (regex.test(t.value)) {
+      matchedField = t.field;
+      return true;
+    }
+    return false;
+  });
+  
+  if (!matched) {
+    return { matches: false, reason: null };
+  }
+  
+  // Check file scope if specified
+  if (entry.target.file) {
+    const { filePath, projectRoot } = context;
+    const findingFile = finding.file || filePath;
+    
+    if (!findingFile) {
+      return { matches: false, reason: "File scope but no file context" };
+    }
+    
+    const normalizedEntry = normalizePath(entry.target.file, projectRoot);
+    const normalizedFile = normalizePath(findingFile, projectRoot);
+    
+    // Support glob patterns
+    if (entry.target.file.includes("*")) {
+      if (!matchGlob(entry.target.file, normalizedFile)) {
+        return { matches: false, reason: "File does not match glob" };
+      }
+    } else {
+      // Check for exact match, suffix match, or contains
+      if (normalizedFile !== normalizedEntry && 
+          !normalizedFile.endsWith("/" + normalizedEntry) &&
+          !normalizedFile.includes(normalizedEntry)) {
+        return { matches: false, reason: "File does not match" };
+      }
+    }
+  }
+  
+  // Check line range if specified
+  if (entry.target.lines) {
+    const findingLine = finding.line || finding.startLine;
+    if (findingLine) {
+      const [start, end] = entry.target.lines;
+      if (findingLine < start || findingLine > end) {
+        return { matches: false, reason: "Line not in range" };
+      }
+    } else if (entry.target.lines[0] !== 1 || entry.target.lines[1] !== Infinity) {
+      // If we have line constraints but no line info in finding, don't match
+      // unless the range is effectively "all lines"
+      return { matches: false, reason: "Line info required but not available" };
+    }
+  }
+  
+  return { 
+    matches: true, 
+    reason: entry.justification?.reason,
+    matchedField,
+  };
+}
+
+/**
+ * Match by rule ID
+ */
+function matchRuleEntry(finding, entry) {
+  if (!entry.target?.ruleId) {
+    return { matches: false, reason: "No rule ID in entry" };
+  }
+  
+  const findingRuleId = finding.ruleId || finding.id?.split("_")[0] || finding.type;
+  
+  if (findingRuleId === entry.target.ruleId) {
+    return { matches: true, reason: entry.justification?.reason };
+  }
+  
+  return { matches: false, reason: null };
+}
+
+/**
+ * Match by file path
+ */
+function matchFileEntry(finding, entry, context) {
+  if (!entry.target?.file) {
+    return { matches: false, reason: "No file in entry" };
+  }
+  
+  const { filePath, projectRoot } = context;
+  const findingFile = finding.file || filePath;
+  
+  if (!findingFile) {
+    return { matches: false, reason: "No file context" };
+  }
+  
+  const normalizedEntry = normalizePath(entry.target.file, projectRoot);
+  const normalizedFile = normalizePath(findingFile, projectRoot);
+  
+  // Support glob patterns
+  if (entry.target.file.includes("*")) {
+    if (!matchGlob(entry.target.file, normalizedFile)) {
+      return { matches: false, reason: "File does not match glob" };
+    }
+  } else if (!normalizedFile.endsWith(normalizedEntry) && !normalizedFile.includes(normalizedEntry)) {
+    return { matches: false, reason: "File does not match" };
+  }
+  
+  // Check line range if specified
+  if (entry.target.lines && finding.line) {
+    const [start, end] = entry.target.lines;
+    if (finding.line < start || finding.line > end) {
+      return { matches: false, reason: "Line not in range" };
+    }
+  }
+  
+  return { matches: true, reason: entry.justification?.reason };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// BULK MATCHING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a finding is suppressed by any safelist entry
+ * @param {Object} finding - Finding to check
+ * @param {Object} safelist - Loaded safelist
+ * @param {Object} context - Context (filePath, command, etc.)
+ * @returns {{ suppressed: boolean, entry: Object|null, reason: string|null, matchType: string|null, matchedField: string|null, confidence: number }}
+ */
+function isSuppressed(finding, safelist, context = {}) {
+  const noSuppress = { 
+    suppressed: false, 
+    entry: null, 
+    reason: null, 
+    matchType: null,
+    matchedField: null,
+    confidence: 0,
+  };
+  
+  if (!safelist?.entries || safelist.entries.length === 0) {
+    return noSuppress;
+  }
+  
+  // Try each entry, track best match (highest confidence)
+  let bestMatch = null;
+  let bestConfidence = 0;
+  
+  for (const entry of safelist.entries) {
+    const result = matchEntry(finding, entry, context);
+    
+    if (result.matches) {
+      // For exact ID matches, return immediately (100% confidence)
+      if (result.confidence === 100) {
+        return {
+          suppressed: true,
+          entry,
+          reason: result.reason,
+          matchType: result.matchType,
+          matchedField: result.matchedField,
+          confidence: result.confidence,
+        };
+      }
+      
+      // Track best match
+      if (result.confidence > bestConfidence) {
+        bestMatch = { entry, result };
+        bestConfidence = result.confidence;
+      }
+    }
+  }
+  
+  // Return best match if found
+  if (bestMatch) {
+    return {
+      suppressed: true,
+      entry: bestMatch.entry,
+      reason: bestMatch.result.reason,
+      matchType: bestMatch.result.matchType,
+      matchedField: bestMatch.result.matchedField,
+      confidence: bestMatch.result.confidence,
+    };
+  }
+  
+  return noSuppress;
+}
+
+/**
+ * Filter findings, separating active from suppressed
+ * @param {Array} findings - Findings to filter
+ * @param {Object} safelist - Loaded safelist
+ * @param {Object} context - Context
+ * @returns {{ active: Array, suppressed: Array, stats: Object }}
+ */
+function filterFindings(findings, safelist, context = {}) {
+  const active = [];
+  const suppressed = [];
+  const stats = {
+    total: findings.length,
+    active: 0,
+    suppressed: 0,
+    byEntry: {},
+    byCategory: {},
+    byMatchType: {},
+    byConfidence: { high: 0, medium: 0, low: 0 },
+    matchedEntries: new Set(),
+  };
+  
+  for (const finding of findings) {
+    const result = isSuppressed(finding, safelist, {
+      ...context,
+      filePath: finding.file,
+    });
+    
+    if (result.suppressed) {
+      suppressed.push({
+        ...finding,
+        _suppression: {
+          entryId: result.entry?.id,
+          reason: result.reason,
+          category: result.entry?.justification?.category,
+          owner: result.entry?.owner?.name,
+          ownerTeam: result.entry?.owner?.team,
+          expiresAt: result.entry?.lifecycle?.expiresAt,
+          matchType: result.matchType,
+          matchedField: result.matchedField,
+          confidence: result.confidence,
+        },
+      });
+      
+      stats.suppressed++;
+      
+      // Track by entry
+      const entryId = result.entry?.id || "unknown";
+      stats.byEntry[entryId] = (stats.byEntry[entryId] || 0) + 1;
+      stats.matchedEntries.add(entryId);
+      
+      // Track by category
+      const category = result.entry?.justification?.category || "unknown";
+      stats.byCategory[category] = (stats.byCategory[category] || 0) + 1;
+      
+      // Track by match type
+      const matchType = result.matchType || "unknown";
+      stats.byMatchType[matchType] = (stats.byMatchType[matchType] || 0) + 1;
+      
+      // Track by confidence
+      const confidence = result.confidence || 0;
+      if (confidence >= 80) stats.byConfidence.high++;
+      else if (confidence >= 50) stats.byConfidence.medium++;
+      else stats.byConfidence.low++;
+    } else {
+      active.push(finding);
+      stats.active++;
+    }
+  }
+  
+  // Convert Set to Array for serialization
+  stats.matchedEntries = Array.from(stats.matchedEntries);
+  
+  return { active, suppressed, stats };
+}
+
+/**
+ * Preview what would be suppressed (dry-run mode)
+ * @param {Array} findings - Findings to check
+ * @param {Object} safelist - Loaded safelist
+ * @param {Object} context - Context
+ * @returns {{ wouldSuppress: Array, stats: Object }}
+ */
+function previewSuppression(findings, safelist, context = {}) {
+  const result = filterFindings(findings, safelist, { ...context, dryRun: true });
+  
+  return {
+    wouldSuppress: result.suppressed.map(f => ({
+      finding: {
+        id: f.id,
+        message: f.message,
+        file: f.file,
+        line: f.line,
+        category: f.category,
+      },
+      suppressedBy: {
+        entryId: f._suppression.entryId,
+        reason: f._suppression.reason,
+        category: f._suppression.category,
+        owner: f._suppression.owner,
+        matchType: f._suppression.matchType,
+        confidence: f._suppression.confidence,
+      },
+    })),
+    stats: result.stats,
+  };
+}
+
+/**
+ * Find which safelist entries are unused (match nothing)
+ * @param {Array} findings - All findings
+ * @param {Object} safelist - Loaded safelist
+ * @param {Object} context - Context
+ * @returns {Array} Entries that matched nothing
+ */
+function findUnusedEntries(findings, safelist, context = {}) {
+  const { stats } = filterFindings(findings, safelist, context);
+  const matchedIds = new Set(stats.matchedEntries);
+  
+  return safelist.entries.filter(entry => !matchedIds.has(entry.id));
+}
+
+/**
+ * Update match counts for entries that matched
+ * @param {Object} safelist - Safelist with _source annotations
+ * @param {Array} matchedEntryIds - Entry IDs that matched
+ * @param {Object} store - Store module for saving
+ * @param {string} projectRoot - Project root
+ */
+function updateMatchCounts(safelist, matchedEntryIds, store, projectRoot) {
+  const uniqueIds = [...new Set(matchedEntryIds)];
+  const now = new Date().toISOString();
+  
+  for (const entryId of uniqueIds) {
+    store.updateEntry(projectRoot, entryId, {
+      lifecycle: {
+        lastMatchedAt: now,
+        matchCount: (safelist.entries.find(e => e.id === entryId)?.lifecycle?.matchCount || 0) + 1,
+      },
+    });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Normalize file path for comparison
+ */
+function normalizePath(filePath, projectRoot) {
+  if (!filePath) return "";
+  
+  let normalized = filePath.replace(/\\/g, "/");
+  
+  // Remove project root prefix if present
+  if (projectRoot) {
+    const normalizedRoot = projectRoot.replace(/\\/g, "/");
+    if (normalized.startsWith(normalizedRoot)) {
+      normalized = normalized.substring(normalizedRoot.length);
+    }
+  }
+  
+  // Remove leading slash
+  if (normalized.startsWith("/")) {
+    normalized = normalized.substring(1);
+  }
+  
+  return normalized;
+}
+
+/**
+ * Simple glob matching
+ */
+function matchGlob(pattern, filePath) {
+  const regexPattern = pattern
+    .replace(/\./g, "\\.")
+    .replace(/\*\*/g, "{{GLOBSTAR}}")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, "[^/]")
+    .replace(/{{GLOBSTAR}}/g, ".*");
+  
+  return new RegExp(`^${regexPattern}$`, "i").test(filePath) ||
+         new RegExp(`${regexPattern}$`, "i").test(filePath);
+}
+
+/**
+ * Get entries that are expiring soon
+ * @param {Object} safelist - Loaded safelist
+ * @param {number} days - Days threshold
+ * @returns {Array} Entries expiring within threshold
+ */
+function getExpiringSoon(safelist, days = 7) {
+  const threshold = Date.now() + (days * 24 * 60 * 60 * 1000);
+  
+  return safelist.entries.filter(entry => {
+    if (!entry.lifecycle?.expiresAt) return false;
+    const expiresAt = new Date(entry.lifecycle.expiresAt).getTime();
+    return expiresAt > Date.now() && expiresAt <= threshold;
+  });
+}
+
+/**
+ * Get entries due for review
+ * @param {Object} safelist - Loaded safelist
+ * @returns {Array} Entries due for review
+ */
+function getDueForReview(safelist) {
+  const now = Date.now();
+  
+  return safelist.entries.filter(entry => {
+    if (!entry.lifecycle?.reviewAt) return false;
+    return new Date(entry.lifecycle.reviewAt).getTime() <= now;
+  });
+}
+
+/**
+ * Get expired entries
+ * @param {Object} safelist - Loaded safelist
+ * @returns {Array} Expired entries
+ */
+function getExpired(safelist) {
+  const now = Date.now();
+  
+  return safelist.entries.filter(entry => {
+    if (!entry.lifecycle?.expiresAt) return false;
+    return new Date(entry.lifecycle.expiresAt).getTime() < now;
+  });
+}
+
+/**
+ * Get unused entries (never matched)
+ * @param {Object} safelist - Loaded safelist
+ * @param {number} days - Days since creation
+ * @returns {Array} Entries that have never matched
+ */
+function getUnused(safelist, days = 30) {
+  const threshold = Date.now() - (days * 24 * 60 * 60 * 1000);
+  
+  return safelist.entries.filter(entry => {
+    if (entry.lifecycle?.matchCount > 0) return false;
+    const createdAt = new Date(entry.lifecycle?.createdAt).getTime();
+    return createdAt < threshold;
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Core matching
+  matchEntry,
+  isSuppressed,
+  filterFindings,
+  
+  // Preview & analysis
+  previewSuppression,
+  findUnusedEntries,
+  calculateConfidence,
+  
+  // Lifecycle management
+  updateMatchCounts,
+  getExpiringSoon,
+  getDueForReview,
+  getExpired,
+  getUnused,
+  
+  // Utilities
+  normalizePath,
+  matchGlob,
+  matchBranch,
+  getCachedRegex,
+};