@veraxhq/verax 0.2.1 → 0.4.0

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

@@ -0,0 +1,235 @@
+/**
+ * Selector Resolver
+ * Finds and validates selectors for extracted promises
+ */
+
+/**
+ * Resolve a selector to an actual element
+ * Returns {found: boolean, selector: string, reason?: string}
+ */
+export async function resolveSelector(page, promise) {
+  // Try promise.selector first if it exists
+  if (promise.selector) {
+    const resolved = await trySelectorVariants(page, promise.selector);
+    if (resolved.found) {
+      return resolved;
+    }
+  }
+  
+  // Try to derive selector from promise details
+  if (promise.category === 'button') {
+    return await resolveButtonSelector(page, promise);
+  }
+  
+  if (promise.category === 'form') {
+    return await resolveFormSelector(page, promise);
+  }
+  
+  if (promise.category === 'validation') {
+    return await resolveValidationSelector(page, promise);
+  }
+  
+  if (promise.type === 'navigation') {
+    return await resolveNavigationSelector(page, promise);
+  }
+  
+  return {
+    found: false,
+    selector: null,
+    reason: 'unsupported-promise-type',
+  };
+}
+
+/**
+ * Try multiple selector variants
+ */
+async function trySelectorVariants(page, baseSelector) {
+  const variants = [
+    baseSelector,
+    baseSelector.replace(/button:contains/, 'button:has-text'),
+    baseSelector.replace(/"/g, "'"),
+  ];
+  
+  for (const selector of variants) {
+    try {
+      const count = await page.locator(selector).count();
+      if (count === 1) {
+        return { found: true, selector };
+      }
+      if (count > 1) {
+        return { found: false, selector, reason: 'ambiguous-selector' };
+      }
+    } catch (e) {
+      // Try next variant
+    }
+  }
+  
+  return { found: false, selector: baseSelector, reason: 'not-found' };
+}
+
+/**
+ * Resolve button selector
+ */
+async function resolveButtonSelector(page, promise) {
+  // First try the provided selector
+  if (promise.selector) {
+    const result = await trySelectorVariants(page, promise.selector);
+    if (result.found) return result;
+  }
+  
+  // Try all button variants
+  const selectors = [
+    'button[onClick]',
+    'button',
+    '[role="button"][onClick]',
+    '[role="button"]',
+  ];
+  
+  for (const selector of selectors) {
+    try {
+      const count = await page.locator(selector).count();
+      if (count === 1) {
+        return { found: true, selector };
+      }
+      if (count > 0) {
+        // Multiple buttons - try to narrow down by content
+        const buttons = await page.locator(selector).all();
+        for (const btn of buttons) {
+          const text = await btn.textContent();
+          if (text && (text.includes('Save') || text.includes('Submit') || text.includes('Click'))) {
+            const specific = `${selector}:has-text("${text.trim()}")`;
+            const count = await page.locator(specific).count();
+            if (count === 1) {
+              return { found: true, selector: specific };
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // Try next
+    }
+  }
+  
+  return { found: false, selector: null, reason: 'not-found' };
+}
+
+/**
+ * Resolve form selector
+ */
+async function resolveFormSelector(page, promise) {
+  if (promise.selector) {
+    const result = await trySelectorVariants(page, promise.selector);
+    if (result.found) return result;
+  }
+  
+  const selectors = [
+    'form[onSubmit]',
+    'form',
+  ];
+  
+  for (const selector of selectors) {
+    try {
+      const count = await page.locator(selector).count();
+      if (count === 1) {
+        return { found: true, selector };
+      }
+    } catch (e) {
+      // Try next
+    }
+  }
+  
+  return { found: false, selector: null, reason: 'not-found' };
+}
+
+/**
+ * Resolve validation selector (for required inputs)
+ */
+async function resolveValidationSelector(page, promise) {
+  if (promise.selector) {
+    const result = await trySelectorVariants(page, promise.selector);
+    if (result.found) return result;
+  }
+  
+  // Look for required inputs
+  const selectors = [
+    'input[required]',
+    'textarea[required]',
+    'select[required]',
+  ];
+  
+  for (const selector of selectors) {
+    try {
+      const count = await page.locator(selector).count();
+      if (count >= 1) {
+        return { found: true, selector };
+      }
+    } catch (e) {
+      // Try next
+    }
+  }
+  
+  return { found: false, selector: null, reason: 'not-found' };
+}
+
+/**
+ * Resolve navigation selector (for anchor tags)
+ */
+async function resolveNavigationSelector(page, promise) {
+  const targetPath = promise.promise.value;
+  
+  const selectors = [
+    `a[href="${targetPath}"]`,
+    `a[href*="${targetPath}"]`,
+  ];
+  
+  for (const selector of selectors) {
+    try {
+      const count = await page.locator(selector).count();
+      if (count === 1) {
+        return { found: true, selector };
+      }
+    } catch (e) {
+      // Try next
+    }
+  }
+  
+  return { found: false, selector: null, reason: 'not-found' };
+}
+
+/**
+ * Find submit button in form
+ */
+export async function findSubmitButton(page, formSelector) {
+  try {
+    // Look for explicit submit button in form
+    const submitBtn = await page.locator(`${formSelector} button[type="submit"]`).first();
+    const count = await submitBtn.count();
+    if (count > 0) {
+      return submitBtn;
+    }
+    
+    // Look for any button in form
+    const btn = await page.locator(`${formSelector} button`).first();
+    if (await btn.count() > 0) {
+      return btn;
+    }
+  } catch (e) {
+    // Fall through
+  }
+  
+  return null;
+}
+
+/**
+ * Check if element is clickable/visible
+ */
+export async function isElementInteractable(page, selector) {
+  try {
+    const element = page.locator(selector).first();
+    const isVisible = await element.isVisible();
+    const isEnabled = await element.isEnabled();
+    return isVisible && isEnabled;
+  } catch (e) {
+    return false;
+  }
+}

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

@@ -1,4 +1,5 @@
 import { atomicWriteJson } from './atomic-write.js';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write summary.json with deterministic digest
@@ -7,6 +8,7 @@ import { atomicWriteJson } from './atomic-write.js';
  */
 export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
   const payload = {
+    contractVersion: ARTIFACT_REGISTRY.summary.contractVersion,
     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 as _extractTemplateBindings, mapTemplateHandlersToScript as _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 (unused)
+ * @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;
+}
+

package/src/cli/util/svelte-sfc-extractor.js

@@ -0,0 +1,146 @@
+/**
+ * PHASE 20 — Svelte SFC (Single File Component) Extractor
+ * 
+ * Extracts <script>, <script context="module">, and markup content from .svelte files.
+ * Deterministic and robust (no external runtime execution).
+ */
+
+/**
+ * PHASE 20: Extract Svelte SFC blocks
+ * 
+ * @param {string} content - Full .svelte file content
+ * @returns {Object} { scriptBlocks: [{content, lang, startLine, isModule}], markup: {content, startLine} }
+ */
+export function extractSvelteSFC(content) {
+  const scriptBlocks = [];
+  let markup = null;
+  
+  // Extract <script> blocks (including <script context="module">)
+  const scriptRegex = /<script(?:\s+context=["']module["'])?(?:\s+lang=["']([^"']+)["'])?[^>]*>([\s\S]*?)<\/script>/gi;
+  let scriptMatch;
+  
+  while ((scriptMatch = scriptRegex.exec(content)) !== null) {
+    const isModule = scriptMatch[0].includes('context="module"') || scriptMatch[0].includes("context='module'");
+    const lang = scriptMatch[1] || 'js';
+    const scriptContent = scriptMatch[2];
+    
+    // Calculate start line
+    const beforeMatch = content.substring(0, scriptMatch.index);
+    const startLine = (beforeMatch.match(/\n/g) || []).length + 1;
+    
+    scriptBlocks.push({
+      content: scriptContent.trim(),
+      lang: lang.toLowerCase(),
+      startLine,
+      isModule,
+    });
+  }
+  
+  // Extract markup (everything outside script/style tags)
+  // Svelte markup is the template content
+  const styleRegex = /<style[^>]*>[\s\S]*?<\/style>/gi;
+  const allScriptRegex = /<script[^>]*>[\s\S]*?<\/script>/gi;
+  
+  let markupContent = content;
+  // Remove style blocks
+  markupContent = markupContent.replace(styleRegex, '');
+  // Remove script blocks
+  markupContent = markupContent.replace(allScriptRegex, '');
+  
+  // Find first non-whitespace line for markup
+  const lines = content.split('\n');
+  let markupStartLine = 1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() && !line.trim().startsWith('<script') && !line.trim().startsWith('<style')) {
+      markupStartLine = i + 1;
+      break;
+    }
+  }
+  
+  if (markupContent.trim()) {
+    markup = {
+      content: markupContent.trim(),
+      startLine: markupStartLine,
+    };
+  }
+  
+  return {
+    scriptBlocks,
+    markup,
+  };
+}
+
+/**
+ * Extract template bindings from Svelte markup
+ * Detects reactive statements, event handlers, and bindings
+ * 
+ * @param {string} markupContent - Svelte markup content
+ * @returns {Object} { reactiveStatements: [], eventHandlers: [], bindings: [] }
+ */
+export function extractTemplateBindings(markupContent) {
+  const reactiveStatements = [];
+  const eventHandlers = [];
+  const bindings = [];
+  
+  // Extract reactive statements: $: statements
+  const reactiveRegex = /\$:\s*([^;]+);/g;
+  let reactiveMatch;
+  while ((reactiveMatch = reactiveRegex.exec(markupContent)) !== null) {
+    reactiveStatements.push({
+      statement: reactiveMatch[1].trim(),
+      line: (markupContent.substring(0, reactiveMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  // Extract event handlers: on:click, on:submit, etc.
+  const eventHandlerRegex = /on:(\w+)=["']([^"']+)["']/g;
+  let handlerMatch;
+  while ((handlerMatch = eventHandlerRegex.exec(markupContent)) !== null) {
+    eventHandlers.push({
+      event: handlerMatch[1],
+      handler: handlerMatch[2],
+      line: (markupContent.substring(0, handlerMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  // Extract bindings: bind:value, bind:checked, etc.
+  const bindingRegex = /bind:(\w+)=["']([^"']+)["']/g;
+  let bindingMatch;
+  while ((bindingMatch = bindingRegex.exec(markupContent)) !== null) {
+    bindings.push({
+      property: bindingMatch[1],
+      variable: bindingMatch[2],
+      line: (markupContent.substring(0, bindingMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  return {
+    reactiveStatements,
+    eventHandlers,
+    bindings,
+  };
+}
+
+/**
+ * Map template handlers to script functions
+ * Helps identify which handlers are UI-bound
+ * 
+ * @param {Array} eventHandlers - Event handlers from template
+ * @param {string} scriptContent - Script block content
+ * @returns {Array} Mapped handlers with function references
+ */
+export function mapTemplateHandlersToScript(eventHandlers, scriptContent) {
+  return eventHandlers.map(handler => {
+    // Try to find function definition in script
+    const functionRegex = new RegExp(`(?:function\\s+${handler.handler}|const\\s+${handler.handler}\\s*=\\s*[^(]*\\(|${handler.handler}\\s*=\\s*[^(]*\\(|export\\s+function\\s+${handler.handler})`, 'g');
+    const functionMatch = functionRegex.exec(scriptContent);
+    
+    return {
+      ...handler,
+      functionFound: !!functionMatch,
+      functionLine: functionMatch ? (scriptContent.substring(0, functionMatch.index).match(/\n/g) || []).length + 1 : null,
+    };
+  });
+}
+