@vibecheckai/cli 3.1.8 → 3.2.0

package/bin/runners/context/proof-context.js

@@ -1,11 +1,211 @@
 /**
  * Proof-Carrying Context System
  * Every claim must have file:line evidence or it gets flagged as hypothesis
+ * 
+ * This module exports the SINGLE TRUTH CONTRACT used across CLI, MCP, and extension.
  */
 
 const fs = require("fs");
 const path = require("path");
 
+const DEFAULT_EVIDENCE_CONFIDENCE = 0.9;
+const MAX_EVIDENCE_SNIPPET = 200;
+
+// Context attribution message shown when AI uses vibecheck data
+const CONTEXT_ATTRIBUTION = "🧠 Context enhanced by vibecheck";
+
+// =============================================================================
+// UNIFIED TRUTH CONTRACT SCHEMA v1.0
+// =============================================================================
+
+/**
+ * The canonical evidence schema used across CLI, MCP, and VS Code extension.
+ * All tools emitting claims MUST include this minimal required payload.
+ */
+const EVIDENCE_SCHEMA = {
+  version: "1.0.0",
+  required: ["file", "line", "snippet", "confidence"],
+  maxSnippet: MAX_EVIDENCE_SNIPPET,
+  confidenceThresholds: {
+    strict: 0.8,     // HIGH confidence required for strict mode
+    balanced: 0.6,   // MEDIUM confidence for balanced mode
+    permissive: 0.4, // LOW confidence allowed in permissive mode
+  },
+  claimTypes: [
+    "route",
+    "schema_table",
+    "schema_column",
+    "export",
+    "default_export",
+    "middleware",
+    "env_var",
+    "auth_guard",
+    "billing_gate",
+    "hypothesis", // Claims without proof get flagged here
+  ],
+};
+
+/**
+ * The truth contract defines rules that AI must satisfy.
+ * Claims without evidence are automatically flagged as "unknown" and block actions.
+ */
+const TRUTH_CONTRACT = {
+  version: "1.0.0",
+  claimsRequireEvidence: true,
+  confidenceThresholds: EVIDENCE_SCHEMA.confidenceThresholds,
+  policies: {
+    strict: {
+      minConfidence: 0.8,
+      allowUnknown: false,
+      requireValidation: true,
+      blockOnDrift: true,
+    },
+    balanced: {
+      minConfidence: 0.6,
+      allowUnknown: false,
+      requireValidation: true,
+      blockOnDrift: false,
+    },
+    permissive: {
+      minConfidence: 0.4,
+      allowUnknown: true,
+      requireValidation: false,
+      blockOnDrift: false,
+    },
+  },
+  invariants: [
+    "No paid feature without server-side enforcement",
+    "No success UI without confirmed success",
+    "No route reference without matching route map entry",
+    "No silent catch in auth/billing flows",
+    "No hardcoded secrets in production code",
+  ],
+};
+
+/**
+ * Normalize an evidence item to the canonical schema.
+ * @param {object} item - Raw evidence item
+ * @param {string} projectPath - Project root path
+ * @param {object} fallback - Fallback values
+ * @returns {object} Normalized evidence conforming to EVIDENCE_SCHEMA
+ */
+function normalizeToEvidenceSchema(item, projectPath, fallback = {}) {
+  const file = item?.file || fallback.file || "";
+  const line = Number(item?.line || item?.lines || fallback.line || 1);
+  let snippet = item?.snippet || item?.evidence || fallback.evidence || "";
+
+  if (!snippet && file && projectPath) {
+    try {
+      const content = fs.readFileSync(path.join(projectPath, file), "utf-8");
+      const lines = content.split("\n");
+      const idx = Math.max(0, Math.min(lines.length - 1, line - 1));
+      snippet = lines[idx] || "";
+    } catch {
+      // File not readable
+    }
+  }
+
+  return {
+    file,
+    line,
+    snippet: String(snippet || "").slice(0, EVIDENCE_SCHEMA.maxSnippet),
+    confidence: item?.confidence ?? fallback.confidence ?? DEFAULT_EVIDENCE_CONFIDENCE,
+  };
+}
+
+/**
+ * Validate that evidence conforms to the schema.
+ * @param {object} evidence - Evidence object to validate
+ * @param {string} policy - Policy mode: 'strict' | 'balanced' | 'permissive'
+ * @returns {{ valid: boolean, errors: string[], confidence: number }}
+ */
+function validateEvidence(evidence, policy = "balanced") {
+  const errors = [];
+  const thresholds = EVIDENCE_SCHEMA.confidenceThresholds;
+  const minConfidence = thresholds[policy] || thresholds.balanced;
+
+  // Check required fields
+  for (const field of EVIDENCE_SCHEMA.required) {
+    if (evidence[field] === undefined || evidence[field] === null || evidence[field] === "") {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Check confidence threshold
+  const confidence = evidence.confidence ?? 0;
+  if (confidence < minConfidence) {
+    errors.push(`Confidence ${confidence} below threshold ${minConfidence} for ${policy} policy`);
+  }
+
+  // Check snippet length
+  if (evidence.snippet && evidence.snippet.length > EVIDENCE_SCHEMA.maxSnippet) {
+    errors.push(`Snippet exceeds max length of ${EVIDENCE_SCHEMA.maxSnippet}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    confidence,
+  };
+}
+
+/**
+ * Create a claim with proper evidence attachment.
+ * @param {string} type - Claim type from EVIDENCE_SCHEMA.claimTypes
+ * @param {string} claim - Human-readable claim text
+ * @param {object} evidence - Evidence object
+ * @param {object} metadata - Additional metadata
+ * @returns {object} Properly formatted claim
+ */
+function createClaim(type, claim, evidence, metadata = {}) {
+  const isHypothesis = !evidence || !evidence.file;
+  
+  return {
+    id: `claim_${hashString(claim + (evidence?.file || ""))}`,
+    type: isHypothesis ? "hypothesis" : type,
+    claim,
+    evidence: evidence ? [evidence] : [],
+    metadata,
+    isVerified: !isHypothesis,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function normalizeEvidenceItem(projectPath, fact, item) {
+  const file = item?.file || fact.file || "";
+  const line = Number(item?.line || item?.lines || fact.line || 1);
+  let snippet = item?.snippet || item?.evidence || fact.evidence || "";
+
+  if (!snippet && file) {
+    try {
+      const content = fs.readFileSync(path.join(projectPath, file), "utf-8");
+      const lines = content.split("\n");
+      const idx = Math.max(0, Math.min(lines.length - 1, line - 1));
+      snippet = lines[idx] || "";
+    } catch {}
+  }
+
+  return {
+    file,
+    line,
+    snippet: String(snippet || "").slice(0, MAX_EVIDENCE_SNIPPET),
+    confidence: item?.confidence ?? fact.confidence ?? DEFAULT_EVIDENCE_CONFIDENCE,
+  };
+}
+
+function normalizeFactEvidence(projectPath, fact) {
+  const raw = Array.isArray(fact.evidence) ? fact.evidence : [fact.evidence];
+  const evidence = raw
+    .filter(Boolean)
+    .map((item) => normalizeEvidenceItem(projectPath, fact, item));
+
+  return {
+    ...fact,
+    confidence: fact.confidence ?? DEFAULT_EVIDENCE_CONFIDENCE,
+    evidence,
+  };
+}
+
 /**
  * Extract proof-carrying facts with exact file:line references
  */
@@ -32,6 +232,13 @@ function extractProofCarryingFacts(projectPath) {
   const middlewareFacts = extractVerifiedMiddleware(projectPath);
   facts.verified.push(...middlewareFacts);
 
+  facts.verified = facts.verified.map((fact) =>
+    normalizeFactEvidence(projectPath, fact),
+  );
+  facts.hypotheses = facts.hypotheses.map((fact) =>
+    normalizeFactEvidence(projectPath, fact),
+  );
+
   // Build proof map
   facts.verified.forEach(f => {
     facts.proofMap[f.claim] = {
@@ -609,6 +816,72 @@ function hashString(str) {
   return Math.abs(hash).toString(16);
 }
 
+/**
+ * Emit guardrail metrics to .vibecheck/audit/guardrail-metrics.jsonl
+ * KPIs tracked: false_positive_rate, unknown_rate, drift_score
+ */
+async function emitGuardrailMetric(projectPath, metric) {
+  const auditDir = path.join(projectPath, ".vibecheck", "audit");
+  try {
+    fs.mkdirSync(auditDir, { recursive: true });
+    const record = JSON.stringify({
+      ...metric,
+      timestamp: new Date().toISOString(),
+    });
+    fs.appendFileSync(
+      path.join(auditDir, "guardrail-metrics.jsonl"),
+      `${record}\n`
+    );
+  } catch {
+    // Ignore write failures in metrics
+  }
+}
+
+/**
+ * Aggregate guardrail KPIs from audit logs
+ * Returns: { falsePositiveRate, unknownRate, avgDriftScore, totalValidations }
+ */
+function aggregateGuardrailKPIs(projectPath) {
+  const auditLogPath = path.join(projectPath, ".vibecheck", "audit", "guardrail-metrics.jsonl");
+  
+  try {
+    const content = fs.readFileSync(auditLogPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean).map(l => JSON.parse(l));
+    
+    // Filter claim validations
+    const validations = lines.filter(l => l.event === "claim_validation");
+    const unknowns = validations.filter(l => l.result === "unknown");
+    const falsePositives = validations.filter(l => l.falsePositive === true);
+    
+    // Filter drift events
+    const drifts = lines.filter(l => l.event === "drift_detected");
+    const avgDriftScore = drifts.length > 0
+      ? drifts.reduce((sum, d) => sum + (d.score || 0), 0) / drifts.length
+      : 0;
+    
+    // Filter firewall blocks
+    const blocks = lines.filter(l => l.event === "truth_firewall_block");
+    
+    return {
+      totalValidations: validations.length,
+      unknownRate: validations.length > 0 ? unknowns.length / validations.length : 0,
+      falsePositiveRate: validations.length > 0 ? falsePositives.length / validations.length : 0,
+      avgDriftScore,
+      totalBlocks: blocks.length,
+      lastUpdated: new Date().toISOString(),
+    };
+  } catch {
+    return {
+      totalValidations: 0,
+      unknownRate: 0,
+      falsePositiveRate: 0,
+      avgDriftScore: 0,
+      totalBlocks: 0,
+      lastUpdated: new Date().toISOString(),
+    };
+  }
+}
+
 /**
  * Golden Path Replay Templates - recorded successful change patterns
  */
@@ -951,13 +1224,25 @@ function generateTruthPack(projectPath, analysis) {
       framework: analysis.framework,
       routes: analysis.proofCarryingFacts?.verified?.length,
       packages: analysis.symbolReality?.installedPackages?.size
-    }))
+    })),
+    
+    // Attribution message for AI responses
+    _attribution: CONTEXT_ATTRIBUTION,
+    _attributionNote: "Include this note when referencing vibecheck data: " + CONTEXT_ATTRIBUTION,
   };
 
   return pack;
 }
 
 module.exports = {
+  // Unified Truth Contract Schema (v1.0)
+  EVIDENCE_SCHEMA,
+  TRUTH_CONTRACT,
+  normalizeToEvidenceSchema,
+  validateEvidence,
+  createClaim,
+  
+  // Proof-Carrying Context Functions
   extractProofCarryingFacts,
   symbolVibecheck,
   computeFileImportanceScore,
@@ -969,4 +1254,11 @@ module.exports = {
   detectDrift,
   enforceOneFileRule,
   generateTruthPack,
+  
+  // Audit Metrics and KPIs
+  emitGuardrailMetric,
+  aggregateGuardrailKPIs,
+  
+  // Context Attribution
+  CONTEXT_ATTRIBUTION,
 };