@veraxhq/verax 0.2.1 → 0.3.0

package/src/cli/util/findings-writer.js

@@ -1,32 +1,142 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
 import { findingIdFromExpectationId } from './idgen.js';
+import {
+  enforceContractsOnFindings,
+  FINDING_STATUS,
+  CONFIDENCE_LEVEL,
+  IMPACT,
+  USER_RISK,
+  OWNERSHIP,
+} from '../../verax/core/contracts/index.js';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from '../../verax/core/artifacts/registry.js';
 
 /**
- * Write findings.json artifact with deterministic IDs
+ * Write findings.json artifact with deterministic IDs and contract enforcement
  */
 export function writeFindingsJson(runDir, findingsData) {
-  const findingsPath = resolve(runDir, 'findings.json');
-  
-  // Add deterministic finding IDs based on expectation IDs
-  const findingsWithIds = (findingsData.findings || []).map(finding => ({
+  const findingsPath = resolve(runDir, ARTIFACT_REGISTRY.findings.filename);
+  const normalizedFindings = normalizeFindings(findingsData?.findings || []);
+  const enforcement = enforceContractsOnFindings(normalizedFindings);
+
+  const findingsWithIds = enforcement.valid.map((finding) => ({
     ...finding,
-    findingId: findingIdFromExpectationId(finding.id),
+    findingId: findingIdFromExpectationId(finding.id || finding.expectationId || ''),
   }));
-  
+
+  const stats = findingsData?.stats || {};
   const payload = {
+    contractVersion: 1,
+    artifactVersions: getArtifactVersions(),
     findings: findingsWithIds,
-    total: findingsData.stats?.total || 0,
+    total: findingsWithIds.length,
     stats: {
-      total: findingsData.stats?.total || 0,
-      silentFailures: findingsData.stats?.silentFailures || 0,
-      observed: findingsData.stats?.observed || 0,
-      coverageGaps: findingsData.stats?.coverageGaps || 0,
-      unproven: findingsData.stats?.unproven || 0,
-      informational: findingsData.stats?.informational || 0,
+      total: findingsWithIds.length,
+      silentFailures: stats.silentFailures || 0,
+      observed: stats.observed || 0,
+      coverageGaps: stats.coverageGaps || 0,
+      unproven: stats.unproven || 0,
+      informational: stats.informational || 0,
+    },
+    detectedAt: findingsData?.detectedAt || new Date().toISOString(),
+    enforcement: {
+      droppedCount: enforcement.dropped.length,
+      downgradedCount: enforcement.downgrades.length,
+      downgrades: enforcement.downgrades.map((entry) => ({
+        reason: entry.reason,
+        originalStatus: entry.original?.status,
+        downgradeToStatus: entry.downgraded?.status,
+      })),
+      dropped: enforcement.dropped.map((entry) => ({
+        reason: entry.reason,
+      })),
     },
-    detectedAt: findingsData.detectedAt || new Date().toISOString(),
   };
-  
+
   atomicWriteJson(findingsPath, payload);
+  return { path: findingsPath, payload };
+}
+
+function normalizeFindings(findings) {
+  return findings.map((finding) => normalizeFinding(finding));
+}
+
+function normalizeFinding(finding) {
+  const status = finding.status || mapClassificationToStatus(finding.classification);
+  const evidence = normalizeEvidence(finding.evidence);
+  const confidence = normalizeConfidence(finding.confidence);
+  const signals = normalizeSignals(finding);
+  const interaction = finding.interaction || {
+    type: finding.type || 'unknown',
+    selector: finding.promise?.selector || finding.promise?.value || finding.source?.file || 'unknown',
+  };
+
+  return {
+    ...finding,
+    status,
+    evidence,
+    confidence,
+    signals,
+    interaction,
+    what_happened: finding.what_happened || finding.reason || 'Expectation was exercised during scan.',
+    what_was_expected: finding.what_was_expected || finding.promise?.value || 'Expectation derived from source code.',
+    what_was_observed: finding.what_was_observed || finding.reason || 'Observation recorded for expectation.',
+    why_it_matters: finding.why_it_matters || 'Potential silent failure identified by expectation vs observation.',
+  };
+}
+
+function mapClassificationToStatus(classification) {
+  if (classification === 'observed') return FINDING_STATUS.CONFIRMED;
+  if (classification === 'silent-failure') return FINDING_STATUS.SUSPECTED;
+  if (classification === 'coverage-gap' || classification === 'unproven') return FINDING_STATUS.SUSPECTED;
+  return FINDING_STATUS.INFORMATIONAL;
+}
+
+function normalizeConfidence(confidence) {
+  if (confidence && typeof confidence === 'object' && confidence.level && confidence.score !== undefined) {
+    return confidence;
+  }
+
+  const numeric = typeof confidence === 'number' ? Math.max(0, Math.min(1, confidence)) : 0;
+  const score = Math.round(numeric * 100);
+  let level = CONFIDENCE_LEVEL.UNPROVEN;
+  if (score >= 80) level = CONFIDENCE_LEVEL.HIGH;
+  else if (score >= 60) level = CONFIDENCE_LEVEL.MEDIUM;
+  else if (score > 0) level = CONFIDENCE_LEVEL.LOW;
+
+  return { level, score };
+}
+
+function normalizeEvidence(evidenceArray) {
+  const items = Array.isArray(evidenceArray) ? evidenceArray : [];
+  const hasNetworkActivity = items.some((item) => item?.type === 'network-log');
+  const hasDomChange = items.some((item) => item?.type === 'screenshot');
+
+  return {
+    type: hasNetworkActivity ? 'network_activity' : undefined,
+    hasDomChange,
+    hasUrlChange: false,
+    hasNetworkActivity,
+    hasStateChange: false,
+    networkRequests: items.filter((item) => item?.type === 'network-log'),
+    before: items.find((item) => item?.type === 'screenshot')?.path,
+    after: undefined,
+  };
+}
+
+function normalizeSignals(finding) {
+  if (finding.signals && typeof finding.signals === 'object') {
+    return finding.signals;
+  }
+
+  const impact = (finding.impact && IMPACT[finding.impact]) ? finding.impact : IMPACT.MEDIUM;
+
+  return {
+    impact,
+    userRisk: USER_RISK.CONFUSES,
+    ownership: OWNERSHIP.FRONTEND,
+    grouping: {
+      expectationType: finding.type || 'unknown',
+    },
+  };
 }

package/src/cli/util/learn-writer.js

@@ -1,18 +1,20 @@
 import { resolve } from 'path';
 import { atomicWriteJson } from './atomic-write.js';
 import { compareExpectations } from './idgen.js';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write learn.json artifact
  * Maintains deterministic ordering for stable output
  */
 export function writeLearnJson(runPaths, expectations, skipped) {
-  const learnJsonPath = resolve(runPaths.baseDir, 'learn.json');
+  const learnJsonPath = resolve(runPaths.baseDir, ARTIFACT_REGISTRY.learn.filename);
   
   // Sort expectations deterministically for stable output
   const sortedExpectations = [...expectations].sort(compareExpectations);
   
   const learnJson = {
+    contractVersion: 1,
     expectations: sortedExpectations,
     stats: {
       totalExpectations: sortedExpectations.length,

package/src/cli/util/observe-writer.js

@@ -1,13 +1,15 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write observe.json artifact
  */
 export function writeObserveJson(runDir, observeData) {
-  const observePath = resolve(runDir, 'observe.json');
+  const observePath = resolve(runDir, ARTIFACT_REGISTRY.observe.filename);
   
   const payload = {
+    contractVersion: 1,
     observations: observeData.observations || [],
     stats: {
       attempted: observeData.stats?.attempted || 0,

package/src/cli/util/paths.js

@@ -1,5 +1,6 @@
 import { join, isAbsolute } from 'path';
 import { mkdirSync } from 'fs';
+import { buildRunArtifactPaths } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Build run artifact paths
@@ -7,18 +8,8 @@ import { mkdirSync } from 'fs';
 export function getRunPaths(projectRoot, outDir, runId) {
   const outBase = isAbsolute(outDir) ? outDir : join(projectRoot, outDir);
   const baseDir = join(outBase, 'runs', runId);
-  
-  return {
-    baseDir,
-    runStatusJson: join(baseDir, 'run.status.json'),
-    runMetaJson: join(baseDir, 'run.meta.json'),
-    summaryJson: join(baseDir, 'summary.json'),
-    findingsJson: join(baseDir, 'findings.json'),
-    tracesJsonl: join(baseDir, 'traces.jsonl'),
-    evidenceDir: join(baseDir, 'evidence'),
-    learnJson: join(baseDir, 'learn.json'),
-    observeJson: join(baseDir, 'observe.json'),
-  };
+
+  return buildRunArtifactPaths(baseDir);
 }
 
 /**

package/src/cli/util/project-discovery.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { resolve, dirname } from 'path';
+import { assertExecutionBootstrapAllowed } from './bootstrap-guard.js';
 
 /**
  * Project Discovery Module
@@ -21,6 +22,8 @@ import { resolve, dirname } from 'path';
  * @returns {Promise<ProjectProfile>}
  */
 export async function discoverProject(srcPath) {
+  // PHASE 21.6.1: Runtime guard - crash if called during inspection
+  assertExecutionBootstrapAllowed('discoverProject');
   const projectRoot = resolve(srcPath);
   
   // Find the nearest package.json

package/src/cli/util/project-writer.js

@@ -1,13 +1,15 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write project profile artifact
  */
 export function writeProjectJson(runPaths, projectProfile) {
-  const projectJsonPath = resolve(runPaths.baseDir, 'project.json');
+  const projectJsonPath = resolve(runPaths.baseDir, ARTIFACT_REGISTRY.project.filename);
   
   const projectJson = {
+    contractVersion: 1,
     framework: projectProfile.framework,
     router: projectProfile.router,
     sourceRoot: projectProfile.sourceRoot,

package/src/cli/util/run-resolver.js

@@ -0,0 +1,64 @@
+/**
+ * PHASE 21.6.1 — Run Resolver
+ * 
+ * Pure filesystem logic to resolve run IDs.
+ * No side effects, no execution dependencies.
+ */
+
+import { readdirSync, statSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Find the latest run ID from .verax/runs/
+ * 
+ * @param {string} projectDir - Project directory
+ * @returns {string|null} Latest run ID or null if no runs found
+ */
+export function findLatestRunId(projectDir) {
+  const runsDir = resolve(projectDir, '.verax', 'runs');
+  
+  if (!existsSync(runsDir)) {
+    return null;
+  }
+  
+  try {
+    const runs = readdirSync(runsDir, { withFileTypes: true })
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => {
+        const runPath = resolve(runsDir, dirent.name);
+        try {
+          const stats = statSync(runPath);
+          return {
+            name: dirent.name,
+            mtimeMs: stats.mtimeMs
+          };
+        } catch {
+          return null;
+        }
+      })
+      .filter(run => run !== null);
+    
+    if (runs.length === 0) {
+      return null;
+    }
+    
+    // Sort by modification time (descending) and return latest
+    runs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return runs[0].name;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Validate that a run ID exists
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID to validate
+ * @returns {boolean} Whether run exists
+ */
+export function validateRunId(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  return existsSync(runDir);
+}
+

package/src/cli/util/source-requirement.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, statSync } from 'fs';
+import { extname, join, resolve } from 'path';
+import { DataError } from './errors.js';
+import { getSourceCodeRequirementBanner } from '../../verax/core/product-definition.js';
+
+const CODE_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.html']);
+
+function safeReaddir(dirPath) {
+  try {
+    return readdirSync(dirPath);
+  } catch {
+    return [];
+  }
+}
+
+function directoryHasCode(dirPath) {
+  const entries = safeReaddir(dirPath);
+  for (const entry of entries) {
+    const fullPath = join(dirPath, entry);
+    let stats;
+    try {
+      stats = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stats.isFile() && CODE_EXTS.has(extname(entry).toLowerCase())) {
+      return true;
+    }
+
+    if (stats.isDirectory() && (entry === 'src' || entry === 'app')) {
+      const nested = safeReaddir(fullPath).slice(0, 50);
+      if (nested.some((name) => CODE_EXTS.has(extname(name).toLowerCase()))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function assertHasLocalSource(srcPath) {
+  const resolved = resolve(srcPath);
+  const hasPackageJson = existsSync(join(resolved, 'package.json'));
+  const hasIndexHtml = existsSync(join(resolved, 'index.html'));
+  const hasCodeFiles = directoryHasCode(resolved);
+
+  if (!hasPackageJson && !hasIndexHtml && !hasCodeFiles) {
+    const banner = getSourceCodeRequirementBanner();
+    throw new DataError(
+      `${banner} Provide --src pointing to your repository so VERAX can analyze expectations. See docs/README.md for the canonical product contract.`
+    );
+  }
+
+  return { hasPackageJson, hasIndexHtml, hasCodeFiles };
+}

package/src/cli/util/summary-writer.js

@@ -7,6 +7,7 @@ import { atomicWriteJson } from './atomic-write.js';
  */
 export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
   const payload = {
+    contractVersion: 1,
     runId: summaryData.runId,
     status: summaryData.status,
     startedAt: summaryData.startedAt,

package/src/cli/util/svelte-navigation-detector.js

@@ -0,0 +1,163 @@
+/**
+ * PHASE 20 — Svelte Navigation Detector
+ * 
+ * Detects navigation promises in Svelte applications:
+ * - <a href="/path"> links
+ * - goto() calls from SvelteKit
+ * - programmatic navigation
+ */
+
+import { extractSvelteSFC, extractTemplateBindings, mapTemplateHandlersToScript } from './svelte-sfc-extractor.js';
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+
+/**
+ * Detect navigation promises in Svelte SFC
+ * 
+ * @param {string} filePath - Path to .svelte file
+ * @param {string} content - Full file content
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array} Array of navigation expectations
+ */
+export function detectSvelteNavigation(filePath, content, projectRoot) {
+  const expectations = [];
+  
+  try {
+    const sfc = extractSvelteSFC(content);
+    const { scriptBlocks, markup } = sfc;
+    
+    // Extract navigation from markup (links)
+    if (markup && markup.content) {
+      const linkRegex = /<a\s+[^>]*href=["']([^"']+)["'][^>]*>/gi;
+      let linkMatch;
+      while ((linkMatch = linkRegex.exec(markup.content)) !== null) {
+        const href = linkMatch[1];
+        // Skip external links and hash-only links
+        if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('#')) {
+          continue;
+        }
+        
+        const beforeMatch = markup.content.substring(0, linkMatch.index);
+        const line = markup.startLine + (beforeMatch.match(/\n/g) || []).length;
+        
+        expectations.push({
+          type: 'navigation',
+          target: href,
+          context: 'markup',
+          sourceRef: {
+            file: filePath,
+            line,
+            snippet: linkMatch[0],
+          },
+          proof: 'PROVEN_EXPECTATION',
+          metadata: {
+            navigationType: 'link',
+          },
+        });
+      }
+    }
+    
+    // Extract navigation from script blocks (goto, navigate, etc.)
+    for (const scriptBlock of scriptBlocks) {
+      if (!scriptBlock.content) continue;
+      
+      try {
+        const ast = parse(scriptBlock.content, {
+          sourceType: 'module',
+          plugins: ['typescript', 'jsx'],
+        });
+        
+        traverse.default(ast, {
+          CallExpression(path) {
+            const { node } = path;
+            
+            // Detect goto() calls (SvelteKit)
+            if (
+              node.callee.type === 'Identifier' &&
+              node.callee.name === 'goto' &&
+              node.arguments.length > 0
+            ) {
+              const arg = node.arguments[0];
+              let target = null;
+              
+              if (arg.type === 'StringLiteral') {
+                target = arg.value;
+              } else if (arg.type === 'TemplateLiteral' && arg.quasis.length === 1) {
+                target = arg.quasis[0].value.raw;
+              }
+              
+              if (target && !target.startsWith('http://') && !target.startsWith('https://') && !target.startsWith('#')) {
+                const location = node.loc;
+                const line = scriptBlock.startLine + (location ? location.start.line - 1 : 0);
+                
+                expectations.push({
+                  type: 'navigation',
+                  target,
+                  context: 'goto',
+                  sourceRef: {
+                    file: filePath,
+                    line,
+                    snippet: scriptBlock.content.substring(
+                      node.start - (ast.program.body[0]?.start || 0),
+                      node.end - (ast.program.body[0]?.start || 0)
+                    ),
+                  },
+                  proof: arg.type === 'StringLiteral' ? 'PROVEN_EXPECTATION' : 'LIKELY_EXPECTATION',
+                  metadata: {
+                    navigationType: 'goto',
+                  },
+                });
+              }
+            }
+            
+            // Detect navigate() calls (if imported)
+            if (
+              node.callee.type === 'MemberExpression' &&
+              node.callee.property.name === 'navigate' &&
+              node.arguments.length > 0
+            ) {
+              const arg = node.arguments[0];
+              let target = null;
+              
+              if (arg.type === 'StringLiteral') {
+                target = arg.value;
+              } else if (arg.type === 'TemplateLiteral' && arg.quasis.length === 1) {
+                target = arg.quasis[0].value.raw;
+              }
+              
+              if (target && !target.startsWith('http://') && !target.startsWith('https://') && !target.startsWith('#')) {
+                const location = node.loc;
+                const line = scriptBlock.startLine + (location ? location.start.line - 1 : 0);
+                
+                expectations.push({
+                  type: 'navigation',
+                  target,
+                  context: 'navigate',
+                  sourceRef: {
+                    file: filePath,
+                    line,
+                    snippet: scriptBlock.content.substring(
+                      node.start - (ast.program.body[0]?.start || 0),
+                      node.end - (ast.program.body[0]?.start || 0)
+                    ),
+                  },
+                  proof: arg.type === 'StringLiteral' ? 'PROVEN_EXPECTATION' : 'LIKELY_EXPECTATION',
+                  metadata: {
+                    navigationType: 'navigate',
+                  },
+                });
+              }
+            }
+          },
+        });
+      } catch (parseError) {
+        // Skip if parsing fails
+      }
+    }
+  } catch (error) {
+    // Skip if extraction fails
+  }
+  
+  return expectations;
+}
+

package/src/cli/util/svelte-network-detector.js

@@ -0,0 +1,80 @@
+/**
+ * PHASE 20 — Svelte Network Detector
+ * 
+ * Detects network calls (fetch, axios) in Svelte component handlers and lifecycle functions.
+ * Reuses AST network detector but ensures it works with Svelte SFC script blocks.
+ */
+
+import { extractSvelteSFC, extractTemplateBindings, mapTemplateHandlersToScript } from './svelte-sfc-extractor.js';
+import { detectNetworkCallsAST } from './ast-network-detector.js';
+import { relative } from 'path';
+
+/**
+ * Detect network promises in Svelte SFC
+ * 
+ * @param {string} filePath - Path to .svelte file
+ * @param {string} content - Full file content
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array} Array of network expectations
+ */
+export function detectSvelteNetwork(filePath, content, projectRoot) {
+  const expectations = [];
+  
+  try {
+    const sfc = extractSvelteSFC(content);
+    const { scriptBlocks, markup } = sfc;
+    
+    // Extract event handlers from markup to identify UI-bound handlers
+    const templateBindings = markup ? extractTemplateBindings(markup.content) : { eventHandlers: [] };
+    const mappedHandlers = scriptBlocks.length > 0 && templateBindings.eventHandlers.length > 0
+      ? mapTemplateHandlersToScript(templateBindings.eventHandlers, scriptBlocks[0].content)
+      : [];
+    
+    const uiBoundHandlers = new Set(mappedHandlers.map(h => h.handler));
+    
+    // Process each script block
+    for (const scriptBlock of scriptBlocks) {
+      if (!scriptBlock.content) continue;
+      
+      // Use AST network detector on script content
+      const networkCalls = detectNetworkCallsAST(scriptBlock.content, filePath, relative(projectRoot, filePath));
+      
+      // Filter and enhance network calls
+      for (const networkCall of networkCalls) {
+        // Check if this is in a UI-bound handler
+        const isUIBound = networkCall.context && uiBoundHandlers.has(networkCall.context);
+        
+        // Skip analytics-only calls (filtered by guardrails later)
+        if (networkCall.target && (
+          networkCall.target.includes('/api/analytics') ||
+          networkCall.target.includes('/api/track') ||
+          networkCall.target.includes('/api/beacon')
+        )) {
+          continue;
+        }
+        
+        expectations.push({
+          type: 'network',
+          target: networkCall.target,
+          method: networkCall.method || 'GET',
+          context: networkCall.context || 'component',
+          sourceRef: {
+            file: filePath,
+            line: networkCall.line || scriptBlock.startLine,
+            snippet: networkCall.snippet || '',
+          },
+          proof: networkCall.proof || 'LIKELY_EXPECTATION',
+          metadata: {
+            isUIBound,
+            handlerContext: networkCall.context,
+          },
+        });
+      }
+    }
+  } catch (error) {
+    // Skip if extraction fails
+  }
+  
+  return expectations;
+}
+