@vibecheckai/cli 3.0.4 → 3.0.7

package/bin/runners/lib/findings-schema.js

@@ -0,0 +1,281 @@
+/**
+ * Findings Schema v2
+ * 
+ * Per spec section 7.1, findings must include:
+ * - fingerprint: stable hash for dedupe across runs
+ * - scope: client|server|runtime|contracts
+ * - repro: minimal reproduction steps (for runtime findings)
+ * - related: linked finding IDs
+ * 
+ * This module provides helpers to create and validate v2 findings.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+
+/**
+ * Generate a stable fingerprint for a finding
+ * Used for dedupe across runs - same issue = same fingerprint
+ */
+function generateFingerprint(category, ...identifiers) {
+  const data = [category, ...identifiers.filter(Boolean)].join("|");
+  return crypto.createHash("sha256").update(data).digest("hex").slice(0, 12);
+}
+
+/**
+ * Infer scope from finding category and evidence
+ */
+function inferScope(category, evidence = []) {
+  const scopeMap = {
+    // Client-side findings
+    'DeadUI': 'runtime',
+    'FakeSuccess': 'client',
+    
+    // Server-side findings
+    'MissingRoute': 'server',
+    'GhostAuth': 'server',
+    'StripeWebhook': 'server',
+    'PaidSurface': 'server',
+    'OwnerModeBypass': 'server',
+    
+    // Contract findings
+    'ContractDrift': 'contracts',
+    'EnvContract': 'contracts',
+    
+    // Runtime findings
+    'AuthCoverage': 'runtime',
+    'RouteCoverage': 'runtime',
+  };
+
+  return scopeMap[category] || 'server';
+}
+
+/**
+ * Create a v2-compliant finding
+ */
+function createFinding({
+  id,
+  category,
+  type,
+  severity,
+  title,
+  message,
+  why,
+  confidence = 'med',
+  evidence = [],
+  fixHints = [],
+  repro = null,
+  related = [],
+  scope = null,
+  source = null,
+}) {
+  // Generate stable fingerprint
+  const fingerprint = generateFingerprint(
+    category,
+    type || title,
+    evidence[0]?.file,
+    evidence[0]?.lines
+  );
+
+  // Infer scope if not provided
+  const resolvedScope = scope || inferScope(category, evidence);
+
+  return {
+    // Core fields
+    id: id || `F_${category.toUpperCase()}_${fingerprint}`,
+    category,
+    type: type || category.toLowerCase(),
+    severity,
+    title,
+    message: message || title,
+    why,
+    confidence,
+    
+    // Evidence
+    evidence,
+    fixHints,
+    
+    // v2 fields (spec 7.1)
+    fingerprint,
+    scope: resolvedScope,
+    repro: repro || null,
+    related: related || [],
+    
+    // Metadata
+    source: source || 'static',
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Create a runtime finding with reproduction steps
+ */
+function createRuntimeFinding({
+  category,
+  type,
+  severity,
+  title,
+  why,
+  url,
+  action,
+  expected,
+  actual,
+  screenshot = null,
+  trace = null,
+  evidence = [],
+  related = [],
+}) {
+  const repro = {
+    url,
+    steps: [
+      `Navigate to ${url}`,
+      action ? `Action: ${action}` : null,
+      `Expected: ${expected}`,
+      `Actual: ${actual}`,
+    ].filter(Boolean),
+    screenshot,
+    trace,
+  };
+
+  return createFinding({
+    category,
+    type,
+    severity,
+    title,
+    why,
+    evidence,
+    related,
+    repro,
+    scope: 'runtime',
+    source: 'reality',
+  });
+}
+
+/**
+ * Create a contract drift finding
+ */
+function createDriftFinding({
+  type,
+  severity,
+  title,
+  message,
+  subject,
+  contractFile,
+  evidence = [],
+}) {
+  return createFinding({
+    category: 'ContractDrift',
+    type,
+    severity,
+    title,
+    message,
+    why: 'Contracts are the source of truth. Drift causes AI hallucinations.',
+    evidence: evidence.length > 0 ? evidence : [{
+      file: `.vibecheck/contracts/${contractFile || 'contracts'}`,
+      lines: '1',
+      reason: title,
+    }],
+    fixHints: [
+      "Run 'vibecheck ctx sync' to update contracts",
+      "Or revert the code change if unintended",
+    ],
+    scope: 'contracts',
+    source: 'drift',
+  });
+}
+
+/**
+ * Link related findings
+ */
+function linkFindings(findings) {
+  // Group findings by file
+  const byFile = new Map();
+  for (const f of findings) {
+    for (const ev of f.evidence || []) {
+      if (ev.file) {
+        if (!byFile.has(ev.file)) byFile.set(ev.file, []);
+        byFile.get(ev.file).push(f.id);
+      }
+    }
+  }
+
+  // Link findings that share files
+  for (const f of findings) {
+    const relatedIds = new Set();
+    for (const ev of f.evidence || []) {
+      if (ev.file && byFile.has(ev.file)) {
+        for (const id of byFile.get(ev.file)) {
+          if (id !== f.id) relatedIds.add(id);
+        }
+      }
+    }
+    f.related = [...relatedIds].slice(0, 5); // Max 5 related
+  }
+
+  return findings;
+}
+
+/**
+ * Validate a finding against v2 schema
+ */
+function validateFinding(finding) {
+  const errors = [];
+
+  // Required fields
+  if (!finding.id) errors.push('Missing id');
+  if (!finding.category) errors.push('Missing category');
+  if (!finding.severity) errors.push('Missing severity');
+  if (!['BLOCK', 'WARN', 'INFO'].includes(finding.severity)) {
+    errors.push(`Invalid severity: ${finding.severity}`);
+  }
+  if (!finding.title) errors.push('Missing title');
+
+  // v2 fields
+  if (!finding.fingerprint) errors.push('Missing fingerprint (v2)');
+  if (!finding.scope) errors.push('Missing scope (v2)');
+  if (!['client', 'server', 'runtime', 'contracts'].includes(finding.scope)) {
+    errors.push(`Invalid scope: ${finding.scope}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Migrate a v1 finding to v2 format
+ */
+function migrateFindingToV2(finding) {
+  // Already has fingerprint = already v2
+  if (finding.fingerprint && finding.scope) {
+    return finding;
+  }
+
+  // Generate fingerprint
+  const fingerprint = generateFingerprint(
+    finding.category || 'Unknown',
+    finding.type || finding.title,
+    finding.evidence?.[0]?.file
+  );
+
+  return {
+    ...finding,
+    fingerprint,
+    scope: finding.scope || inferScope(finding.category, finding.evidence),
+    repro: finding.repro || null,
+    related: finding.related || [],
+  };
+}
+
+module.exports = {
+  generateFingerprint,
+  inferScope,
+  createFinding,
+  createRuntimeFinding,
+  createDriftFinding,
+  linkFindings,
+  validateFinding,
+  migrateFindingToV2,
+};