vibecheck-ai 2.0.1 → 5.0.0

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

@@ -0,0 +1,948 @@
+/**
+ * vibecheck safelist - Schema & Validation
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * A SCALPEL, NOT A TRASH CAN
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Responsible suppression with:
+ * - Required justification
+ * - Owner accountability
+ * - Optional expiration
+ * - Audit trail
+ * - Scope control (repo-wide vs local)
+ * - Abuse prevention limits
+ * - Conflict detection
+ */
+
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SCHEMA VERSION - Increment on breaking changes
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const SCHEMA_VERSION = 2;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LIMITS - Prevent safelist abuse
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const LIMITS = {
+  MAX_ENTRIES_PER_FILE: 500,          // Max entries in a single safelist file
+  MAX_REASON_LENGTH: 500,             // Max characters in reason
+  MAX_PATTERN_LENGTH: 200,            // Max regex pattern length
+  MAX_FILE_PATH_LENGTH: 300,          // Max file path length
+  MIN_REASON_LENGTH: 10,              // Min characters in reason
+  MAX_LINE_RANGE: 1000,               // Max lines in a line range
+  MAX_OWNER_NAME_LENGTH: 100,         // Max owner name length
+  MAX_TICKET_URL_LENGTH: 500,         // Max ticket URL length
+  WARN_ENTRIES_THRESHOLD: 100,        // Warn when exceeding this many entries
+  STALE_DAYS_THRESHOLD: 90,           // Days without match before considered stale
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// DANGEROUS PATTERNS - Patterns that suppress too much
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const DANGEROUS_PATTERNS = [
+  /^\.\*$/,                           // Matches everything
+  /^\.\+$/,                           // Matches everything non-empty
+  /^\[^\\s\]\*$/i,                    // Matches any non-whitespace
+  /^\\w\*$/i,                         // Matches any word
+  /^\\S\*$/i,                         // Matches any non-whitespace
+  /^\.\{0,\}$/,                       // Matches everything (alternate)
+];
+
+/**
+ * Check if a pattern is dangerously broad
+ */
+function isDangerousPattern(pattern) {
+  if (!pattern || pattern.length < 3) return true; // Too short
+  
+  for (const dangerous of DANGEROUS_PATTERNS) {
+    if (dangerous.test(pattern)) return true;
+  }
+  
+  // Check for patterns that would match almost anything
+  try {
+    const regex = new RegExp(pattern, "i");
+    const testStrings = ["a", "test", "ERROR", "123", "foo_bar"];
+    const matchCount = testStrings.filter(s => regex.test(s)).length;
+    if (matchCount >= 4) return true; // Matches too many test strings
+  } catch {
+    // Invalid regex - will be caught by other validation
+  }
+  
+  return false;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENTRY SCHEMA
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Safelist entry schema
+ * @typedef {Object} SafelistEntry
+ * @property {string} id - Unique entry ID (e.g., "SL_abc123")
+ * @property {string} type - Entry type: "finding" | "pattern" | "rule" | "file"
+ * @property {Object} target - What to suppress
+ * @property {string} [target.findingId] - Specific finding ID
+ * @property {string} [target.pattern] - Regex pattern to match
+ * @property {string} [target.ruleId] - Rule ID to suppress
+ * @property {string} [target.file] - File path (glob supported)
+ * @property {number[]} [target.lines] - Line range [start, end]
+ * @property {Object} justification - Required justification
+ * @property {string} justification.reason - Why this is suppressed
+ * @property {string} justification.category - Category of justification
+ * @property {string} [justification.ticket] - Link to issue/ticket
+ * @property {Object} owner - Who is responsible
+ * @property {string} owner.name - Person/team name
+ * @property {string} [owner.email] - Contact email
+ * @property {string} [owner.team] - Team name
+ * @property {Object} scope - Where this applies
+ * @property {string} scope.type - "repo" | "local" | "branch"
+ * @property {string[]} [scope.commands] - Commands this applies to (default: all)
+ * @property {Object} lifecycle - Temporal properties
+ * @property {string} lifecycle.createdAt - ISO timestamp
+ * @property {string} lifecycle.createdBy - Who created (CLI user, CI, etc.)
+ * @property {string} [lifecycle.expiresAt] - ISO timestamp for expiry
+ * @property {string} [lifecycle.reviewAt] - ISO timestamp for review reminder
+ * @property {string} [lifecycle.lastMatchedAt] - Last time this matched a finding
+ * @property {number} lifecycle.matchCount - How many times this has matched
+ * @property {Object} [audit] - Audit trail
+ * @property {Array} [audit.history] - Change history
+ */
+
+/**
+ * Justification categories - must pick one
+ */
+const JUSTIFICATION_CATEGORIES = {
+  "false-positive": {
+    name: "False Positive",
+    description: "The finding is incorrect - code is actually fine",
+    requiresTicket: false,
+    maxExpiry: null, // Can be permanent
+  },
+  "accepted-risk": {
+    name: "Accepted Risk",
+    description: "Risk acknowledged and accepted by team",
+    requiresTicket: true, // Should have a ticket
+    maxExpiry: 365, // Max 1 year, then review
+  },
+  "test-fixture": {
+    name: "Test Fixture",
+    description: "Intentional test data/mock",
+    requiresTicket: false,
+    maxExpiry: null,
+  },
+  "legacy-code": {
+    name: "Legacy Code",
+    description: "Known issue in legacy code pending refactor",
+    requiresTicket: true,
+    maxExpiry: 180, // Max 6 months
+  },
+  "third-party": {
+    name: "Third-Party Code",
+    description: "Issue in vendored/third-party code we don't control",
+    requiresTicket: false,
+    maxExpiry: null,
+  },
+  "documentation": {
+    name: "Documentation/Example",
+    description: "Intentional example code in docs",
+    requiresTicket: false,
+    maxExpiry: null,
+  },
+  "temporary": {
+    name: "Temporary Suppression",
+    description: "Short-term suppression during development",
+    requiresTicket: false,
+    maxExpiry: 30, // Max 30 days
+  },
+};
+
+/**
+ * Scope types
+ */
+const SCOPE_TYPES = {
+  "repo": {
+    name: "Repository-Wide",
+    description: "Applies to entire repo, committed to version control",
+    file: ".vibecheck/safelist.json",
+    gitIgnore: false,
+  },
+  "local": {
+    name: "Local Only",
+    description: "Only applies to this machine, not committed",
+    file: ".vibecheck/safelist.local.json",
+    gitIgnore: true,
+  },
+  "branch": {
+    name: "Branch-Specific",
+    description: "Only applies to specific branches",
+    file: ".vibecheck/safelist.json",
+    gitIgnore: false,
+  },
+};
+
+/**
+ * Commands that respect the safelist
+ */
+const SAFELIST_COMMANDS = [
+  "audit",    // vibecheck audit
+  "scan",     // vibecheck scan (alias)
+  "ship",     // vibecheck ship
+  "polish",   // vibecheck polish
+  "prove",    // vibecheck prove
+  "reality",  // vibecheck reality
+  "guard",    // vibecheck guard
+];
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validation error
+ */
+class SafelistValidationError extends Error {
+  constructor(message, field, value) {
+    super(message);
+    this.name = "SafelistValidationError";
+    this.field = field;
+    this.value = value;
+  }
+}
+
+/**
+ * Validate a safelist entry
+ * @param {SafelistEntry} entry - Entry to validate
+ * @param {Object} opts - Validation options
+ * @param {boolean} opts.strict - Enable strict validation (default: true)
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+function validateEntry(entry, opts = {}) {
+  const { strict = true } = opts;
+  const errors = [];
+  const warnings = [];
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // ID VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.id || typeof entry.id !== "string") {
+    errors.push("Missing or invalid 'id' field");
+  } else {
+    if (!entry.id.startsWith("SL_")) {
+      errors.push("Entry ID must start with 'SL_'");
+    }
+    if (entry.id.length > 50) {
+      errors.push("Entry ID too long (max 50 characters)");
+    }
+    if (!/^SL_[a-zA-Z0-9_]+$/.test(entry.id)) {
+      errors.push("Entry ID contains invalid characters (only alphanumeric and underscore allowed)");
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // TYPE VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.type || !["finding", "pattern", "rule", "file"].includes(entry.type)) {
+    errors.push("Invalid 'type' - must be: finding, pattern, rule, or file");
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // TARGET VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.target || typeof entry.target !== "object") {
+    errors.push("Missing 'target' object");
+  } else {
+    const hasTarget = entry.target.findingId || entry.target.pattern || 
+                      entry.target.ruleId || entry.target.file;
+    if (!hasTarget) {
+      errors.push("Target must have at least one of: findingId, pattern, ruleId, file");
+    }
+    
+    // Validate finding ID format
+    if (entry.target.findingId) {
+      if (typeof entry.target.findingId !== "string") {
+        errors.push("Finding ID must be a string");
+      } else if (entry.target.findingId.length > 200) {
+        errors.push("Finding ID too long (max 200 characters)");
+      }
+    }
+    
+    // Validate pattern
+    if (entry.target.pattern) {
+      if (typeof entry.target.pattern !== "string") {
+        errors.push("Pattern must be a string");
+      } else {
+        if (entry.target.pattern.length > LIMITS.MAX_PATTERN_LENGTH) {
+          errors.push(`Pattern too long (max ${LIMITS.MAX_PATTERN_LENGTH} characters)`);
+        }
+        
+        // Validate regex syntax
+        try {
+          new RegExp(entry.target.pattern);
+        } catch (e) {
+          errors.push(`Invalid regex pattern: ${e.message}`);
+        }
+        
+        // Check for dangerous patterns
+        if (strict && isDangerousPattern(entry.target.pattern)) {
+          errors.push("Pattern is too broad and would match too many findings. Be more specific.");
+        }
+        
+        // Check for common regex mistakes
+        if (entry.target.pattern.includes("\\\\") && !entry.target.pattern.includes("\\\\\\\\")) {
+          warnings.push("Pattern contains double backslash - did you mean to escape a backslash?");
+        }
+      }
+    }
+    
+    // Validate rule ID
+    if (entry.target.ruleId) {
+      if (typeof entry.target.ruleId !== "string") {
+        errors.push("Rule ID must be a string");
+      } else if (!/^[A-Z][A-Z0-9_]*$/i.test(entry.target.ruleId)) {
+        warnings.push("Rule ID should be uppercase with underscores (e.g., MOCK_DATA, HARDCODED_SECRET)");
+      }
+    }
+    
+    // Validate file path
+    if (entry.target.file) {
+      if (typeof entry.target.file !== "string") {
+        errors.push("File path must be a string");
+      } else {
+        if (entry.target.file.length > LIMITS.MAX_FILE_PATH_LENGTH) {
+          errors.push(`File path too long (max ${LIMITS.MAX_FILE_PATH_LENGTH} characters)`);
+        }
+        
+        // Check for suspicious file patterns
+        if (entry.target.file === "*" || entry.target.file === "**" || entry.target.file === "**/*") {
+          errors.push("File pattern is too broad - would match all files");
+        }
+        
+        // Normalize path separators warning
+        if (entry.target.file.includes("\\")) {
+          warnings.push("File path contains backslashes - use forward slashes for cross-platform compatibility");
+        }
+        
+        // Check for absolute paths
+        if (/^[A-Za-z]:/.test(entry.target.file) || entry.target.file.startsWith("/")) {
+          warnings.push("File path appears to be absolute - consider using relative paths");
+        }
+      }
+    }
+    
+    // Validate line range
+    if (entry.target.lines) {
+      if (!Array.isArray(entry.target.lines) || entry.target.lines.length !== 2) {
+        errors.push("Lines must be an array of [start, end]");
+      } else {
+        const [start, end] = entry.target.lines;
+        
+        if (!Number.isInteger(start) || !Number.isInteger(end)) {
+          errors.push("Line numbers must be integers");
+        } else {
+          if (start < 1) {
+            errors.push("Line numbers must be >= 1");
+          }
+          if (start > end) {
+            errors.push("Line range start must be <= end");
+          }
+          if (end - start > LIMITS.MAX_LINE_RANGE) {
+            errors.push(`Line range too large (max ${LIMITS.MAX_LINE_RANGE} lines)`);
+          }
+          if (end > 100000) {
+            warnings.push("Line range end is very large - are you sure this is correct?");
+          }
+        }
+      }
+      
+      // Lines require file
+      if (!entry.target.file) {
+        errors.push("Line range requires a file path");
+      }
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // JUSTIFICATION VALIDATION (REQUIRED - this is a scalpel!)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.justification || typeof entry.justification !== "object") {
+    errors.push("Missing 'justification' object - reason is REQUIRED");
+  } else {
+    // Reason validation
+    if (!entry.justification.reason) {
+      errors.push("Justification reason is REQUIRED");
+    } else if (typeof entry.justification.reason !== "string") {
+      errors.push("Justification reason must be a string");
+    } else {
+      if (entry.justification.reason.length < LIMITS.MIN_REASON_LENGTH) {
+        errors.push(`Justification reason must be at least ${LIMITS.MIN_REASON_LENGTH} characters`);
+      }
+      if (entry.justification.reason.length > LIMITS.MAX_REASON_LENGTH) {
+        errors.push(`Justification reason too long (max ${LIMITS.MAX_REASON_LENGTH} characters)`);
+      }
+      
+      // Check for low-effort reasons
+      const lowEffortReasons = [
+        /^false positive$/i,
+        /^ignore$/i,
+        /^suppress$/i,
+        /^skip$/i,
+        /^not an issue$/i,
+        /^test$/i,
+        /^asdf/i,
+        /^xxx/i,
+        /^todo/i,
+      ];
+      if (strict && lowEffortReasons.some(r => r.test(entry.justification.reason.trim()))) {
+        errors.push("Justification reason is too vague. Explain WHY this should be suppressed.");
+      }
+    }
+    
+    // Category validation
+    if (!entry.justification.category) {
+      errors.push("Justification category is REQUIRED");
+    } else if (!JUSTIFICATION_CATEGORIES[entry.justification.category]) {
+      errors.push(`Invalid justification category. Must be one of: ${Object.keys(JUSTIFICATION_CATEGORIES).join(", ")}`);
+    } else {
+      const category = JUSTIFICATION_CATEGORIES[entry.justification.category];
+      if (category.requiresTicket && !entry.justification.ticket) {
+        errors.push(`Category '${entry.justification.category}' requires a ticket/issue link`);
+      }
+    }
+    
+    // Ticket validation
+    if (entry.justification.ticket) {
+      if (typeof entry.justification.ticket !== "string") {
+        errors.push("Ticket must be a string");
+      } else {
+        if (entry.justification.ticket.length > LIMITS.MAX_TICKET_URL_LENGTH) {
+          errors.push(`Ticket URL too long (max ${LIMITS.MAX_TICKET_URL_LENGTH} characters)`);
+        }
+        
+        // Validate URL format
+        if (!isValidUrl(entry.justification.ticket)) {
+          warnings.push("Ticket doesn't appear to be a valid URL");
+        }
+      }
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // OWNER VALIDATION (REQUIRED - accountability)
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.owner || typeof entry.owner !== "object") {
+    errors.push("Missing 'owner' object - accountability is REQUIRED");
+  } else {
+    if (!entry.owner.name) {
+      errors.push("Owner name is REQUIRED");
+    } else if (typeof entry.owner.name !== "string") {
+      errors.push("Owner name must be a string");
+    } else {
+      if (entry.owner.name.length < 2) {
+        errors.push("Owner name must be at least 2 characters");
+      }
+      if (entry.owner.name.length > LIMITS.MAX_OWNER_NAME_LENGTH) {
+        errors.push(`Owner name too long (max ${LIMITS.MAX_OWNER_NAME_LENGTH} characters)`);
+      }
+      
+      // Check for placeholder names
+      const placeholderNames = ["test", "user", "admin", "me", "todo", "asdf", "xxx"];
+      if (strict && placeholderNames.includes(entry.owner.name.toLowerCase())) {
+        warnings.push("Owner name appears to be a placeholder - use a real name or team");
+      }
+    }
+    
+    // Email validation
+    if (entry.owner.email) {
+      if (typeof entry.owner.email !== "string") {
+        errors.push("Owner email must be a string");
+      } else if (!isValidEmail(entry.owner.email)) {
+        warnings.push("Owner email doesn't appear to be valid");
+      }
+    }
+    
+    // Team validation
+    if (entry.owner.team) {
+      if (typeof entry.owner.team !== "string") {
+        errors.push("Owner team must be a string");
+      } else if (entry.owner.team.length > 100) {
+        errors.push("Owner team name too long (max 100 characters)");
+      }
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SCOPE VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.scope || typeof entry.scope !== "object") {
+    errors.push("Missing 'scope' object");
+  } else {
+    if (!entry.scope.type || !SCOPE_TYPES[entry.scope.type]) {
+      errors.push(`Invalid scope type. Must be one of: ${Object.keys(SCOPE_TYPES).join(", ")}`);
+    }
+    
+    // Validate commands if specified
+    if (entry.scope.commands) {
+      if (!Array.isArray(entry.scope.commands)) {
+        errors.push("Scope commands must be an array");
+      } else {
+        const invalidCommands = entry.scope.commands.filter(c => !SAFELIST_COMMANDS.includes(c));
+        if (invalidCommands.length > 0) {
+          errors.push(`Invalid commands in scope: ${invalidCommands.join(", ")}`);
+        }
+        if (entry.scope.commands.length === 0) {
+          warnings.push("Empty commands array - entry won't apply to any commands");
+        }
+      }
+    }
+    
+    // Validate branch if specified
+    if (entry.scope.type === "branch" && !entry.scope.branches) {
+      warnings.push("Branch scope type but no branches specified");
+    }
+    if (entry.scope.branches) {
+      if (!Array.isArray(entry.scope.branches)) {
+        errors.push("Scope branches must be an array");
+      } else if (entry.scope.branches.length === 0) {
+        warnings.push("Empty branches array");
+      }
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LIFECYCLE VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════
+  
+  if (!entry.lifecycle || typeof entry.lifecycle !== "object") {
+    errors.push("Missing 'lifecycle' object");
+  } else {
+    // Created timestamp
+    if (!entry.lifecycle.createdAt) {
+      errors.push("Missing lifecycle.createdAt timestamp");
+    } else if (!isValidISODate(entry.lifecycle.createdAt)) {
+      errors.push("Invalid lifecycle.createdAt timestamp (must be ISO 8601)");
+    }
+    
+    // Expiry validation
+    if (entry.lifecycle.expiresAt) {
+      if (!isValidISODate(entry.lifecycle.expiresAt)) {
+        errors.push("Invalid lifecycle.expiresAt timestamp (must be ISO 8601)");
+      } else if (entry.lifecycle.createdAt) {
+        const expiresAt = new Date(entry.lifecycle.expiresAt);
+        const createdAt = new Date(entry.lifecycle.createdAt);
+        
+        if (expiresAt <= createdAt) {
+          errors.push("Expiry date must be after creation date");
+        }
+      }
+    }
+    
+    // Check expiry constraints based on category
+    if (entry.justification?.category) {
+      const category = JUSTIFICATION_CATEGORIES[entry.justification.category];
+      if (category?.maxExpiry) {
+        if (!entry.lifecycle.expiresAt) {
+          errors.push(`Category '${entry.justification.category}' requires an expiration date (max ${category.maxExpiry} days)`);
+        } else if (entry.lifecycle.createdAt) {
+          const expiresAt = new Date(entry.lifecycle.expiresAt);
+          const createdAt = new Date(entry.lifecycle.createdAt);
+          const daysDiff = (expiresAt - createdAt) / (1000 * 60 * 60 * 24);
+          if (daysDiff > category.maxExpiry) {
+            errors.push(`Category '${entry.justification.category}' max expiry is ${category.maxExpiry} days, got ${Math.round(daysDiff)} days`);
+          }
+        }
+      }
+    }
+    
+    // Review date validation
+    if (entry.lifecycle.reviewAt) {
+      if (!isValidISODate(entry.lifecycle.reviewAt)) {
+        errors.push("Invalid lifecycle.reviewAt timestamp (must be ISO 8601)");
+      }
+    }
+    
+    // Match count validation
+    if (entry.lifecycle.matchCount !== undefined) {
+      if (!Number.isInteger(entry.lifecycle.matchCount) || entry.lifecycle.matchCount < 0) {
+        errors.push("Match count must be a non-negative integer");
+      }
+    }
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VALIDATION HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if string is a valid ISO 8601 date
+ */
+function isValidISODate(str) {
+  if (typeof str !== "string") return false;
+  const date = new Date(str);
+  return !isNaN(date.getTime()) && str.includes("T");
+}
+
+/**
+ * Check if string is a valid email
+ */
+function isValidEmail(str) {
+  if (typeof str !== "string") return false;
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(str);
+}
+
+/**
+ * Check if string is a valid URL
+ */
+function isValidUrl(str) {
+  if (typeof str !== "string") return false;
+  try {
+    new URL(str);
+    return true;
+  } catch {
+    // Allow ticket IDs like JIRA-123
+    return /^[A-Z]+-\d+$/i.test(str);
+  }
+}
+
+/**
+ * Validate entire safelist file
+ * @param {Object} safelist - Safelist object
+ * @param {Object} opts - Validation options
+ * @returns {{ valid: boolean, errors: string[], warnings: string[], stats: Object }}
+ */
+function validateSafelist(safelist, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const stats = {
+    total: 0,
+    valid: 0,
+    invalid: 0,
+    expired: 0,
+    expiringSoon: 0,
+    dueForReview: 0,
+    stale: 0,
+    conflicts: [],
+  };
+  
+  if (!safelist || typeof safelist !== "object") {
+    errors.push("Invalid safelist format");
+    return { valid: false, errors, warnings, stats };
+  }
+  
+  // Version check
+  if (safelist.version !== SCHEMA_VERSION) {
+    if (!safelist.version) {
+      errors.push("Missing schema version");
+    } else if (safelist.version < SCHEMA_VERSION) {
+      warnings.push(`Safelist version ${safelist.version} is outdated (current: ${SCHEMA_VERSION}). Run 'vibecheck safelist migrate'.`);
+    } else {
+      errors.push(`Safelist version ${safelist.version} is newer than supported (${SCHEMA_VERSION}). Update vibecheck CLI.`);
+    }
+  }
+  
+  if (!Array.isArray(safelist.entries)) {
+    errors.push("Safelist must have 'entries' array");
+    return { valid: false, errors, warnings, stats };
+  }
+  
+  stats.total = safelist.entries.length;
+  
+  // Check entry count limits
+  if (safelist.entries.length > LIMITS.MAX_ENTRIES_PER_FILE) {
+    errors.push(`Too many entries (${safelist.entries.length}). Max: ${LIMITS.MAX_ENTRIES_PER_FILE}. Consider cleaning up expired/unused entries.`);
+  } else if (safelist.entries.length > LIMITS.WARN_ENTRIES_THRESHOLD) {
+    warnings.push(`High number of entries (${safelist.entries.length}). Consider reviewing and cleaning up.`);
+  }
+  
+  const now = Date.now();
+  const sevenDays = 7 * 24 * 60 * 60 * 1000;
+  const staleDays = LIMITS.STALE_DAYS_THRESHOLD * 24 * 60 * 60 * 1000;
+  
+  // Validate each entry
+  const ids = new Set();
+  const patternMap = new Map(); // For conflict detection
+  const fileMap = new Map();    // For conflict detection
+  
+  for (let i = 0; i < safelist.entries.length; i++) {
+    const entry = safelist.entries[i];
+    const validation = validateEntry(entry, opts);
+    
+    if (!validation.valid) {
+      stats.invalid++;
+      errors.push(`Entry ${i} (${entry.id || "no-id"}): ${validation.errors.join("; ")}`);
+    } else {
+      stats.valid++;
+    }
+    
+    // Add entry warnings
+    if (validation.warnings) {
+      warnings.push(...validation.warnings.map(w => `Entry ${entry.id}: ${w}`));
+    }
+    
+    // Check for duplicate IDs
+    if (entry.id) {
+      if (ids.has(entry.id)) {
+        errors.push(`Duplicate entry ID: ${entry.id}`);
+      }
+      ids.add(entry.id);
+    }
+    
+    // Check for expired entries
+    if (entry.lifecycle?.expiresAt) {
+      const expiresAt = new Date(entry.lifecycle.expiresAt).getTime();
+      if (expiresAt < now) {
+        stats.expired++;
+        warnings.push(`Entry ${entry.id} has expired (${new Date(expiresAt).toLocaleDateString()})`);
+      } else if (expiresAt < now + sevenDays) {
+        stats.expiringSoon++;
+      }
+    }
+    
+    // Check for entries due for review
+    if (entry.lifecycle?.reviewAt) {
+      const reviewAt = new Date(entry.lifecycle.reviewAt).getTime();
+      if (reviewAt < now) {
+        stats.dueForReview++;
+        warnings.push(`Entry ${entry.id} is due for review`);
+      }
+    }
+    
+    // Check for stale entries (never matched after creation period)
+    if (entry.lifecycle?.createdAt) {
+      const createdAt = new Date(entry.lifecycle.createdAt).getTime();
+      const matchCount = entry.lifecycle?.matchCount || 0;
+      if (createdAt < now - staleDays && matchCount === 0) {
+        stats.stale++;
+        warnings.push(`Entry ${entry.id} has never matched any findings (${LIMITS.STALE_DAYS_THRESHOLD}+ days old)`);
+      }
+    }
+    
+    // Conflict detection - overlapping patterns
+    if (entry.target?.pattern) {
+      for (const [existingId, existingPattern] of patternMap) {
+        if (patternsOverlap(entry.target.pattern, existingPattern)) {
+          stats.conflicts.push({ entry1: existingId, entry2: entry.id, type: "pattern" });
+          warnings.push(`Potential overlap: ${existingId} and ${entry.id} have similar patterns`);
+        }
+      }
+      patternMap.set(entry.id, entry.target.pattern);
+    }
+    
+    // Conflict detection - same file
+    if (entry.target?.file) {
+      for (const [existingId, existingFile] of fileMap) {
+        if (filesOverlap(entry.target.file, existingFile)) {
+          // Only warn if they don't have different line ranges
+          const existingEntry = safelist.entries.find(e => e.id === existingId);
+          if (!entry.target.lines || !existingEntry?.target?.lines) {
+            stats.conflicts.push({ entry1: existingId, entry2: entry.id, type: "file" });
+            warnings.push(`Potential overlap: ${existingId} and ${entry.id} target same file`);
+          }
+        }
+      }
+      fileMap.set(entry.id, entry.target.file);
+    }
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    stats,
+  };
+}
+
+/**
+ * Check if two patterns might overlap
+ */
+function patternsOverlap(pattern1, pattern2) {
+  if (pattern1 === pattern2) return true;
+  
+  // Check if one contains the other
+  if (pattern1.includes(pattern2) || pattern2.includes(pattern1)) return true;
+  
+  // Try to detect regex subset relationships
+  try {
+    const testStrings = ["test", "error", "mock_data", "console.log", "TODO", "FIXME"];
+    const regex1 = new RegExp(pattern1, "i");
+    const regex2 = new RegExp(pattern2, "i");
+    
+    const matches1 = testStrings.filter(s => regex1.test(s));
+    const matches2 = testStrings.filter(s => regex2.test(s));
+    
+    // Check for overlap in matches
+    const overlap = matches1.filter(m => matches2.includes(m));
+    return overlap.length > 0 && (overlap.length === matches1.length || overlap.length === matches2.length);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if two file patterns might overlap
+ */
+function filesOverlap(file1, file2) {
+  if (file1 === file2) return true;
+  
+  // Normalize paths
+  const norm1 = file1.replace(/\\/g, "/");
+  const norm2 = file2.replace(/\\/g, "/");
+  
+  // Check if one is a prefix of the other
+  if (norm1.startsWith(norm2) || norm2.startsWith(norm1)) return true;
+  
+  // Check glob overlap
+  if (file1.includes("*") || file2.includes("*")) {
+    // Both are globs - check if they're the same base pattern
+    const base1 = norm1.replace(/\*+/g, "*");
+    const base2 = norm2.replace(/\*+/g, "*");
+    if (base1 === base2) return true;
+  }
+  
+  return false;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FACTORY FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a new safelist entry ID
+ */
+function generateEntryId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `SL_${timestamp}_${random}`;
+}
+
+/**
+ * Create a new safelist entry with defaults
+ * @param {Object} opts - Entry options
+ * @returns {SafelistEntry}
+ */
+function createEntry(opts) {
+  const {
+    type = "finding",
+    findingId,
+    pattern,
+    ruleId,
+    file,
+    lines,
+    reason,
+    category = "false-positive",
+    ticket,
+    ownerName,
+    ownerEmail,
+    ownerTeam,
+    scopeType = "repo",
+    commands,
+    expiresIn, // Days from now
+    reviewIn,  // Days from now
+  } = opts;
+  
+  const now = new Date().toISOString();
+  
+  const entry = {
+    id: generateEntryId(),
+    type,
+    target: {},
+    justification: {
+      reason,
+      category,
+    },
+    owner: {
+      name: ownerName,
+    },
+    scope: {
+      type: scopeType,
+    },
+    lifecycle: {
+      createdAt: now,
+      createdBy: process.env.USER || process.env.USERNAME || "cli",
+      matchCount: 0,
+    },
+  };
+  
+  // Target
+  if (findingId) entry.target.findingId = findingId;
+  if (pattern) entry.target.pattern = pattern;
+  if (ruleId) entry.target.ruleId = ruleId;
+  if (file) entry.target.file = file;
+  if (lines) entry.target.lines = lines;
+  
+  // Justification
+  if (ticket) entry.justification.ticket = ticket;
+  
+  // Owner
+  if (ownerEmail) entry.owner.email = ownerEmail;
+  if (ownerTeam) entry.owner.team = ownerTeam;
+  
+  // Scope
+  if (commands) entry.scope.commands = commands;
+  
+  // Lifecycle
+  if (expiresIn) {
+    entry.lifecycle.expiresAt = new Date(Date.now() + expiresIn * 24 * 60 * 60 * 1000).toISOString();
+  }
+  if (reviewIn) {
+    entry.lifecycle.reviewAt = new Date(Date.now() + reviewIn * 24 * 60 * 60 * 1000).toISOString();
+  }
+  
+  return entry;
+}
+
+/**
+ * Create empty safelist
+ */
+function createEmptySafelist() {
+  return {
+    version: SCHEMA_VERSION,
+    metadata: {
+      createdAt: new Date().toISOString(),
+      description: "vibecheck safelist - Responsible finding suppression",
+    },
+    entries: [],
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  SCHEMA_VERSION,
+  LIMITS,
+  JUSTIFICATION_CATEGORIES,
+  SCOPE_TYPES,
+  SAFELIST_COMMANDS,
+  DANGEROUS_PATTERNS,
+  SafelistValidationError,
+  isDangerousPattern,
+  isValidISODate,
+  isValidEmail,
+  isValidUrl,
+  validateEntry,
+  validateSafelist,
+  patternsOverlap,
+  filesOverlap,
+  generateEntryId,
+  createEntry,
+  createEmptySafelist,
+};