@veraxhq/verax 0.1.0

package/src/verax/observe/ui-signal-sensor.js

@@ -0,0 +1,197 @@
+/**
+ * WAVE 3: UI Signal Sensor
+ * Detects user-visible feedback signals: loading states, dialogs, error messages
+ * Conservative: only count signals with accessibility semantics or explicit attributes
+ */
+
+export class UISignalSensor {
+  /**
+   * Snapshot current UI signals on the page.
+   * Returns: { hasLoadingIndicator, hasDialog, buttonStateChanged, errorSignals, explanation }
+   */
+  async snapshot(page) {
+    const signals = await page.evaluate(() => {
+      const result = {
+        hasLoadingIndicator: false,
+        hasDialog: false,
+        hasErrorSignal: false,
+        hasStatusSignal: false,
+        hasLiveRegion: false,
+        disabledElements: [],
+        explanation: []
+      };
+
+      // Check for loading indicators with accessibility semantics
+      // aria-busy="true"
+      const ariaBusy = document.querySelector('[aria-busy="true"]');
+      if (ariaBusy) {
+        result.hasLoadingIndicator = true;
+        result.explanation.push('Found [aria-busy="true"]');
+      }
+
+      // [data-loading] or [aria-label] with "loading" text
+      const dataLoading = document.querySelector('[data-loading]');
+      if (dataLoading) {
+        result.hasLoadingIndicator = true;
+        result.explanation.push('Found [data-loading]');
+      }
+
+      // role=status or role=alert with aria-live
+      const statusRegions = document.querySelectorAll('[role="status"], [role="alert"]');
+      if (statusRegions.length > 0) {
+        result.hasStatusSignal = true;
+        result.explanation.push(`Found ${statusRegions.length} status/alert region(s)`);
+      }
+
+      // aria-live region
+      const liveRegions = document.querySelectorAll('[aria-live]');
+      if (liveRegions.length > 0) {
+        result.hasLiveRegion = true;
+        result.explanation.push(`Found ${liveRegions.length} aria-live region(s)`);
+      }
+
+      // Check for dialogs
+      const dialog = document.querySelector('[role="dialog"], [aria-modal="true"]');
+      if (dialog && dialog.offsetParent !== null) {
+        // offsetParent is null if element is hidden
+        result.hasDialog = true;
+        result.explanation.push('Found dialog/modal');
+      }
+
+      // Check for disabled/loading buttons
+      const disabledButtons = document.querySelectorAll('button[disabled], button[aria-busy="true"]');
+      disabledButtons.forEach((btn) => {
+        result.disabledElements.push({
+          type: 'button',
+          text: (btn.textContent || '').trim().slice(0, 50),
+          attributes: {
+            disabled: btn.hasAttribute('disabled'),
+            ariaBusy: btn.getAttribute('aria-busy'),
+            class: btn.className.slice(0, 100)
+          }
+        });
+      });
+
+      if (result.disabledElements.length > 0) {
+        result.explanation.push(
+          `Found ${result.disabledElements.length} disabled/loading button(s)`
+        );
+      }
+
+      // Check for error signals: aria-invalid visible elements
+      const invalidElements = document.querySelectorAll('[aria-invalid="true"]');
+      if (invalidElements.length > 0) {
+        result.hasErrorSignal = true;
+        result.explanation.push(`Found ${invalidElements.length} invalid element(s)`);
+      }
+
+      // Check for common error message patterns with accessibility attributes
+      const errorMessages = document.querySelectorAll(
+        '[role="alert"], [class*="error"], [class*="danger"]'
+      );
+      if (errorMessages.length > 0) {
+        for (const elem of errorMessages) {
+          const text = elem.textContent.trim().slice(0, 50);
+          if (text && (text.toLowerCase().includes('error') || text.toLowerCase().includes('fail'))) {
+            result.hasErrorSignal = true;
+            result.explanation.push(`Found error message: "${text}"`);
+            break;
+          }
+        }
+      }
+
+      return result;
+    });
+
+    return signals;
+  }
+
+  /**
+   * Compute diff between two snapshots.
+   * Returns: { changed: boolean, explanation: string[], summary: {...} }
+   */
+  diff(before, after) {
+    const result = {
+      changed: false,
+      explanation: [],
+      summary: {
+        loadingStateChanged: before.hasLoadingIndicator !== after.hasLoadingIndicator,
+        dialogStateChanged: before.hasDialog !== after.hasDialog,
+        errorSignalChanged: before.hasErrorSignal !== after.hasErrorSignal,
+        statusSignalChanged: before.hasStatusSignal !== after.hasStatusSignal,
+        liveRegionStateChanged: before.hasLiveRegion !== after.hasLiveRegion,
+        disabledButtonsChanged: before.disabledElements.length !== after.disabledElements.length
+      }
+    };
+
+    // Check what changed
+    if (result.summary.loadingStateChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Loading indicator: ${before.hasLoadingIndicator} → ${after.hasLoadingIndicator}`
+      );
+    }
+
+    if (result.summary.dialogStateChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Dialog present: ${before.hasDialog} → ${after.hasDialog}`
+      );
+    }
+
+    if (result.summary.errorSignalChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Error signal: ${before.hasErrorSignal} → ${after.hasErrorSignal}`
+      );
+    }
+
+    if (result.summary.statusSignalChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Status signal: ${before.hasStatusSignal} → ${after.hasStatusSignal}`
+      );
+    }
+
+    if (result.summary.liveRegionStateChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Live region: ${before.hasLiveRegion} → ${after.hasLiveRegion}`
+      );
+    }
+
+    if (result.summary.disabledButtonsChanged) {
+      result.changed = true;
+      result.explanation.push(
+        `Disabled buttons: ${before.disabledElements.length} → ${after.disabledElements.length}`
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Check if any feedback signal is present.
+   */
+  hasAnyFeedback(signals) {
+    return (
+      signals.hasLoadingIndicator ||
+      signals.hasDialog ||
+      signals.hasErrorSignal ||
+      signals.hasStatusSignal ||
+      signals.hasLiveRegion ||
+      signals.disabledElements.length > 0
+    );
+  }
+
+  /**
+   * Check if any error/failure feedback is present.
+   */
+  hasErrorFeedback(signals) {
+    return (
+      signals.hasErrorSignal ||
+      signals.hasDialog || // Dialog might be error confirmation
+      (signals.hasStatusSignal && signals.explanation.some((ex) => ex.includes('error')))
+    );
+  }
+}

package/src/verax/resolve-workspace-root.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Determines if a path looks like the verax repository root
+ * (contains src/verax directory)
+ */
+function isVeraxRepoRoot(dir) {
+  try {
+    const veraxPath = join(dir, 'src', 'verax');
+    const indexPath = join(veraxPath, 'index.js');
+    return existsSync(indexPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detects project type by looking for marker files/directories
+ */
+function detectProjectMarker(dir) {
+  const markers = [
+    { file: 'package.json', check: (content) => {
+      try {
+        const pkg = JSON.parse(content);
+        if (pkg.private === false && pkg.homepage) return true;
+        if (pkg.scripts && pkg.scripts.start && (pkg.dependencies?.react || pkg.dependencies?.next)) return true;
+        if (pkg.scripts && pkg.scripts.dev) return true;
+        return !!pkg.name && pkg.name !== '@verax/verax';
+      } catch {
+        return false;
+      }
+    }},
+    { file: 'index.html', check: () => true },
+    { file: 'next.config.js', check: () => true },
+    { file: 'next.config.mjs', check: () => true },
+    { file: 'next.config.ts', check: () => true },
+    { file: 'vite.config.js', check: () => true },
+    { file: 'vite.config.ts', check: () => true },
+    { file: 'app.js', check: () => true },
+    { file: 'App.tsx', check: () => true },
+    { file: 'App.jsx', check: () => true },
+    { dir: 'src', check: () => true }
+  ];
+
+  for (const marker of markers) {
+    const markerPath = join(dir, marker.file || marker.dir);
+    if (existsSync(markerPath)) {
+      if (marker.file) {
+        try {
+          const content = readFileSync(markerPath, 'utf-8');
+          if (marker.check(content)) {
+            return true;
+          }
+        } catch {
+          // Continue if we can't read the file
+          continue;
+        }
+      } else {
+        // Directory marker
+        if (marker.check()) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Resolves the workspace root (project directory) for verax scanning.
+ *
+ * Priority:
+ * 1. If --project-dir is provided → use it (absolute path)
+ * 2. Else → auto-detect nearest parent directory containing project markers
+ * 3. If no project marker found and cwd is not repo root → return cwd
+ * 4. If no project marker found and cwd IS repo root → raise error
+ *
+ * @param {string} projectDirArg - The value of --project-dir if provided
+ * @param {string} currentWorkingDir - Current working directory (defaults to process.cwd())
+ * @returns {object} { workspaceRoot, autoDetected, isRepoRoot }
+ * @throws {Error} If unable to resolve a valid workspace root
+ */
+export function resolveWorkspaceRoot(projectDirArg = null, currentWorkingDir = process.cwd()) {
+  const cwd = resolve(currentWorkingDir);
+
+  // 1. If --project-dir is provided, use it
+  if (projectDirArg) {
+    const projectDir = resolve(projectDirArg);
+    if (!existsSync(projectDir)) {
+      throw new Error(`Project directory does not exist: ${projectDir}`);
+    }
+    return {
+      workspaceRoot: projectDir,
+      autoDetected: false,
+      isRepoRoot: isVeraxRepoRoot(projectDir)
+    };
+  }
+
+  // 2. Auto-detect: search upward from cwd for project markers
+  let searchDir = cwd;
+  const repoRootPath = isVeraxRepoRoot(cwd) ? cwd : null;
+
+  // Search upward from cwd, but stop at repo root if we find it
+  while (searchDir !== dirname(searchDir)) {
+    // If we detect a project marker, use this directory
+    if (detectProjectMarker(searchDir)) {
+      const isRepoRoot = isVeraxRepoRoot(searchDir);
+      
+      // CRITICAL GUARD: If this is the repo root AND we found a marker (e.g., shared test artifact),
+      // refuse to use repo root as workspace root
+      if (isRepoRoot && searchDir === repoRootPath) {
+        throw new Error(
+          'verax verax: Refusing to write artifacts in repository root. ' +
+          'Use --project-dir to specify the target project directory.'
+        );
+      }
+
+      return {
+        workspaceRoot: searchDir,
+        autoDetected: true,
+        isRepoRoot: false
+      };
+    }
+
+    searchDir = dirname(searchDir);
+
+    // If we hit the repo root during search, stop (don't use repo root implicitly)
+    if (isVeraxRepoRoot(searchDir) && searchDir !== cwd) {
+      break;
+    }
+  }
+
+  // 3. Fallback: if we found repo root in upward search, refuse it
+  if (isVeraxRepoRoot(cwd)) {
+    throw new Error(
+      'verax verax: Refusing to write artifacts in repository root. ' +
+      'Use --project-dir to specify the target project directory.'
+    );
+  }
+
+  // 4. Use cwd if no markers found (last resort for edge cases)
+  return {
+    workspaceRoot: cwd,
+    autoDetected: false,
+    isRepoRoot: false
+  };
+}
+
+/**
+ * Validates that an artifact path is within the workspace root
+ * @throws {Error} If artifact path is outside workspace root
+ */
+export function assertArtifactPathInWorkspace(artifactPath, workspaceRoot) {
+  const resolvedArtifact = resolve(artifactPath);
+  const resolvedWorkspace = resolve(workspaceRoot);
+
+  // Normalize paths for comparison
+  const artifactNorm = resolvedArtifact.replace(/\\/g, '/');
+  const workspaceNorm = resolvedWorkspace.replace(/\\/g, '/');
+
+  if (!artifactNorm.startsWith(workspaceNorm + '/') && artifactNorm !== workspaceNorm) {
+    throw new Error(
+      `verax verax: Artifact path outside workspace root.\n` +
+      `Workspace: ${workspaceRoot}\n` +
+      `Artifact: ${artifactPath}`
+    );
+  }
+}

package/src/verax/scan-summary-writer.js

@@ -0,0 +1,41 @@
+import { resolve } from 'path';
+import { writeFileSync, mkdirSync } from 'fs';
+
+export function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, artifactPaths = null) {
+  const summary = {
+    version: 1,
+    scannedAt: new Date().toISOString(),
+    url: url,
+    projectType: projectType,
+    truth: {
+      learn: learnTruth,
+      observe: observeTruth,
+      detect: detectTruth
+    },
+    paths: {
+      manifest: manifestPath,
+      traces: tracesPath,
+      findings: findingsPath
+    }
+  };
+  
+  let summaryPath;
+  if (artifactPaths) {
+    // Use new artifact structure
+    summaryPath = artifactPaths.summary;
+    // Write the scan summary with truth data
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
+  } else {
+    // Legacy structure
+    const scanDir = resolve(projectDir, '.veraxverax', 'scan');
+    mkdirSync(scanDir, { recursive: true });
+    summaryPath = resolve(scanDir, 'scan-summary.json');
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
+  }
+  
+  return {
+    ...summary,
+    summaryPath: summaryPath
+  };
+}
+

package/src/verax/shared/artifact-manager.js

@@ -0,0 +1,139 @@
+/**
+ * Wave 9 — Artifact Manager
+ *
+ * Manages the new artifact directory structure:
+ * .verax/runs/<runId>/
+ *   - summary.json (overall scan results, metrics)
+ *   - findings.json (all findings)
+ *   - traces.jsonl (one JSON per line, per interaction)
+ *   - evidence/ (screenshots, network logs, etc.)
+ *   - flows/ (flow diagrams if enabled)
+ *
+ * All artifacts are redacted before writing.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, appendFileSync } from 'fs';
+import { resolve, join } from 'path';
+import { randomBytes } from 'crypto';
+
+/**
+ * Generate a unique run ID.
+ * @returns {string} - 8-character hex ID
+ */
+export function generateRunId() {
+  return randomBytes(4).toString('hex');
+}
+
+/**
+ * Create artifact directory structure.
+ * @param {string} projectRoot - Project root directory
+ * @param {string} runId - Run identifier
+ * @returns {Object} - Paths to each artifact location
+ */
+export function initArtifactPaths(projectRoot, runId = null) {
+  const id = runId || generateRunId();
+  const runDir = resolve(projectRoot, '.verax', 'runs', id);
+
+  const paths = {
+    runId: id,
+    runDir,
+    summary: resolve(runDir, 'summary.json'),
+    findings: resolve(runDir, 'findings.json'),
+    traces: resolve(runDir, 'traces.jsonl'),
+    evidence: resolve(runDir, 'evidence'),
+    flows: resolve(runDir, 'flows'),
+    artifacts: resolve(projectRoot, '.verax', 'artifacts') // Legacy compat
+  };
+
+  // Create directories
+  [runDir, paths.evidence, paths.flows].forEach(dir => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  });
+
+  return paths;
+}
+
+/**
+ * Write summary.json with metadata and metrics.
+ * @param {Object} paths - Artifact paths from initArtifactPaths
+ * @param {Object} summary - Summary data { url, duration, findings, metrics }
+ */
+export function writeSummary(paths, summary) {
+  const data = {
+    runId: paths.runId,
+    timestamp: new Date().toISOString(),
+    url: summary.url,
+    projectRoot: summary.projectRoot,
+    metrics: summary.metrics || {
+      parseMs: 0,
+      resolveMs: 0,
+      observeMs: 0,
+      detectMs: 0,
+      totalMs: 0
+    },
+    findingsCounts: summary.findingsCounts || {
+      HIGH: 0,
+      MEDIUM: 0,
+      LOW: 0,
+      UNKNOWN: 0
+    },
+    topFindings: summary.topFindings || [],
+    cacheStats: summary.cacheStats || {}
+  };
+
+  writeFileSync(paths.summary, JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Write findings.json with all detected issues.
+ * @param {Object} paths - Artifact paths
+ * @param {Array} findings - Array of finding objects
+ */
+export function writeFindings(paths, findings) {
+  const data = {
+    runId: paths.runId,
+    timestamp: new Date().toISOString(),
+    total: findings.length,
+    findings
+  };
+
+  writeFileSync(paths.findings, JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Append a trace to traces.jsonl (one JSON object per line).
+ * @param {Object} paths - Artifact paths
+ * @param {Object} trace - Trace object to append
+ */
+export function appendTrace(paths, trace) {
+  const line = JSON.stringify(trace) + '\n';
+  appendFileSync(paths.traces, line);
+}
+
+/**
+ * Write evidence file (screenshot, network log, etc.).
+ * @param {Object} paths - Artifact paths
+ * @param {string} filename - Evidence filename
+ * @param {*} data - Data to write (string or buffer)
+ */
+export function writeEvidence(paths, filename, data) {
+  const filepath = resolve(paths.evidence, filename);
+  
+  if (typeof data === 'string') {
+    writeFileSync(filepath, data);
+  } else {
+    writeFileSync(filepath, data);
+  }
+}
+
+/**
+ * Get all artifact paths for a given run.
+ * @param {string} projectRoot - Project root
+ * @param {string} runId - Run identifier
+ * @returns {Object} - Paths object
+ */
+export function getArtifactPaths(projectRoot, runId) {
+  return initArtifactPaths(projectRoot, runId);
+}

package/src/verax/shared/caching.js

@@ -0,0 +1,104 @@
+/**
+ * Wave 9 — Performance Caching Layer
+ *
+ * Provides in-memory and optional disk caching for TS Program, symbol resolution,
+ * and AST extraction results. Deterministic cache keys based on file content hashes.
+ *
+ * Cache is keyed by: projectRoot + tsconfig path + file mtimes hash
+ * Entries are computed only once per unique key within a single run.
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { resolve, join } from 'path';
+
+const memoryCache = new Map(); // Global in-memory cache
+
+/**
+ * Compute a deterministic cache key from project root, tsconfig, and source files.
+ * @param {string} projectRoot - Project root directory
+ * @param {string} tsconfigPath - Path to tsconfig.json (optional)
+ * @param {Array<string>} sourceFiles - Array of source file paths
+ * @returns {string} - Deterministic cache key
+ */
+export function computeCacheKey(projectRoot, tsconfigPath, sourceFiles = []) {
+  const hash = createHash('sha256');
+
+  // Hash the project root
+  hash.update(projectRoot);
+
+  // Hash the tsconfig if present
+  if (tsconfigPath && existsSync(tsconfigPath)) {
+    try {
+      const tsconfigContent = readFileSync(tsconfigPath, 'utf-8');
+      hash.update(tsconfigContent);
+    } catch (e) {
+      // If tsconfig can't be read, just use the path
+      hash.update(tsconfigPath);
+    }
+  }
+
+  // Hash file modification times (more efficient than file content)
+  for (const filePath of sourceFiles) {
+    try {
+      if (existsSync(filePath)) {
+        const stats = statSync(filePath);
+        hash.update(filePath + ':' + stats.mtimeMs);
+      }
+    } catch (e) {
+      // Skip files that can't be stat'd
+    }
+  }
+
+  return hash.digest('hex').substring(0, 16); // Use first 16 chars for brevity
+}
+
+/**
+ * Get a value from cache. Calls computeFn if not cached.
+ * @param {string} key - Cache key
+ * @param {Function} computeFn - Function to compute value if not cached
+ * @returns {*} - Cached or computed value
+ */
+export function getOrCompute(key, computeFn) {
+  if (memoryCache.has(key)) {
+    return memoryCache.get(key);
+  }
+
+  const value = computeFn();
+  memoryCache.set(key, value);
+  return value;
+}
+
+/**
+ * Clear the in-memory cache (useful between test runs).
+ */
+export function clearCache() {
+  memoryCache.clear();
+}
+
+/**
+ * Get cache statistics (for diagnostics).
+ * @returns {Object} - { size, hitRate, entries }
+ */
+export function getCacheStats() {
+  return {
+    size: memoryCache.size,
+    keys: Array.from(memoryCache.keys()).slice(0, 5) // First 5 keys for inspection
+  };
+}
+
+/**
+ * Create a cache key specifically for TS Program resolution.
+ */
+export function getTSProgramCacheKey(rootDir, files) {
+  const tsconfigPath = resolve(rootDir, 'tsconfig.json');
+  return `ts-program:${computeCacheKey(rootDir, tsconfigPath, files)}`;
+}
+
+/**
+ * Create a cache key specifically for AST extraction.
+ */
+export function getASTCacheKey(projectDir, files) {
+  const tsconfigPath = resolve(projectDir, 'tsconfig.json');
+  return `ast:${computeCacheKey(projectDir, tsconfigPath, files)}`;
+}

package/src/verax/shared/expectation-proof.js

@@ -0,0 +1,4 @@
+export const ExpectationProof = {
+  PROVEN_EXPECTATION: 'PROVEN_EXPECTATION',
+  UNKNOWN_EXPECTATION: 'UNKNOWN_EXPECTATION'
+};