@veraxhq/verax 0.2.1 → 0.3.0

package/src/cli/commands/gates.js

@@ -0,0 +1,95 @@
+/**
+ * PHASE 19 — Capability Gates CLI Command
+ * 
+ * Evaluates all capability gates and reports PASS/FAIL.
+ */
+
+import {
+  evaluateAllCapabilityGates,
+  buildGateContext,
+} from '../../verax/core/capabilities/gates.js';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * PHASE 19: `verax gates` command
+ * 
+ * @param {Object} options - Options
+ * @param {boolean} options.json - Output as JSON
+ * @param {boolean} options.verbose - Verbose output
+ */
+export async function gatesCommand(options = {}) {
+  const { json = false, verbose = false } = options;
+  
+  // Pass explicit project root to ensure correct path resolution
+  const projectRoot = resolve(__dirname, '../../..');
+  const context = await buildGateContext({ projectRoot });
+  const result = evaluateAllCapabilityGates(context);
+  
+  if (json) {
+    console.log(JSON.stringify({
+      pass: result.pass,
+      summary: result.summary,
+      perCapability: result.perCapability,
+    }, null, 2));
+  } else {
+    // Human-readable output
+    console.log('\n' + '='.repeat(80));
+    console.log('CAPABILITY GATES EVALUATION');
+    console.log('='.repeat(80));
+    console.log(`\nStatus: ${result.pass ? '✅ PASS' : '❌ FAIL'}`);
+    console.log(`Total Capabilities: ${result.summary.total}`);
+    console.log(`Passing: ${result.summary.pass}`);
+    console.log(`Failing: ${result.summary.fail}`);
+    
+    if (!result.pass) {
+      console.log('\n' + '-'.repeat(80));
+      console.log('FAILING CAPABILITIES:');
+      console.log('-'.repeat(80));
+      
+      for (const failure of result.summary.allFailures) {
+        console.log(`\n❌ ${failure.capabilityId}`);
+        for (const gateFailure of failure.failures) {
+          console.log(`   └─ ${gateFailure.reasonCode}: ${gateFailure.message}`);
+        }
+        if (failure.warnings && failure.warnings.length > 0) {
+          for (const warning of failure.warnings) {
+            console.log(`   ⚠️  ${warning.reasonCode}: ${warning.message}`);
+          }
+        }
+      }
+      
+      if (verbose) {
+        console.log('\n' + '-'.repeat(80));
+        console.log('REQUIREMENTS BY MATURITY LEVEL:');
+        console.log('-'.repeat(80));
+        console.log('\nEXPERIMENTAL:');
+        console.log('  - Must exist in registry');
+        console.log('  - Must have at least 1 test matrix entry');
+        console.log('\nPARTIAL:');
+        console.log('  - All EXPERIMENTAL requirements');
+        console.log('  - Must have at least 1 realistic fixture mapping');
+        console.log('  - Must have documentation');
+        console.log('\nSTABLE:');
+        console.log('  - All PARTIAL requirements');
+        console.log('  - Must have determinism test coverage');
+        console.log('  - Must have artifact assertions in test matrix');
+        console.log('  - Must have guardrails coverage (if category requires it)');
+      }
+    } else {
+      console.log('\n✅ All capabilities meet their required gates!');
+    }
+    
+    console.log('='.repeat(80) + '\n');
+  }
+  
+  // Exit code: 0 if PASS, 2 if FAIL
+  if (!result.pass) {
+    process.exit(2);
+  }
+}
+

package/src/cli/commands/inspect.js

@@ -1,13 +1,41 @@
-import { resolve } from 'path';
+import { resolve, dirname, basename } from 'path';
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { DataError } from '../util/errors.js';
+import { displayPerformanceInInspect } from '../../verax/core/perf/perf.display.js';
+import { loadRunTimeline } from '../../verax/core/observe/run-timeline.js';
+import { loadDecisionTrace } from '../../verax/core/decisions/decision.trace.js';
+import { loadCrossIndex } from '../../verax/core/report/cross-index.js';
+import { generateHumanSummary, formatHumanSummary } from '../../verax/core/report/human-summary.js';
+
+/**
+ * Extract runId from runPath
+ */
+function extractRunId(runPath) {
+  const fullPath = resolve(runPath);
+  const runDirBasename = basename(fullPath);
+  const parentDir = basename(dirname(fullPath));
+  
+  // Check if path is .verax/runs/<runId>
+  if (parentDir === 'runs') {
+    return runDirBasename;
+  }
+  
+  return runDirBasename;
+}
 
 /**
  * `verax inspect` command
  * Read an existing run folder and display summary
  */
 export async function inspectCommand(runPath, options = {}) {
-  const { json = false } = options;
+  const { 
+    json = false,
+    timeline = false,
+    decisions = false,
+    failures = false,
+    performance = false,
+    evidence = false
+  } = options;
   
   const fullPath = resolve(runPath);
   
@@ -102,7 +130,108 @@ export async function inspectCommand(runPath, options = {}) {
       console.log(`Evidence: not found`);
     }
     
+  // PHASE 21.9: Display performance metrics
+  const runId = output.runId;
+  const projectDir = resolve(process.cwd());
+  
+  // PHASE 21.10: Handle specific flags
+  if (timeline) {
+    const timelineData = loadRunTimeline(projectDir, runId);
+    if (timelineData) {
+      if (json) {
+        console.log(JSON.stringify(timelineData, null, 2));
+      } else {
+        console.log('\n=== Timeline ===\n');
+        for (const event of timelineData.events) {
+          console.log(`${event.timestamp || 'N/A'} [${event.phase}] ${event.event}`);
+          if (event.data) {
+            console.log(`  ${JSON.stringify(event.data)}`);
+          }
+        }
+        console.log('');
+      }
+      return output;
+    }
+  }
+  
+  if (decisions) {
+    const decisionTrace = loadDecisionTrace(projectDir, runId);
+    if (decisionTrace) {
+      if (json) {
+        console.log(JSON.stringify(decisionTrace, null, 2));
+      } else {
+        console.log('\n=== Decision Trace ===\n');
+        for (const trace of decisionTrace.findings) {
+          console.log(`Finding: ${trace.findingId}`);
+          console.log(`  Status: ${trace.status.value}`);
+          console.log(`  Confidence: ${trace.confidence.level || 'UNKNOWN'}`);
+          console.log(`  Why detected: ${trace.detection.why.map(w => w.reason).join('; ')}`);
+          console.log(`  Why status: ${trace.status.why.map(w => w.reason).join('; ')}`);
+          console.log('');
+        }
+      }
+      return output;
+    }
+  }
+  
+  if (failures) {
+    const failureLedgerPath = resolve(fullPath, 'failure.ledger.json');
+    if (existsSync(failureLedgerPath)) {
+      const failureLedger = JSON.parse(readFileSync(failureLedgerPath, 'utf-8'));
+      if (json) {
+        console.log(JSON.stringify(failureLedger, null, 2));
+      } else {
+        console.log('\n=== Failures ===\n');
+        console.log(`Total: ${failureLedger.summary?.total || 0}`);
+        if (failureLedger.failures) {
+          for (const failure of failureLedger.failures) {
+            console.log(`[${failure.severity || 'UNKNOWN'}] ${failure.code}: ${failure.message}`);
+          }
+        }
+        console.log('');
+      }
+      return output;
+    }
+  }
+  
+  if (performance) {
+    displayPerformanceInInspect(projectDir, runId);
     console.log('');
+    return output;
+  }
+  
+  if (evidence) {
+    const crossIndex = loadCrossIndex(projectDir, runId);
+    if (crossIndex) {
+      if (json) {
+        console.log(JSON.stringify(crossIndex, null, 2));
+      } else {
+        console.log('\n=== Evidence Cross-Index ===\n');
+        for (const [findingId, entry] of Object.entries(crossIndex.findings)) {
+          console.log(`Finding: ${findingId}`);
+          console.log(`  Evidence files: ${entry.evidence.files.length}`);
+          console.log(`  Evidence complete: ${entry.evidence.isComplete}`);
+          console.log(`  Confidence: ${entry.confidence.level || 'UNKNOWN'}`);
+          console.log(`  Guardrails: ${entry.guardrails.applied.length} rule(s) applied`);
+          console.log('');
+        }
+      }
+      return output;
+    }
+  }
+  
+  // Default: show summary + human summary
+  displayPerformanceInInspect(projectDir, runId);
+  
+  // PHASE 21.10: Display human summary
+  const humanSummary = await generateHumanSummary(projectDir, runId);
+  if (humanSummary && !json) {
+    console.log(formatHumanSummary(humanSummary));
+  } else if (humanSummary && json) {
+    output.humanSummary = humanSummary;
+  }
+  
+  console.log('');
   }
   
   return output;

package/src/cli/commands/release-check.js

@@ -0,0 +1,213 @@
+/**
+ * PHASE 21.7 — Release Check CLI Command
+ * 
+ * Checks release readiness: GA status, Provenance, SBOM, Reproducibility.
+ * Exit codes: 0 = RELEASE-READY, 5 = RELEASE-BLOCKED, 70 = Internal corruption
+ */
+
+import { buildProvenance, writeProvenance } from '../../verax/core/release/provenance.builder.js';
+import { buildSBOM, writeSBOM } from '../../verax/core/release/sbom.builder.js';
+import { checkReproducibility, writeReproducibilityReport } from '../../verax/core/release/reproducibility.check.js';
+import { checkGAStatus } from '../../verax/core/ga/ga.enforcer.js';
+import { writeReleaseReport } from '../../verax/core/release/release-report-writer.js';
+import { findLatestRunId } from '../util/run-resolver.js';
+import { resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+/**
+ * Check release readiness
+ * 
+ * @param {Object} options - Options
+ * @param {boolean} [options.json] - Output as JSON
+ */
+export async function releaseCheckCommand(options = {}) {
+  const { json = false } = options;
+  const projectDir = resolve(process.cwd());
+  
+  const status = {
+    ga: { ok: false, status: 'UNKNOWN', blockers: [] },
+    provenance: { ok: false, exists: false, blockers: [] },
+    sbom: { ok: false, exists: false, blockers: [] },
+    reproducibility: { ok: false, verdict: 'UNKNOWN', blockers: [] }
+  };
+  
+  // 1. Check GA status
+  try {
+    const runId = findLatestRunId(projectDir);
+    if (runId) {
+      const gaCheck = checkGAStatus(projectDir, runId);
+      status.ga.ok = gaCheck.ready;
+      status.ga.status = gaCheck.ready ? 'GA-READY' : 'GA-BLOCKED';
+      if (!gaCheck.ready && gaCheck.status?.blockers) {
+        status.ga.blockers = gaCheck.status.blockers.map(b => b.message);
+      }
+    } else {
+      status.ga.blockers.push('No runs found. Run a scan first.');
+    }
+  } catch (error) {
+    status.ga.blockers.push(`GA check failed: ${error.message}`);
+  }
+  
+  // 2. Check Provenance
+  try {
+    const provenancePath = resolve(projectDir, 'release', 'release.provenance.json');
+    if (existsSync(provenancePath)) {
+      status.provenance.exists = true;
+      const provenance = JSON.parse(readFileSync(provenancePath, 'utf-8'));
+      
+      // Validate provenance structure
+      if (!provenance.version || !provenance.git || !provenance.env) {
+        status.provenance.blockers.push('Invalid provenance structure');
+      } else if (provenance.git.dirty) {
+        status.provenance.blockers.push('Provenance indicates dirty git repository');
+      } else if (provenance.gaStatus !== 'GA-READY') {
+        status.provenance.blockers.push(`GA status is ${provenance.gaStatus}, not GA-READY`);
+      } else {
+        status.provenance.ok = true;
+      }
+    } else {
+      // Try to build it
+      try {
+        const provenance = await buildProvenance(projectDir);
+        writeProvenance(projectDir, provenance);
+        status.provenance.exists = true;
+        status.provenance.ok = true;
+      } catch (error) {
+        status.provenance.blockers.push(`Cannot build provenance: ${error.message}`);
+      }
+    }
+  } catch (error) {
+    status.provenance.blockers.push(`Provenance check failed: ${error.message}`);
+  }
+  
+  // 3. Check SBOM
+  try {
+    const sbomPath = resolve(projectDir, 'release', 'sbom.json');
+    if (existsSync(sbomPath)) {
+      status.sbom.exists = true;
+      const sbom = JSON.parse(readFileSync(sbomPath, 'utf-8'));
+      
+      // Validate SBOM structure
+      if (!sbom.bomFormat || !sbom.components || !Array.isArray(sbom.components)) {
+        status.sbom.blockers.push('Invalid SBOM structure');
+      } else if (sbom.components.length === 0) {
+        status.sbom.blockers.push('SBOM has no components');
+      } else {
+        status.sbom.ok = true;
+      }
+    } else {
+      // Try to build it
+      try {
+        const sbom = await buildSBOM(projectDir);
+        writeSBOM(projectDir, sbom);
+        status.sbom.exists = true;
+        status.sbom.ok = true;
+      } catch (error) {
+        status.sbom.blockers.push(`Cannot build SBOM: ${error.message}`);
+      }
+    }
+  } catch (error) {
+    status.sbom.blockers.push(`SBOM check failed: ${error.message}`);
+  }
+  
+  // 4. Check Reproducibility
+  try {
+    const report = await checkReproducibility(projectDir);
+    writeReproducibilityReport(projectDir, report);
+    
+    if (report.verdict === 'REPRODUCIBLE') {
+      status.reproducibility.ok = true;
+      status.reproducibility.verdict = 'REPRODUCIBLE';
+    } else {
+      status.reproducibility.verdict = 'NON_REPRODUCIBLE';
+      if (report.differences && report.differences.length > 0) {
+        status.reproducibility.blockers = report.differences.map(d => d.message);
+      } else {
+        status.reproducibility.blockers.push('Build is not reproducible');
+      }
+    }
+  } catch (error) {
+    status.reproducibility.blockers.push(`Reproducibility check failed: ${error.message}`);
+  }
+  
+  // Determine overall status
+  const allOk = status.ga.ok && status.provenance.ok && status.sbom.ok && status.reproducibility.ok;
+  const hasInternalCorruption = 
+    status.ga.blockers.some(b => b.includes('corruption') || b.includes('INTERNAL')) ||
+    status.provenance.blockers.some(b => b.includes('corruption')) ||
+    status.sbom.blockers.some(b => b.includes('corruption'));
+  
+  // Write release report
+  const releaseStatus = {
+    releaseReady: allOk,
+    status,
+    summary: {
+      ga: status.ga.ok ? 'OK' : 'BLOCKED',
+      provenance: status.provenance.ok ? 'OK' : 'BLOCKED',
+      sbom: status.sbom.ok ? 'OK' : 'BLOCKED',
+      reproducibility: status.reproducibility.ok ? 'OK' : 'BLOCKED'
+    }
+  };
+  const releaseReportPath = writeReleaseReport(projectDir, releaseStatus);
+  
+  // Output
+  if (json) {
+    console.log(JSON.stringify({
+      releaseReady: allOk,
+      status,
+      summary: {
+        ga: status.ga.ok ? 'OK' : 'BLOCKED',
+        provenance: status.provenance.ok ? 'OK' : 'BLOCKED',
+        sbom: status.sbom.ok ? 'OK' : 'BLOCKED',
+        reproducibility: status.reproducibility.ok ? 'OK' : 'BLOCKED'
+      },
+      reportPath: releaseReportPath
+    }, null, 2));
+  } else {
+    console.log('\n' + '='.repeat(80));
+    console.log('RELEASE READINESS CHECK');
+    console.log('='.repeat(80));
+    
+    console.log(`\nGA Status: ${status.ga.ok ? '✅ READY' : '❌ BLOCKED'}`);
+    if (status.ga.blockers.length > 0) {
+      for (const blocker of status.ga.blockers) {
+        console.log(`  - ${blocker}`);
+      }
+    }
+    
+    console.log(`\nProvenance: ${status.provenance.ok ? '✅ OK' : '❌ BLOCKED'}`);
+    if (status.provenance.blockers.length > 0) {
+      for (const blocker of status.provenance.blockers) {
+        console.log(`  - ${blocker}`);
+      }
+    }
+    
+    console.log(`\nSBOM: ${status.sbom.ok ? '✅ OK' : '❌ BLOCKED'}`);
+    if (status.sbom.blockers.length > 0) {
+      for (const blocker of status.sbom.blockers) {
+        console.log(`  - ${blocker}`);
+      }
+    }
+    
+    console.log(`\nReproducibility: ${status.reproducibility.ok ? '✅ REPRODUCIBLE' : '❌ NON_REPRODUCIBLE'}`);
+    if (status.reproducibility.blockers.length > 0) {
+      for (const blocker of status.reproducibility.blockers) {
+        console.log(`  - ${blocker}`);
+      }
+    }
+    
+    console.log(`\nOverall: ${allOk ? '✅ RELEASE-READY' : '❌ RELEASE-BLOCKED'}`);
+    console.log(`\nSee report: ${releaseReportPath}`);
+    console.log('='.repeat(80) + '\n');
+  }
+  
+  // Exit codes: 0 = RELEASE-READY, 2 = RELEASE-BLOCKED, 70 = Internal corruption
+  if (allOk) {
+    process.exit(0);
+  } else if (hasInternalCorruption) {
+    process.exit(70);
+  } else {
+    process.exit(2);
+  }
+}
+