vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/contracts.js

@@ -0,0 +1,804 @@
+/**
+ * Contracts Generator + Drift Detector v2
+ * 
+ * Generates contracts from truthpack and detects drift between runs.
+ * The hallucination stopper - AI can't invent endpoints, env vars, or auth.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const { createFinding, getSeverity } = require("./schemas/validator");
+
+// =============================================================================
+// CONTRACT TYPES
+// =============================================================================
+
+const CONTRACT_TYPES = {
+  ROUTES: "routes",
+  ENV: "env",
+  AUTH: "auth",
+  EXTERNAL: "external",
+};
+
+// =============================================================================
+// CONTRACT GENERATION
+// =============================================================================
+
+/**
+ * Generate all contracts from truthpack
+ */
+function generateContracts(truthpack, options = {}) {
+  const { includeInternal = false } = options;
+
+  const contracts = {
+    meta: {
+      version: "2.0.0",
+      generatedAt: new Date().toISOString(),
+      truthpackHash: computeHash(JSON.stringify(truthpack)),
+    },
+    routes: generateRouteContract(truthpack),
+    env: generateEnvContract(truthpack),
+    auth: generateAuthContract(truthpack),
+    external: generateExternalContract(truthpack),
+  };
+
+  // Compute contract hashes
+  contracts.hashes = {
+    routes: computeHash(JSON.stringify(contracts.routes)),
+    env: computeHash(JSON.stringify(contracts.env)),
+    auth: computeHash(JSON.stringify(contracts.auth)),
+    external: computeHash(JSON.stringify(contracts.external)),
+  };
+
+  return contracts;
+}
+
+/**
+ * Generate route contract
+ */
+function generateRouteContract(truthpack) {
+  const routes = truthpack?.routes?.server || [];
+  
+  return {
+    endpoints: routes.map(r => ({
+      method: r.method,
+      path: r.path,
+      file: r.file,
+      confidence: r.confidence,
+      authRequired: r.authRequired || false,
+      paidOnly: r.paidOnly || false,
+    })),
+    count: routes.length,
+    byMethod: countByField(routes, "method"),
+    byConfidence: countByField(routes, "confidence"),
+  };
+}
+
+/**
+ * Generate env contract
+ */
+function generateEnvContract(truthpack) {
+  const env = truthpack?.env || {};
+  const vars = env.vars || [];
+  const declared = env.declared || [];
+
+  // Classify vars by prefix
+  const classified = {
+    public: vars.filter(v => v.name.startsWith("NEXT_PUBLIC_") || v.name.startsWith("VITE_")),
+    server: vars.filter(v => !v.name.startsWith("NEXT_PUBLIC_") && !v.name.startsWith("VITE_")),
+  };
+
+  // Required vs optional (heuristic: used in multiple files = required)
+  const required = vars.filter(v => v.usageCount > 1 || v.required);
+  const optional = vars.filter(v => v.usageCount <= 1 && !v.required);
+
+  return {
+    variables: vars.map(v => ({
+      name: v.name,
+      required: v.required || v.usageCount > 1,
+      public: v.name.startsWith("NEXT_PUBLIC_") || v.name.startsWith("VITE_"),
+      declaredIn: declared.includes(v.name) ? ".env.example" : null,
+      usageCount: v.usageCount || 1,
+    })),
+    count: vars.length,
+    requiredCount: required.length,
+    publicCount: classified.public.length,
+    declared: declared,
+  };
+}
+
+/**
+ * Generate auth contract
+ */
+function generateAuthContract(truthpack) {
+  const auth = truthpack?.auth || {};
+
+  return {
+    providers: auth.providers || [],
+    protectedPatterns: auth.nextMatcherPatterns || [],
+    middleware: {
+      next: auth.nextMiddleware?.length > 0,
+      fastify: auth.fastify?.preHandlerHooks?.length > 0,
+    },
+    rbacDetected: auth.rbacPatterns?.length > 0,
+    signals: {
+      sessionChecks: auth.sessionChecks || [],
+      redirects: auth.redirects || [],
+    },
+  };
+}
+
+/**
+ * Generate external services contract
+ */
+function generateExternalContract(truthpack) {
+  const billing = truthpack?.billing || {};
+  const integrations = truthpack?.integrations || [];
+
+  return {
+    stripe: {
+      detected: billing.stripeDetected || false,
+      webhookVerified: billing.webhookSignatureVerification || false,
+      products: billing.products || [],
+    },
+    services: integrations.map(i => ({
+      name: i.name,
+      type: i.type,
+      envVars: i.envVars || [],
+    })),
+  };
+}
+
+// =============================================================================
+// DRIFT DETECTION
+// =============================================================================
+
+/**
+ * Detect drift between two contract sets
+ */
+function detectDrift(currentContracts, previousContracts, options = {}) {
+  const { strict = false } = options;
+
+  const findings = [];
+
+  // Route drift
+  const routeDrift = detectRouteDrift(
+    currentContracts.routes,
+    previousContracts.routes,
+    { strict }
+  );
+  findings.push(...routeDrift);
+
+  // Env drift
+  const envDrift = detectEnvDrift(
+    currentContracts.env,
+    previousContracts.env,
+    { strict }
+  );
+  findings.push(...envDrift);
+
+  // Auth drift
+  const authDrift = detectAuthDrift(
+    currentContracts.auth,
+    previousContracts.auth,
+    { strict }
+  );
+  findings.push(...authDrift);
+
+  // External drift
+  const externalDrift = detectExternalDrift(
+    currentContracts.external,
+    previousContracts.external,
+    { strict }
+  );
+  findings.push(...externalDrift);
+
+  return {
+    hasDrift: findings.length > 0,
+    findings,
+    summary: {
+      routes: routeDrift.length,
+      env: envDrift.length,
+      auth: authDrift.length,
+      external: externalDrift.length,
+    },
+  };
+}
+
+/**
+ * Detect route drift
+ */
+function detectRouteDrift(current, previous, options = {}) {
+  const findings = [];
+  const { strict } = options;
+
+  const currentPaths = new Set(current.endpoints.map(e => `${e.method}:${e.path}`));
+  const previousPaths = new Set(previous.endpoints.map(e => `${e.method}:${e.path}`));
+
+  // New routes (not in previous)
+  for (const ep of current.endpoints) {
+    const key = `${ep.method}:${ep.path}`;
+    if (!previousPaths.has(key)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ROUTE_NEW",
+        severity: "INFO",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `New route added: ${ep.method} ${ep.path}`,
+        why: "Route was added since last contract sync",
+        confidence: "high",
+        path: ep.path,
+        method: ep.method,
+        evidence: [{
+          kind: "file",
+          file: ep.file,
+          reason: "New route definition",
+        }],
+      }));
+    }
+  }
+
+  // Removed routes (in previous but not current)
+  for (const ep of previous.endpoints) {
+    const key = `${ep.method}:${ep.path}`;
+    if (!currentPaths.has(key)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ROUTE_REMOVED",
+        severity: strict ? "BLOCK" : "WARN",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Route removed: ${ep.method} ${ep.path}`,
+        why: "Route existed in previous contract but is now missing",
+        confidence: "high",
+        path: ep.path,
+        method: ep.method,
+        evidence: [{
+          kind: "file",
+          file: ep.file,
+          reason: "Route no longer exists",
+        }],
+      }));
+    }
+  }
+
+  // Auth requirement changes
+  for (const ep of current.endpoints) {
+    const key = `${ep.method}:${ep.path}`;
+    const prev = previous.endpoints.find(p => `${p.method}:${p.path}` === key);
+    
+    if (prev && prev.authRequired && !ep.authRequired) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_AUTH_REMOVED",
+        severity: "BLOCK",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Auth removed from route: ${ep.method} ${ep.path}`,
+        why: "Route previously required auth but no longer does",
+        confidence: "high",
+        path: ep.path,
+        method: ep.method,
+        evidence: [{
+          kind: "file",
+          file: ep.file,
+          reason: "Auth requirement removed",
+        }],
+      }));
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect env drift
+ */
+function detectEnvDrift(current, previous, options = {}) {
+  const findings = [];
+  const { strict } = options;
+
+  const currentVars = new Set(current.variables.map(v => v.name));
+  const previousVars = new Set(previous.variables.map(v => v.name));
+
+  // New required env vars
+  for (const v of current.variables) {
+    if (v.required && !previousVars.has(v.name)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ENV_NEW_REQUIRED",
+        severity: strict ? "BLOCK" : "WARN",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `New required env var: ${v.name}`,
+        why: "New required environment variable added",
+        confidence: "high",
+        evidence: [{
+          kind: "file",
+          reason: `${v.name} is required but not in previous contract`,
+        }],
+      }));
+    }
+  }
+
+  // Required vars removed (may break existing deployments)
+  for (const v of previous.variables) {
+    if (v.required && !currentVars.has(v.name)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ENV_REMOVED",
+        severity: "INFO",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Env var removed: ${v.name}`,
+        why: "Environment variable no longer used",
+        confidence: "high",
+        evidence: [{
+          kind: "file",
+          reason: `${v.name} was in previous contract but not current`,
+        }],
+      }));
+    }
+  }
+
+  // Public → Server (security concern)
+  for (const v of current.variables) {
+    const prev = previous.variables.find(p => p.name === v.name);
+    if (prev && prev.public && !v.public) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ENV_PUBLIC_TO_SERVER",
+        severity: "INFO",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Env var moved from public to server: ${v.name}`,
+        why: "Variable changed from public to server-only (good for security)",
+        confidence: "medium",
+        evidence: [{
+          kind: "file",
+          reason: `${v.name} prefix changed`,
+        }],
+      }));
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect auth drift
+ */
+function detectAuthDrift(current, previous, options = {}) {
+  const findings = [];
+
+  // Protected patterns removed
+  const currentPatterns = new Set(current.protectedPatterns);
+  const previousPatterns = new Set(previous.protectedPatterns);
+
+  for (const pattern of previousPatterns) {
+    if (!currentPatterns.has(pattern)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_AUTH_PATTERN_REMOVED",
+        severity: "BLOCK",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Protected pattern removed: ${pattern}`,
+        why: "Auth protection pattern was removed from middleware",
+        confidence: "high",
+        evidence: [{
+          kind: "file",
+          reason: `Pattern "${pattern}" no longer in matcher`,
+        }],
+      }));
+    }
+  }
+
+  // Middleware disabled
+  if (previous.middleware.next && !current.middleware.next) {
+    findings.push(createFinding({
+      detectorId: "D_DRIFT_AUTH_MIDDLEWARE_DISABLED",
+      severity: "BLOCK",
+      category: "ContractDrift",
+      scope: "contracts",
+      title: "Next.js auth middleware disabled",
+      why: "Auth middleware was active but is now disabled",
+      confidence: "high",
+      evidence: [{
+        kind: "file",
+        reason: "middleware.ts no longer exports auth matcher",
+      }],
+    }));
+  }
+
+  return findings;
+}
+
+/**
+ * Detect external service drift
+ */
+function detectExternalDrift(current, previous, options = {}) {
+  const findings = [];
+
+  // Stripe webhook verification removed
+  if (previous.stripe.webhookVerified && !current.stripe.webhookVerified) {
+    findings.push(createFinding({
+      detectorId: "D_DRIFT_STRIPE_VERIFY_REMOVED",
+      severity: "BLOCK",
+      category: "ContractDrift",
+      scope: "contracts",
+      title: "Stripe webhook verification removed",
+      why: "Stripe webhook signature verification was present but removed",
+      confidence: "high",
+      evidence: [{
+        kind: "file",
+        reason: "constructEvent or verifyHeader no longer called",
+      }],
+    }));
+  }
+
+  return findings;
+}
+
+// =============================================================================
+// CONTRACT SYNC (ctx sync)
+// =============================================================================
+
+/**
+ * Sync contracts - generate and save
+ */
+function syncContracts(truthpack, repoRoot) {
+  const contracts = generateContracts(truthpack);
+
+  const contractsDir = path.join(repoRoot, ".vibecheck", "contracts");
+  fs.mkdirSync(contractsDir, { recursive: true });
+
+  // Write individual contract files
+  for (const type of Object.values(CONTRACT_TYPES)) {
+    if (contracts[type]) {
+      fs.writeFileSync(
+        path.join(contractsDir, `${type}.json`),
+        JSON.stringify(contracts[type], null, 2)
+      );
+    }
+  }
+
+  // Write combined contracts
+  fs.writeFileSync(
+    path.join(contractsDir, "contracts.json"),
+    JSON.stringify(contracts, null, 2)
+  );
+
+  // Write hashes for quick drift check
+  fs.writeFileSync(
+    path.join(contractsDir, "hashes.json"),
+    JSON.stringify(contracts.hashes, null, 2)
+  );
+
+  return contracts;
+}
+
+/**
+ * Load previous contracts for drift comparison
+ */
+function loadPreviousContracts(repoRoot) {
+  const contractsPath = path.join(repoRoot, ".vibecheck", "contracts", "contracts.json");
+  
+  if (!fs.existsSync(contractsPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(contractsPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Guard contracts - check for drift and generate findings
+ */
+function guardContracts(truthpack, repoRoot, options = {}) {
+  const previous = loadPreviousContracts(repoRoot);
+  
+  if (!previous) {
+    // No previous contracts, just sync
+    const contracts = syncContracts(truthpack, repoRoot);
+    return {
+      isFirstRun: true,
+      hasDrift: false,
+      findings: [],
+      contracts,
+    };
+  }
+
+  const current = generateContracts(truthpack);
+  const drift = detectDrift(current, previous, options);
+
+  // If no blockers, update contracts
+  const hasBlockers = drift.findings.some(f => f.severity === "BLOCK");
+  if (!hasBlockers) {
+    syncContracts(truthpack, repoRoot);
+  }
+
+  return {
+    isFirstRun: false,
+    hasDrift: drift.hasDrift,
+    hasBlockers,
+    findings: drift.findings,
+    contracts: current,
+    previous,
+  };
+}
+
+// =============================================================================
+// DRIFT EXPLAINABILITY
+// =============================================================================
+
+/**
+ * Generate detailed drift explanation with remediation
+ */
+function explainDrift(driftResult) {
+  const { findings, summary } = driftResult;
+  
+  const explanation = {
+    summary: {
+      hasDrift: driftResult.hasDrift,
+      totalChanges: findings.length,
+      byCategory: summary,
+      verdict: findings.some(f => f.severity === "BLOCK") ? "BLOCK" : 
+               findings.some(f => f.severity === "WARN") ? "WARN" : "OK",
+    },
+    changes: [],
+    remediation: [],
+  };
+
+  for (const finding of findings) {
+    const change = {
+      type: getChangeType(finding.detectorId),
+      severity: finding.severity,
+      title: finding.title,
+      why: finding.why || getWhyMessage(finding),
+      impact: getImpactMessage(finding),
+      remediation: getRemediationCommand(finding),
+    };
+    explanation.changes.push(change);
+    
+    if (change.remediation) {
+      explanation.remediation.push(change.remediation);
+    }
+  }
+
+  return explanation;
+}
+
+/**
+ * Get change type from detector ID
+ */
+function getChangeType(detectorId) {
+  const types = {
+    "D_DRIFT_ROUTE_NEW": "added",
+    "D_DRIFT_ROUTE_REMOVED": "removed",
+    "D_DRIFT_AUTH_REMOVED": "modified",
+    "D_DRIFT_ENV_NEW_REQUIRED": "added",
+    "D_DRIFT_ENV_REMOVED": "removed",
+    "D_DRIFT_ENV_PUBLIC_TO_SERVER": "modified",
+    "D_DRIFT_AUTH_PATTERN_REMOVED": "removed",
+    "D_DRIFT_AUTH_PATTERN_NEW": "added",
+    "D_DRIFT_EXTERNAL_NEW": "added",
+    "D_DRIFT_EXTERNAL_REMOVED": "removed",
+  };
+  return types[detectorId] || "unknown";
+}
+
+/**
+ * Get why message for finding
+ */
+function getWhyMessage(finding) {
+  const messages = {
+    "D_DRIFT_ROUTE_NEW": "New endpoint referenced by client but not in previous contract",
+    "D_DRIFT_ROUTE_REMOVED": "Endpoint was in contract but no longer exists in codebase",
+    "D_DRIFT_AUTH_REMOVED": "Route lost auth protection - potential security regression",
+    "D_DRIFT_ENV_NEW_REQUIRED": "New required env var may break deployments without it",
+    "D_DRIFT_ENV_REMOVED": "Env var no longer used - can be cleaned up",
+    "D_DRIFT_AUTH_PATTERN_REMOVED": "Auth protection pattern removed from middleware",
+    "D_DRIFT_AUTH_PATTERN_NEW": "New route pattern added to auth middleware",
+    "D_DRIFT_EXTERNAL_NEW": "New external API dependency detected",
+    "D_DRIFT_EXTERNAL_REMOVED": "External API dependency removed",
+  };
+  return messages[finding.detectorId] || "Contract changed since last sync";
+}
+
+/**
+ * Get impact message for finding
+ */
+function getImpactMessage(finding) {
+  if (finding.severity === "BLOCK") {
+    return "This change may cause runtime failures or security issues";
+  }
+  if (finding.severity === "WARN") {
+    return "This change should be reviewed before shipping";
+  }
+  return "This change is informational";
+}
+
+/**
+ * Get remediation command for finding
+ */
+function getRemediationCommand(finding) {
+  const detectorId = finding.detectorId;
+  
+  // If the change is intentional, sync contracts
+  if (detectorId.includes("NEW") || detectorId.includes("ADDED")) {
+    return {
+      ifIntentional: "vibecheck ctx sync",
+      description: "If this change is intentional, sync contracts",
+    };
+  }
+  
+  if (detectorId.includes("REMOVED")) {
+    if (detectorId.includes("ROUTE")) {
+      return {
+        ifIntentional: "vibecheck ctx sync",
+        ifAccidental: `Add route back or remove client call to ${finding.evidence?.[0]?.path || "the endpoint"}`,
+        description: "Route was removed - verify this is intentional",
+      };
+    }
+    if (detectorId.includes("AUTH")) {
+      return {
+        ifIntentional: "vibecheck ctx sync --force",
+        ifAccidental: "Restore auth protection to the route",
+        description: "Auth was removed - this is usually NOT intentional",
+      };
+    }
+  }
+  
+  return {
+    ifIntentional: "vibecheck ctx sync",
+    description: "Review the change and sync if intentional",
+  };
+}
+
+/**
+ * Write contracts diff to disk
+ */
+function writeContractsDiff(repoRoot, driftResult) {
+  const dir = path.join(repoRoot, ".vibecheck");
+  fs.mkdirSync(dir, { recursive: true });
+
+  const explanation = explainDrift(driftResult);
+  
+  const diff = {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      verdict: explanation.summary.verdict,
+    },
+    ...explanation,
+  };
+
+  const diffPath = path.join(dir, "contracts_diff.json");
+  fs.writeFileSync(diffPath, JSON.stringify(diff, null, 2));
+
+  return { path: diffPath, explanation };
+}
+
+/**
+ * Print drift report to console
+ */
+function printDriftReport(driftResult) {
+  const explanation = explainDrift(driftResult);
+  
+  console.log("\n" + "=".repeat(60));
+  console.log("📋 CONTRACT DRIFT REPORT");
+  console.log("=".repeat(60));
+  
+  if (!driftResult.hasDrift) {
+    console.log("\n✅ No drift detected - contracts are in sync\n");
+    return;
+  }
+
+  const verdictEmoji = {
+    BLOCK: "🚫",
+    WARN: "⚠️",
+    OK: "✅",
+  }[explanation.summary.verdict];
+
+  console.log(`\nVerdict: ${verdictEmoji} ${explanation.summary.verdict}`);
+  console.log(`Changes: ${explanation.summary.totalChanges}`);
+  
+  // Group by severity
+  const blockers = explanation.changes.filter(c => c.severity === "BLOCK");
+  const warnings = explanation.changes.filter(c => c.severity === "WARN");
+  const infos = explanation.changes.filter(c => c.severity === "INFO");
+
+  if (blockers.length > 0) {
+    console.log("\n🚫 BLOCKERS:");
+    for (const change of blockers) {
+      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
+      console.log(`   └─ Why: ${change.why}`);
+      if (change.remediation?.ifAccidental) {
+        console.log(`   └─ Fix: ${change.remediation.ifAccidental}`);
+      }
+    }
+  }
+
+  if (warnings.length > 0) {
+    console.log("\n⚠️  WARNINGS:");
+    for (const change of warnings) {
+      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
+      console.log(`   └─ Why: ${change.why}`);
+    }
+  }
+
+  if (infos.length > 0) {
+    console.log("\nℹ️  INFO:");
+    for (const change of infos) {
+      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
+    }
+  }
+
+  // Remediation
+  console.log("\n" + "-".repeat(60));
+  console.log("REMEDIATION:");
+  
+  if (explanation.summary.verdict === "BLOCK") {
+    console.log("\n   If changes are INTENTIONAL:");
+    console.log("   $ vibecheck ctx sync --force");
+    console.log("\n   If changes are ACCIDENTAL:");
+    console.log("   - Review the blockers above and fix the issues");
+    console.log("   - Then run: vibecheck ctx sync");
+  } else {
+    console.log("\n   To accept these changes:");
+    console.log("   $ vibecheck ctx sync");
+  }
+  
+  console.log("\n" + "=".repeat(60) + "\n");
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function computeHash(content) {
+  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+function countByField(items, field) {
+  const counts = {};
+  for (const item of items) {
+    const value = item[field] || "unknown";
+    counts[value] = (counts[value] || 0) + 1;
+  }
+  return counts;
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+module.exports = {
+  // Contract types
+  CONTRACT_TYPES,
+
+  // Generation
+  generateContracts,
+  generateRouteContract,
+  generateEnvContract,
+  generateAuthContract,
+  generateExternalContract,
+
+  // Drift detection
+  detectDrift,
+  detectRouteDrift,
+  detectEnvDrift,
+  detectAuthDrift,
+  detectExternalDrift,
+
+  // Drift explainability
+  explainDrift,
+  writeContractsDiff,
+  printDriftReport,
+
+  // Sync/Guard
+  syncContracts,
+  loadPreviousContracts,
+  guardContracts,
+};