@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/detect/index.js

@@ -25,7 +25,9 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
   const manifestContent = readFileSync(manifestPath, 'utf-8');
   const tracesContent = readFileSync(tracesPath, 'utf-8');
   
+  // @ts-expect-error - readFileSync with encoding returns string
   const manifest = JSON.parse(manifestContent);
+  // @ts-expect-error - readFileSync with encoding returns string
   const observation = JSON.parse(tracesContent);
   
   const projectDir = manifest.projectDir;
@@ -98,20 +100,20 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
                   selectorHint.includes(interactionSelector) || 
                   interactionSelector.includes(normalizedSelectorHint) ||
                   normalizedSelectorHint === normalizedInteractionSelector) {
-                if (expectation.type === 'navigation' && (interaction.type === 'link' || interaction.type === 'button')) {
+                if ((expectation.type === 'navigation' || expectation.type === 'spa_navigation') && (interaction.type === 'link' || interaction.type === 'button')) {
                   matchingExpectations.push(expectation);
                 } else if (expectation.type === 'form_submission' && interaction.type === 'form') {
                   matchingExpectations.push(expectation);
                 }
               } else {
-                if (expectation.type === 'navigation' && (interaction.type === 'link' || interaction.type === 'button')) {
+                if ((expectation.type === 'navigation' || expectation.type === 'spa_navigation') && (interaction.type === 'link' || interaction.type === 'button')) {
                   selectorMismatch = true;
                 } else if (expectation.type === 'form_submission' && interaction.type === 'form') {
                   selectorMismatch = true;
                 }
               }
             } else if (!selectorHint && !interactionSelector) {
-              if (expectation.type === 'navigation' && (interaction.type === 'link' || interaction.type === 'button')) {
+              if ((expectation.type === 'navigation' || expectation.type === 'spa_navigation') && (interaction.type === 'link' || interaction.type === 'button')) {
                 matchingExpectations.push(expectation);
               } else if (expectation.type === 'form_submission' && interaction.type === 'form') {
                 matchingExpectations.push(expectation);
@@ -122,9 +124,24 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
         
         if (matchingExpectations.length > 1) {
           multipleMatches = true;
+          // VISION TRANSPARENCY: Record ambiguity explicitly (not silent skip)
+          if (_silenceTracker) {
+            _silenceTracker.record({
+              scope: 'expectation',
+              reason: 'ambiguous_promise',
+              description: `Multiple expectations match interaction "${interaction.label}" (${matchingExpectations.length} candidates). Cannot determine intent without guessing.`,
+              context: {
+                interaction: { type: interaction.type, selector: interaction.selector, label: interaction.label },
+                candidateCount: matchingExpectations.length,
+                candidates: matchingExpectations.map(e => e.targetPath)
+              },
+              impact: 'interaction_not_evaluated',
+              outcome: 'UNPROVEN_INTERACTION'
+            });
+          }
         } else if (matchingExpectations.length === 1) {
           expectedTargetPath = matchingExpectations[0].targetPath;
-          expectationType = matchingExpectations[0].type;
+          expectationType = matchingExpectations[0].type === 'spa_navigation' ? 'navigation' : matchingExpectations[0].type;
         } else if (selectorMismatch) {
           skips.push({
             code: 'SELECTOR_MISMATCH',
@@ -169,6 +186,21 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
         }
         
         if (matchingRoutes.length > 1) {
+          // VISION TRANSPARENCY: Record ambiguity explicitly
+          if (_silenceTracker) {
+            _silenceTracker.record({
+              scope: 'expectation',
+              reason: 'ambiguous_promise',
+              description: `Multiple routes match interaction "${interaction.label}" (${matchingRoutes.length} candidates). Conservative approach requires single clear match.`,
+              context: {
+                interaction: { type: interaction.type, selector: interaction.selector, label: interaction.label },
+                candidateCount: matchingRoutes.length,
+                candidates: matchingRoutes
+              },
+              impact: 'interaction_not_evaluated',
+              outcome: 'UNPROVEN_INTERACTION'
+            });
+          }
           skips.push({
             code: 'AMBIGUOUS_MATCH',
             message: 'Multiple expectations could match; conservative approach requires single clear match',
@@ -187,6 +219,7 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
     }
     
     if (multipleMatches) {
+      // VISION TRANSPARENCY: Ambiguity already recorded in silence tracker above
       skips.push({
         code: 'AMBIGUOUS_MATCH',
         message: 'Multiple expectations could match; conservative approach requires single clear match',
@@ -243,13 +276,17 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
         
         if (!hasEffect) {
           findings.push({
-            type: 'silent_failure',
+            type: 'navigation_silent_failure',
             interaction: {
               type: interaction.type,
               selector: interaction.selector,
               label: interaction.label
             },
             reason: 'Expected user-visible outcome did not occur',
+            what_happened: 'Navigation attempt produced no visible effect',
+            what_was_expected: `Navigate to ${normalizedTarget || 'target page'}`,
+            what_was_observed: 'URL, DOM, and visuals remained unchanged',
+            why_it_matters: 'Users cannot reach the intended destination despite interacting',
             evidence: {
               before: beforeScreenshot,
               after: afterScreenshot,
@@ -269,6 +306,10 @@ export async function detect(manifestPath, tracesPath, validation = null, _expec
             label: interaction.label
           },
           reason: 'Expected user-visible outcome did not occur',
+          what_happened: 'User action produced no visible effect',
+          what_was_expected: 'Some user-visible change after interaction',
+          what_was_observed: 'URL, DOM, and visuals remained unchanged',
+          why_it_matters: 'Users cannot complete the intended action',
           evidence: {
             before: beforeScreenshot,
             after: afterScreenshot,

package/src/verax/detect/invariants-enforcer.js

@@ -0,0 +1,147 @@
+/**
+ * Phase 4: Final Output Invariants (Trust Lock)
+ *
+ * Strict gate applied only to user-facing outputs (REPORT.json, SUMMARY.md, console).
+ * Findings violating any invariant are dropped silently. Purity and determinism are required.
+ */
+
+const KNOWN_IMPACTS = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO', 'UNKNOWN'];
+const VALID_STATUSES = ['CONFIRMED', 'SUSPECTED', 'INFORMATIONAL'];
+
+function isValidEvidence(evidence) {
+  if (!evidence || typeof evidence !== 'object') return false;
+  const keys = Object.keys(evidence);
+  if (keys.length === 0) return false;
+
+  const signals = Object.values(evidence).filter(v => {
+    if (v === true || v === false) return true;
+    if (typeof v === 'number' && v !== 0) return true;
+    if (typeof v === 'string' && v.length > 0) return true;
+    if (Array.isArray(v)) return v.length > 0; // arrays must contain at least one element
+    if (v && typeof v === 'object') return Object.keys(v).length > 0;
+    return false;
+  });
+
+  return signals.length > 0;
+}
+
+function isValidConfidence(confidence) {
+  if (confidence === 0) return true;
+  if (!confidence) return false;
+
+  if (typeof confidence === 'number') {
+    return confidence >= 0 && confidence <= 1;
+  }
+
+  if (typeof confidence === 'object') {
+    const hasLevel = (typeof confidence.level === 'string' && confidence.level.length > 0) || typeof confidence.level === 'number';
+    const hasScore = typeof confidence.score === 'number';
+    return hasLevel || hasScore;
+  }
+
+  return false;
+}
+
+function isValidPromise(promise) {
+  if (!promise || typeof promise !== 'object') return false;
+
+  const { kind, value, type, expected, actual, expected_signal } = promise;
+
+  const kindValueValid = typeof kind === 'string' && kind.length > 0 && typeof value === 'string' && value.length > 0;
+  const typeValid = typeof type === 'string' && type.length > 0;
+  const expectationValid = (typeof expected === 'string' && expected.length > 0) ||
+    (typeof actual === 'string' && actual.length > 0) ||
+    (typeof expected_signal === 'string' && expected_signal.length > 0);
+
+  return kindValueValid || (typeValid && expectationValid);
+}
+
+function isInternalErrorFlag(finding) {
+  const internalMarkers = [
+    'INTERNAL_ERROR',
+    'internal-error',
+    'internalError',
+    'TIMEOUT_ERROR',
+    'CRASH',
+    'FATAL',
+    'BROWSER_CRASH'
+  ];
+
+  if (internalMarkers.some(marker =>
+    finding.reason?.includes?.(marker) ||
+    finding.errorMessage?.includes?.(marker) ||
+    finding.errorStack?.includes?.(marker)
+  )) {
+    return true;
+  }
+
+  if (finding.reason?.toLowerCase?.().includes('internal error')) {
+    return true;
+  }
+
+  return false;
+}
+
+function isValidCause(cause, evidence) {
+  if (!cause || typeof cause !== 'object') return false;
+  if (!cause.id || !cause.statement) return false;
+
+  if (Array.isArray(cause.evidence_refs) && cause.evidence_refs.length > 0) {
+    if (!evidence || typeof evidence !== 'object') return false;
+    return cause.evidence_refs.every(ref => typeof ref === 'string' && ref in evidence);
+  }
+
+  return true;
+}
+
+export function filterCausesWithEvidence(evidence, causes) {
+  if (!Array.isArray(causes)) return [];
+  return causes.filter(cause => isValidCause(cause, evidence));
+}
+
+function enforceFinalInvariant(finding) {
+  if (!finding) return null;
+
+  if (!isValidEvidence(finding.evidence)) return null;
+  if (!isValidPromise(finding.promise)) return null;
+  if (!isValidConfidence(finding.confidence)) return null;
+  if (finding.impact && !KNOWN_IMPACTS.includes(finding.impact)) return null;
+  if (isInternalErrorFlag(finding)) return null;
+  if (!finding.id || typeof finding.id !== 'string' || finding.id.length === 0) return null;
+  if (finding.status && !VALID_STATUSES.includes(finding.status)) return null;
+
+  const causes = filterCausesWithEvidence(finding.evidence, finding.causes);
+
+  return { ...finding, causes };
+}
+
+export function deduplicateFindings(findings) {
+  const seen = new Set();
+  const deduped = [];
+
+  for (const finding of findings) {
+    const promiseKey = finding.promise ? JSON.stringify(finding.promise) : 'nopromise';
+    const key = `${finding.id || 'unknown'}|${finding.location || 'unknown'}|${promiseKey}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(finding);
+  }
+
+  return deduped;
+}
+
+export function enforceFinalInvariants(findings) {
+  if (!Array.isArray(findings)) return [];
+
+  const validFindings = findings
+    .map(enforceFinalInvariant)
+    .filter(Boolean);
+
+  const deduped = deduplicateFindings(validFindings);
+
+  return deduped.sort((a, b) => {
+    const aId = (a.id || '').toString();
+    const bId = (b.id || '').toString();
+    return aId.localeCompare(bId);
+  });
+}