@veraxhq/verax 0.2.0 → 0.3.0

package/src/verax/core/report/cross-index.js

@@ -0,0 +1,192 @@
+/**
+ * PHASE 21.10 — Artifact Cross-Index
+ * 
+ * Builds cross-index linking findingId to all related artifacts.
+ */
+
+import { readFileSync, existsSync, writeFileSync, readdirSync } from 'fs';
+import { resolve, relative } from 'path';
+
+/**
+ * Build cross-index
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Cross-index
+ */
+export function buildCrossIndex(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  
+  if (!existsSync(runDir)) {
+    return null;
+  }
+  
+  const index = {};
+  
+  // Load findings
+  const findingsPath = resolve(runDir, 'findings.json');
+  if (!existsSync(findingsPath)) {
+    return {
+      runId,
+      findings: {},
+      summary: { total: 0 },
+      generatedAt: new Date().toISOString()
+    };
+  }
+  
+  const findings = JSON.parse(readFileSync(findingsPath, 'utf-8'));
+  const evidenceIndex = loadArtifact(runDir, 'evidence.index.json');
+  const decisionTrace = loadArtifact(runDir, 'decisions.trace.json');
+  const timeline = loadArtifact(runDir, 'run.timeline.json');
+  const failureLedger = loadArtifact(runDir, 'failure.ledger.json');
+  const performanceReport = loadArtifact(runDir, 'performance.report.json');
+  
+  if (!Array.isArray(findings.findings)) {
+    return {
+      runId,
+      findings: {},
+      summary: { total: 0 },
+      generatedAt: new Date().toISOString()
+    };
+  }
+  
+  for (const finding of findings.findings) {
+    const findingId = finding.findingId || finding.id || `finding-${Object.keys(index).length}`;
+    
+    const entry = {
+      findingId,
+      type: finding.type || null,
+      status: finding.severity || finding.status || null,
+      
+      // Evidence files
+      evidence: {
+        packageId: finding.evidencePackage?.id || null,
+        files: finding.evidencePackage?.files || [],
+        isComplete: finding.evidencePackage?.isComplete || false,
+        beforeScreenshot: finding.evidence?.before || null,
+        afterScreenshot: finding.evidence?.after || null
+      },
+      
+      // Confidence reasons
+      confidence: {
+        level: finding.confidenceLevel || null,
+        score: finding.confidence !== undefined ? finding.confidence : null,
+        reasons: finding.confidenceReasons || [],
+        trace: decisionTrace?.findings?.find(t => t.findingId === findingId)?.confidence || null
+      },
+      
+      // Guardrails rules
+      guardrails: {
+        applied: finding.guardrails?.appliedRules?.map(r => ({
+          id: r.id || r,
+          category: r.category || null,
+          action: r.action || null
+        })) || [],
+        finalDecision: finding.guardrails?.finalDecision || null,
+        contradictions: finding.guardrails?.contradictions || [],
+        trace: decisionTrace?.findings?.find(t => t.findingId === findingId)?.guardrails || null
+      },
+      
+      // Failures (if any related)
+      failures: failureLedger?.failures?.filter(f => 
+        f.context?.findingId === findingId || 
+        f.message?.includes(findingId)
+      ).map(f => ({
+        code: f.code,
+        message: f.message,
+        severity: f.severity,
+        timestamp: f.timestamp
+      })) || [],
+      
+      // Performance impacts (if any)
+      performance: performanceReport?.violations?.some(v => 
+        v.message?.includes(findingId)
+      ) ? {
+        impacted: true,
+        violations: performanceReport.violations.filter(v => 
+          v.message?.includes(findingId)
+        )
+      } : null,
+      
+      // Timeline entries
+      timeline: timeline?.events?.filter(e => 
+        e.data?.findingId === findingId ||
+        (e.event === 'guardrails_applied' && e.data?.findingId === findingId) ||
+        (e.event === 'evidence_enforced' && e.data?.findingId === findingId)
+      ).map(e => ({
+        timestamp: e.timestamp,
+        phase: e.phase,
+        event: e.event,
+        data: e.data
+      })) || []
+    };
+    
+    index[findingId] = entry;
+  }
+  
+  return {
+    runId,
+    findings: index,
+    summary: {
+      total: Object.keys(index).length,
+      withEvidence: Object.values(index).filter(e => e.evidence.files.length > 0).length,
+      withGuardrails: Object.values(index).filter(e => e.guardrails.applied.length > 0).length,
+      withFailures: Object.values(index).filter(e => e.failures.length > 0).length,
+      withTimeline: Object.values(index).filter(e => e.timeline.length > 0).length
+    },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Load artifact JSON
+ */
+function loadArtifact(runDir, filename) {
+  const path = resolve(runDir, filename);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write cross-index to file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} index - Cross-index
+ * @returns {string} Path to written file
+ */
+export function writeCrossIndex(projectDir, runId, index) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const outputPath = resolve(runDir, 'artifacts.index.json');
+  writeFileSync(outputPath, JSON.stringify(index, null, 2), 'utf-8');
+  return outputPath;
+}
+
+/**
+ * Load cross-index from file
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Cross-index or null
+ */
+export function loadCrossIndex(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const indexPath = resolve(runDir, 'artifacts.index.json');
+  
+  if (!existsSync(indexPath)) {
+    return null;
+  }
+  
+  try {
+    return JSON.parse(readFileSync(indexPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+

package/src/verax/core/report/human-summary.js

@@ -0,0 +1,222 @@
+/**
+ * PHASE 21.10 — Human Summary
+ * 
+ * Generates human-readable summary for Enterprise UX.
+ * Clear, direct, no marketing.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Load artifact JSON
+ */
+function loadArtifact(runDir, filename) {
+  const path = resolve(runDir, filename);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate human summary
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Human summary
+ */
+export async function generateHumanSummary(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  
+  if (!existsSync(runDir)) {
+    return null;
+  }
+  
+  const summary = loadArtifact(runDir, 'summary.json');
+  const findings = loadArtifact(runDir, 'findings.json');
+  const determinism = loadArtifact(runDir, 'decisions.json');
+  const performanceReport = loadArtifact(runDir, 'performance.report.json');
+  
+  // Security reports are in release/ directory (project root)
+  // Use projectDir parameter directly (already resolved)
+  const releaseDir = resolve(projectDir, 'release');
+  const securitySecrets = loadArtifact(releaseDir, 'security.secrets.report.json');
+  const securityVuln = loadArtifact(releaseDir, 'security.vuln.report.json');
+  
+  const gaStatus = loadArtifact(runDir, 'ga.status.json');
+  
+  if (!summary) {
+    return null;
+  }
+  
+  const findingsArray = Array.isArray(findings?.findings) ? findings.findings : [];
+  const confirmedFindings = findingsArray.filter(f => (f.severity || f.status) === 'CONFIRMED');
+  const suspectedFindings = findingsArray.filter(f => (f.severity || f.status) === 'SUSPECTED');
+  
+  // What VERAX is confident about
+  const confident = {
+    findings: confirmedFindings.length,
+    message: confirmedFindings.length > 0 
+      ? `${confirmedFindings.length} finding(s) with complete evidence`
+      : 'No findings with complete evidence',
+    details: confirmedFindings.map(f => ({
+      type: f.type,
+      outcome: f.outcome,
+      confidence: f.confidenceLevel || 'UNKNOWN'
+    }))
+  };
+  
+  // What VERAX is NOT confident about
+  const notConfident = {
+    findings: suspectedFindings.length,
+    message: suspectedFindings.length > 0
+      ? `${suspectedFindings.length} finding(s) with incomplete evidence (SUSPECTED)`
+      : 'No findings with incomplete evidence',
+    details: suspectedFindings.map(f => ({
+      type: f.type,
+      outcome: f.outcome,
+      confidence: f.confidenceLevel || 'UNKNOWN',
+      missingEvidence: f.evidencePackage?.isComplete === false
+    }))
+  };
+  
+  // Why some things were skipped
+  const skips = [];
+  if (summary.truth?.observe?.skips) {
+    for (const skip of summary.truth.observe.skips) {
+      skips.push({
+        reason: skip.reason || skip.code || 'UNKNOWN',
+        count: skip.count || 1,
+        message: skip.message || `Skipped: ${skip.reason || skip.code}`
+      });
+    }
+  }
+  
+  // Determinism verdict
+  let determinismVerdict = 'UNKNOWN';
+  if (determinism) {
+    try {
+      const { DecisionRecorder } = await import('../../../core/determinism-model.js');
+      const recorder = DecisionRecorder.fromExport(determinism);
+      const { computeDeterminismVerdict } = await import('../../../core/determinism/contract.js');
+      const verdict = computeDeterminismVerdict(recorder);
+      determinismVerdict = verdict.verdict;
+    } catch {
+      determinismVerdict = summary.determinism?.verdict || 'UNKNOWN';
+    }
+  } else if (summary.determinism) {
+    determinismVerdict = summary.determinism.verdict || 'UNKNOWN';
+  }
+  
+  // Performance verdict
+  const performanceVerdict = performanceReport?.verdict || 'UNKNOWN';
+  const performanceOk = performanceReport?.ok !== false;
+  
+  // Security verdict
+  const securityOk = !securitySecrets?.hasSecrets && 
+                     !securityVuln?.blocking &&
+                     (securitySecrets !== null || securityVuln !== null); // At least one report exists
+  
+  // GA verdict
+  const gaReady = gaStatus?.gaReady === true;
+  const gaVerdict = gaReady ? 'GA-READY' : (gaStatus ? 'GA-BLOCKED' : 'UNKNOWN');
+  
+  return {
+    runId,
+    whatWeKnow: {
+      confident: confident,
+      notConfident: notConfident,
+      skips: skips.length > 0 ? {
+        total: skips.reduce((sum, s) => sum + s.count, 0),
+        reasons: skips
+      } : null
+    },
+    verdicts: {
+      determinism: {
+        verdict: determinismVerdict,
+        message: determinismVerdict === 'DETERMINISTIC' 
+          ? 'Run was reproducible (same inputs = same outputs)'
+          : determinismVerdict === 'NON_DETERMINISTIC'
+          ? 'Run was not reproducible (adaptive events detected)'
+          : 'Determinism not evaluated'
+      },
+      performance: {
+        verdict: performanceVerdict,
+        ok: performanceOk,
+        message: performanceOk
+          ? 'Performance within budget'
+          : performanceReport?.violations?.length > 0
+          ? `${performanceReport.violations.length} BLOCKING performance violation(s)`
+          : 'Performance not evaluated'
+      },
+      security: {
+        ok: securityOk,
+        message: securityOk
+          ? 'Security baseline passed'
+          : securitySecrets?.hasSecrets
+          ? 'Secrets detected'
+          : securityVuln?.blocking
+          ? 'Critical vulnerabilities detected'
+          : 'Security not evaluated'
+      },
+      ga: {
+        verdict: gaVerdict,
+        ready: gaReady,
+        message: gaReady
+          ? 'GA-READY: All gates passed'
+          : gaStatus
+          ? `GA-BLOCKED: ${gaStatus.blockers?.length || 0} blocker(s)`
+          : 'GA not evaluated'
+      }
+    },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Format human summary for CLI display
+ * 
+ * @param {Object} summary - Human summary
+ * @returns {string} Formatted string
+ */
+export function formatHumanSummary(summary) {
+  if (!summary) {
+    return 'Summary: Not available';
+  }
+  
+  const lines = [];
+  lines.push('\n' + '='.repeat(80));
+  lines.push('HUMAN SUMMARY');
+  lines.push('='.repeat(80));
+  
+  // What we know
+  lines.push('\nWhat VERAX is confident about:');
+  lines.push(`  ${summary.whatWeKnow.confident.message}`);
+  
+  lines.push('\nWhat VERAX is NOT confident about:');
+  lines.push(`  ${summary.whatWeKnow.notConfident.message}`);
+  
+  if (summary.whatWeKnow.skips) {
+    lines.push('\nWhy some things were skipped:');
+    for (const skip of summary.whatWeKnow.skips.reasons) {
+      lines.push(`  - ${skip.message} (${skip.count}x)`);
+    }
+  }
+  
+  // Verdicts
+  lines.push('\nVerdicts:');
+  lines.push(`  Determinism: ${summary.verdicts.determinism.verdict} - ${summary.verdicts.determinism.message}`);
+  lines.push(`  Performance: ${summary.verdicts.performance.verdict} - ${summary.verdicts.performance.message}`);
+  lines.push(`  Security: ${summary.verdicts.security.ok ? 'OK' : 'BLOCKED'} - ${summary.verdicts.security.message}`);
+  lines.push(`  GA: ${summary.verdicts.ga.verdict} - ${summary.verdicts.ga.message}`);
+  
+  lines.push('='.repeat(80) + '\n');
+  
+  return lines.join('\n');
+}
+