@veraxhq/verax 0.2.1 → 0.3.0

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

@@ -2,14 +2,30 @@
  * 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
+ * 
+ * CSS SPINNER DETECTION: Detects CSS-only loading indicators without semantic attributes
  */
 
+import {
+  isBorderSpinnerPattern,
+  isRotationAnimation,
+  isPulseAnimation,
+  isSpinnerSize,
+  isDecorativeElement,
+  CSS_SPINNER_REASON_CODES
+} from '../shared/css-spinner-rules.js';
+
 export class UISignalSensor {
   /**
    * Snapshot current UI signals on the page.
-   * Returns: { hasLoadingIndicator, hasDialog, buttonStateChanged, errorSignals, explanation }
+   * Returns: { hasLoadingIndicator, hasDialog, buttonStateChanged, errorSignals, explanation, cssSpinners }
+   * 
+   * @param {Object} page - Playwright page object
+   * @param {number} interactionTime - Optional: timestamp of interaction (for timing window)
+   * @param {Object} beforeSnapshot - Optional: snapshot before interaction (for correlation)
+   * @returns {Promise<Object>} UI signals snapshot
    */
-  async snapshot(page) {
+  async snapshot(page, interactionTime = null, beforeSnapshot = null) {
     const signals = await page.evaluate(() => {
       const result = {
         hasLoadingIndicator: false,
@@ -85,6 +101,136 @@ export class UISignalSensor {
         );
       }
 
+      // CSS SPINNER DETECTION: Detect CSS-only loading indicators
+      result.cssSpinners = [];
+      result.cssSpinnerDetected = false;
+      
+      const allElements = Array.from(document.querySelectorAll('*'));
+      const currentTime = Date.now();
+      const MAX_SPINNER_SIZE = 100;
+      const MIN_SPINNER_SIZE = 8;
+      const SPINNER_TIMING_WINDOW_MS = 2000;
+      
+      // Helper functions (inlined for browser context)
+      const isBorderSpinnerPattern = (style) => {
+        const borderWidth = parseFloat(style.borderWidth) || 0;
+        const borderTopWidth = parseFloat(style.borderTopWidth) || 0;
+        if (borderWidth < 2 && borderTopWidth < 2) return false;
+        
+        const borderColor = style.borderColor || '';
+        const borderTopColor = style.borderTopColor || '';
+        const hasDifferentTopColor = borderTopColor && borderColor && borderTopColor !== borderColor && borderTopColor !== 'rgba(0, 0, 0, 0)';
+        
+        const borderRadius = style.borderRadius || '';
+        const isCircular = borderRadius.includes('50%') || borderRadius.includes('999') || parseFloat(borderRadius) > 20;
+        
+        return hasDifferentTopColor && isCircular;
+      };
+      
+      const isRotationAnimation = (style) => {
+        const animationName = (style.animationName || '').toLowerCase();
+        const animation = (style.animation || '').toLowerCase();
+        const transform = style.transform || '';
+        const animationDuration = style.animationDuration || '';
+        
+        const spinnerKeywords = ['spin', 'rotate', 'loading', 'loader'];
+        const hasSpinnerKeyword = spinnerKeywords.some(k => animationName.includes(k) || animation.includes(k));
+        const hasRotation = transform.includes('rotate');
+        const isAnimated = animationDuration && animationDuration !== '0s' && !animationDuration.includes('none');
+        
+        return (hasRotation || hasSpinnerKeyword) && isAnimated;
+      };
+      
+      const isPulseAnimation = (style) => {
+        const animationName = (style.animationName || '').toLowerCase();
+        const animation = (style.animation || '').toLowerCase();
+        const animationDuration = style.animationDuration || '';
+        const opacity = parseFloat(style.opacity) || 1;
+        
+        const pulseKeywords = ['pulse', 'fade', 'loading'];
+        const hasPulseKeyword = pulseKeywords.some(k => animationName.includes(k) || animation.includes(k));
+        const isAnimated = animationDuration && animationDuration !== '0s' && !animationDuration.includes('none');
+        const hasOpacityVariation = opacity < 1;
+        
+        return hasPulseKeyword && isAnimated && hasOpacityVariation;
+      };
+      
+      const isSpinnerSize = (width, height) => {
+        const maxDim = Math.max(width, height);
+        const minDim = Math.min(width, height);
+        if (maxDim > MAX_SPINNER_SIZE || minDim < MIN_SPINNER_SIZE) return false;
+        const aspectRatio = maxDim / (minDim || 1);
+        return aspectRatio <= 2.0;
+      };
+      
+      for (const el of allElements) {
+        const style = window.getComputedStyle(el);
+        // @ts-expect-error
+        if (el.offsetParent === null || style.visibility === 'hidden' || style.display === 'none' || style.opacity === '0') {
+          continue;
+        }
+        
+        // Skip if element has semantic loading attributes
+        if (el.hasAttribute('aria-busy') || el.hasAttribute('data-loading') || el.getAttribute('role') === 'progressbar') {
+          continue;
+        }
+        
+        const width = el.offsetWidth || 0;
+        const height = el.offsetHeight || 0;
+        const elementId = el.id || `${el.tagName}-${el.className}`;
+        
+        // Check size bounds
+        if (!isSpinnerSize(width, height)) {
+          continue;
+        }
+        
+        // Check for spinner patterns
+        let spinnerType = null;
+        let reasonCode = null;
+        
+        if (isBorderSpinnerPattern(style)) {
+          spinnerType = 'border-spinner';
+          reasonCode = 'UI_CSS_SPINNER_DETECTED_BORDER';
+        } else if (isRotationAnimation(style)) {
+          spinnerType = 'rotation-spinner';
+          reasonCode = 'UI_CSS_SPINNER_DETECTED_ROTATION';
+        } else if (isPulseAnimation(style)) {
+          spinnerType = 'pulse-spinner';
+          reasonCode = 'UI_CSS_SPINNER_DETECTED_PULSE';
+        }
+        
+        if (spinnerType) {
+          result.cssSpinners.push({
+            type: spinnerType,
+            reasonCode,
+            elementId,
+            width,
+            height
+          });
+          result.cssSpinnerDetected = true;
+        }
+      }
+      
+      // Require 2+ independent signals for CONFIRMED CSS spinner feedback
+      if (result.cssSpinnerDetected) {
+        const hasDisabledButton = result.disabledElements.length > 0;
+        const hasPointerEventsDisabled = allElements.some(el => {
+          const style = window.getComputedStyle(el);
+          return style.pointerEvents === 'none';
+        });
+        
+        const corroboratingSignals = [hasDisabledButton, hasPointerEventsDisabled].filter(Boolean).length;
+        
+        if (corroboratingSignals >= 1) {
+          result.hasLoadingIndicator = true;
+          result.explanation.push(`CSS spinner detected with ${corroboratingSignals} corroborating signal(s)`);
+          result.cssSpinnerReasonCode = 'UI_CSS_SPINNER_ACCEPTED_WITH_CORROBORATION';
+        } else {
+          result.explanation.push('CSS spinner detected but no corroborating signals (SUSPECTED)');
+          result.cssSpinnerReasonCode = 'UI_CSS_SPINNER_REJECTED_NO_CORROBORATION';
+        }
+      }
+
       // VALIDATION INTELLIGENCE v1: Detect visible validation feedback
       // Check for aria-invalid="true" with visible error text nearby
       const invalidElements = Array.from(document.querySelectorAll('[aria-invalid="true"]'));

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

@@ -3,8 +3,11 @@ import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'fs';
 import { computeExpectationsSummary } from './shared/artifact-manager.js';
 import { createImpactSummary } from './core/silence-impact.js';
 import { computeDecisionSnapshot } from './core/decision-snapshot.js';
+import { VERAX_PRODUCT_DEFINITION } from './core/product-definition.js';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from './core/artifacts/registry.js';
+import { generateHumanSummary } from './core/report/human-summary.js';
 
-export function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, runDirOpt, findingsArray = null) {
+export async function writeScanSummary(projectDir, url, projectType, learnTruth, observeTruth, detectTruth, manifestPath, tracesPath, findingsPath, runDirOpt, findingsArray = null) {
   if (!runDirOpt) {
     throw new Error('runDirOpt is required');
   }
@@ -29,20 +32,30 @@ export function writeScanSummary(projectDir, url, projectType, learnTruth, obser
   }
   
   // PHASE 6: Compute determinism summary from decisions.json
+  // PHASE 21.2: Use HARD verdict from determinism contract
   let determinismSummary = null;
   if (runDirOpt && observeTruth?.runId) {
     const decisionsPath = resolve(runDirOpt, 'decisions.json');
     if (existsSync(decisionsPath)) {
       try {
         const decisions = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
-        const { DecisionRecorder } = require('./core/determinism-model.js');
+        const { DecisionRecorder } = await import('./core/determinism-model.js');
         const recorder = DecisionRecorder.fromExport(decisions);
         const summary = recorder.getSummary();
         
+        // PHASE 21.2: Compute HARD verdict from adaptive events
+        const { computeDeterminismVerdict } = await import('./core/determinism/contract.js');
+        const verdict = computeDeterminismVerdict(recorder);
+        
         determinismSummary = {
-          isDeterministic: summary.isDeterministic,
-          totalDecisions: summary.totalDecisions,
-          decisionsByCategory: summary.decisionsByCategory,
+          verdict: verdict.verdict, // PHASE 21.2: HARD verdict (DETERMINISTIC or NON_DETERMINISTIC)
+          message: verdict.message,
+          reasons: verdict.reasons,
+          adaptiveEventsCount: verdict.adaptiveEvents.length,
+          // Legacy fields for backward compatibility
+          isDeterministic: verdict.verdict === 'DETERMINISTIC',
+          totalDecisions: summary.total,
+          decisionsByCategory: summary.byCategory,
           decisionsPath: decisionsPath
         };
       } catch (error) {
@@ -58,19 +71,37 @@ export function writeScanSummary(projectDir, url, projectType, learnTruth, obser
     decisionSnapshot = computeDecisionSnapshot(findingsArray, detectTruth, observeTruth, silences);
   }
   
+  // PHASE 21.10: Generate human summary
+  let humanSummary = null;
+  if (observeTruth?.runId) {
+    try {
+      humanSummary = await generateHumanSummary(projectDir, observeTruth.runId);
+    } catch {
+      // Ignore errors generating human summary
+    }
+  }
+  
   const summary = {
     version: 1,
+    contractVersion: 1,  // PHASE 0: Track schema changes
     scannedAt: new Date().toISOString(),
     url: url,
     projectType: projectType,
     expectationsSummary: expectationsSummary,
+    // PHASE 0: Include Evidence Law statement
+    evidenceLaw: {
+      statement: VERAX_PRODUCT_DEFINITION.evidenceLaw.statement,
+      description: VERAX_PRODUCT_DEFINITION.evidenceLaw.definition,
+      enforcement: VERAX_PRODUCT_DEFINITION.evidenceLaw.enforcement
+    },
     // PHASE 7: Decision snapshot first (most important for human decision-making)
     decisionSnapshot: decisionSnapshot,
     // PHASE 7: Misinterpretation guards (explicit warnings)
     interpretationGuards: {
       zeroFindings: 'Zero findings does NOT mean no problems. Check unverified count and confidence level.',
       deterministicRun: 'Deterministic run does NOT mean correct site. Only means scan was reproducible.',
-      highSilenceImpact: 'High silence impact does NOT mean failures exist. Only means unknowns affect confidence.'
+      highSilenceImpact: 'High silence impact does NOT mean failures exist. Only means unknowns affect confidence.',
+      evidenceLaw: 'Not all findings are CONFIRMED. Some may be SUSPECTED (insufficient evidence). Only CONFIRMED findings are actionable.'
     },
     truth: {
       learn: learnTruth,
@@ -88,14 +119,17 @@ export function writeScanSummary(projectDir, url, projectType, learnTruth, obser
     } : null,
     // PHASE 6: Add determinism summary
     determinism: determinismSummary,
+    // PHASE 21.10: Add human summary
+    humanSummary: humanSummary,
     paths: {
       manifest: manifestPath,
       traces: tracesPath,
       findings: findingsPath
-    }
+    },
+    artifactVersions: getArtifactVersions()
   };
   
-  const summaryPath = resolve(scanDir, 'scan-summary.json');
+  const summaryPath = resolve(scanDir, ARTIFACT_REGISTRY.scanSummary.filename);
   writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + '\n');
   
   return {

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

@@ -15,6 +15,7 @@
 import { existsSync, mkdirSync, writeFileSync, appendFileSync } from 'fs';
 import { resolve } from 'path';
 import { randomBytes } from 'crypto';
+import { buildRunArtifactPaths } from '../core/artifacts/registry.js';
 
 /**
  * Generate a unique run ID.
@@ -33,17 +34,19 @@ export function generateRunId() {
 export function initArtifactPaths(projectRoot, runId = null) {
   const id = runId || generateRunId();
   const runDir = resolve(projectRoot, '.verax', 'runs', id);
+  const registryPaths = buildRunArtifactPaths(runDir);
 
   const paths = {
     runId: id,
     runDir,
-    summary: resolve(runDir, 'summary.json'),
-    findings: resolve(runDir, 'findings.json'),
+    summary: registryPaths.summaryJson,
+    findings: registryPaths.findingsJson,
     expectations: resolve(runDir, 'expectations.json'),
-    traces: resolve(runDir, 'traces.jsonl'),
-    evidence: resolve(runDir, 'evidence'),
+    traces: registryPaths.tracesJsonl,
+    evidence: registryPaths.evidenceDir,
     flows: resolve(runDir, 'flows'),
-    artifacts: resolve(projectRoot, '.verax', 'artifacts') // Legacy compat
+    artifacts: resolve(projectRoot, '.verax', 'artifacts'), // Legacy compat
+    registry: registryPaths.artifactVersions
   };
 
   // Create directories

package/src/verax/shared/css-spinner-rules.js

@@ -0,0 +1,204 @@
+/**
+ * CSS SPINNER DETECTION RULES
+ * 
+ * Truth boundary for detecting CSS-only loading indicators (spinners)
+ * without semantic attributes (aria-busy, data-loading, role).
+ * 
+ * Hard rules encoded as constants and predicates. No prose, only code.
+ */
+
+/**
+ * Reason codes for CSS spinner detection decisions
+ */
+export const CSS_SPINNER_REASON_CODES = {
+  DETECTED_BORDER_SPINNER: 'UI_CSS_SPINNER_DETECTED_BORDER',
+  DETECTED_ROTATION_ANIMATION: 'UI_CSS_SPINNER_DETECTED_ROTATION',
+  DETECTED_PULSE_ANIMATION: 'UI_CSS_SPINNER_DETECTED_PULSE',
+  REJECTED_DECORATIVE: 'UI_CSS_SPINNER_REJECTED_DECORATIVE',
+  REJECTED_TOO_LARGE: 'UI_CSS_SPINNER_REJECTED_TOO_LARGE',
+  REJECTED_ALWAYS_PRESENT: 'UI_CSS_SPINNER_REJECTED_ALWAYS_PRESENT',
+  REJECTED_NO_CORROBORATION: 'UI_CSS_SPINNER_REJECTED_NO_CORROBORATION',
+  REJECTED_TIMING_WINDOW: 'UI_CSS_SPINNER_TIMED',
+  ACCEPTED_WITH_CORROBORATION: 'UI_CSS_SPINNER_ACCEPTED_WITH_CORROBORATION'
+};
+
+/**
+ * Maximum size for a spinner element (in pixels)
+ * Larger elements are likely decorative, not loading indicators
+ */
+export const MAX_SPINNER_SIZE = 100; // pixels (width or height)
+
+/**
+ * Minimum size for a spinner element (in pixels)
+ * Very small elements might be decorative dots
+ */
+export const MIN_SPINNER_SIZE = 8; // pixels
+
+/**
+ * Timing window for spinner appearance (milliseconds)
+ * Spinner must appear within this window after interaction to count as loading feedback
+ */
+export const SPINNER_TIMING_WINDOW_MS = 2000; // 2 seconds
+
+/**
+ * Check if an element has border-based spinner pattern
+ * Pattern: border + border-top (or border-left) with different color, creating circular spinner
+ * 
+ * @param {Object} computedStyle - Computed style object
+ * @returns {boolean}
+ */
+export function isBorderSpinnerPattern(computedStyle) {
+  if (!computedStyle) return false;
+  
+  const borderWidth = parseFloat(computedStyle.borderWidth) || 0;
+  const borderTopWidth = parseFloat(computedStyle.borderTopWidth) || 0;
+  const borderLeftWidth = parseFloat(computedStyle.borderLeftWidth) || 0;
+  
+  // Must have border
+  if (borderWidth < 2 && borderTopWidth < 2 && borderLeftWidth < 2) {
+    return false;
+  }
+  
+  // Check for different border colors (spinner pattern)
+  const borderColor = computedStyle.borderColor || '';
+  const borderTopColor = computedStyle.borderTopColor || '';
+  const borderLeftColor = computedStyle.borderLeftColor || '';
+  
+  // Border-top or border-left should have different color than main border
+  const hasDifferentTopColor = borderTopColor && borderColor && borderTopColor !== borderColor && borderTopColor !== 'rgba(0, 0, 0, 0)';
+  const hasDifferentLeftColor = borderLeftColor && borderColor && borderLeftColor !== borderColor && borderLeftColor !== 'rgba(0, 0, 0, 0)';
+  
+  // Check for circular shape (border-radius >= 50%)
+  const borderRadius = computedStyle.borderRadius || '';
+  const isCircular = borderRadius.includes('50%') || borderRadius.includes('999') || parseFloat(borderRadius) > 20;
+  
+  return (hasDifferentTopColor || hasDifferentLeftColor) && isCircular;
+}
+
+/**
+ * Check if an element has rotation animation
+ * Pattern: animation-name includes rotation, or transform: rotate() in keyframes
+ * 
+ * @param {Object} computedStyle - Computed style object
+ * @param {Object} element - DOM element
+ * @returns {boolean}
+ */
+export function isRotationAnimation(computedStyle, element) {
+  if (!computedStyle || !element) return false;
+  
+  const animationName = computedStyle.animationName || '';
+  const animation = computedStyle.animation || '';
+  
+  // Check animation name for spinner-related keywords (but don't rely only on names)
+  const spinnerKeywords = ['spin', 'rotate', 'loading', 'loader'];
+  const hasSpinnerKeyword = spinnerKeywords.some(keyword => 
+    animationName.toLowerCase().includes(keyword) || animation.toLowerCase().includes(keyword)
+  );
+  
+  // Check for transform: rotate() in computed style (indicates rotation)
+  const transform = computedStyle.transform || '';
+  const hasRotation = transform.includes('rotate');
+  
+  // Check for animation-duration (must be animated)
+  const animationDuration = computedStyle.animationDuration || '';
+  const isAnimated = animationDuration && animationDuration !== '0s' && !animationDuration.includes('none');
+  
+  // Must have rotation AND be animated
+  return (hasRotation || hasSpinnerKeyword) && isAnimated;
+}
+
+/**
+ * Check if an element has pulse animation (opacity or scale pulsing)
+ * Pattern: animation that changes opacity or scale repeatedly
+ * 
+ * @param {Object} computedStyle - Computed style object
+ * @returns {boolean}
+ */
+export function isPulseAnimation(computedStyle) {
+  if (!computedStyle) return false;
+  
+  const animationName = computedStyle.animationName || '';
+  const animation = computedStyle.animation || '';
+  
+  // Check for pulse-related keywords
+  const pulseKeywords = ['pulse', 'fade', 'loading'];
+  const hasPulseKeyword = pulseKeywords.some(keyword => 
+    animationName.toLowerCase().includes(keyword) || animation.toLowerCase().includes(keyword)
+  );
+  
+  // Check for animation-duration
+  const animationDuration = computedStyle.animationDuration || '';
+  const isAnimated = animationDuration && animationDuration !== '0s' && !animationDuration.includes('none');
+  
+  // Check for opacity animation (common in pulse patterns)
+  const opacity = parseFloat(computedStyle.opacity) || 1;
+  const hasOpacityVariation = opacity < 1; // Partially transparent suggests pulsing
+  
+  return hasPulseKeyword && isAnimated && hasOpacityVariation;
+}
+
+/**
+ * Check if element size is within spinner bounds
+ * 
+ * @param {number} width - Element width in pixels
+ * @param {number} height - Element height in pixels
+ * @returns {boolean}
+ */
+export function isSpinnerSize(width, height) {
+  const maxDim = Math.max(width, height);
+  const minDim = Math.min(width, height);
+  
+  // Must be within size bounds
+  if (maxDim > MAX_SPINNER_SIZE || minDim < MIN_SPINNER_SIZE) {
+    return false;
+  }
+  
+  // Should be roughly square (spinners are usually circular/square)
+  const aspectRatio = maxDim / (minDim || 1);
+  return aspectRatio <= 2.0; // Allow some rectangular tolerance
+}
+
+/**
+ * Check if spinner appeared within timing window
+ * 
+ * @param {number} appearanceTime - Time when spinner appeared (ms since epoch)
+ * @param {number} interactionTime - Time when interaction occurred (ms since epoch)
+ * @returns {boolean}
+ */
+export function isWithinTimingWindow(appearanceTime, interactionTime) {
+  if (!appearanceTime || !interactionTime) return false;
+  const timeDiff = appearanceTime - interactionTime;
+  return timeDiff >= 0 && timeDiff <= SPINNER_TIMING_WINDOW_MS;
+}
+
+/**
+ * Check if element is likely decorative (always present, large, not near interaction)
+ * 
+ * @param {Object} element - DOM element
+ * @param {Object} computedStyle - Computed style object
+ * @param {boolean} wasPresentBefore - Whether element existed before interaction
+ * @returns {boolean}
+ */
+export function isDecorativeElement(element, computedStyle, wasPresentBefore) {
+  if (!element || !computedStyle) return false;
+  
+  // If element was always present, likely decorative
+  if (wasPresentBefore) {
+    return true;
+  }
+  
+  // Check size
+  const width = element.offsetWidth || 0;
+  const height = element.offsetHeight || 0;
+  if (!isSpinnerSize(width, height)) {
+    return true;
+  }
+  
+  // Check if element is very large (likely decorative)
+  if (width > MAX_SPINNER_SIZE || height > MAX_SPINNER_SIZE) {
+    return true;
+  }
+  
+  return false;
+}
+