@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/run-list.js

@@ -0,0 +1,211 @@
+/**
+ * Run Listing CLI Command
+ * Lists completed Guardian runs with their metadata
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readMetaJson, formatDuration } = require('./run-artifacts');
+
+/**
+ * Find all run directories in artifacts folder
+ * 
+ * @param {string} artifactsDir - Path to artifacts directory
+ * @returns {string[]} array of run directory paths
+ */
+function findRunDirs(artifactsDir) {
+  if (!fs.existsSync(artifactsDir)) {
+    return [];
+  }
+  
+  try {
+    const entries = fs.readdirSync(artifactsDir, { withFileTypes: true });
+    return entries
+      .filter(e => e.isDirectory())
+      .map(e => path.join(artifactsDir, e.name));
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Load run metadata with fallback to directory name parsing
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {Object|null} run info or null if cannot parse
+ */
+function loadRunInfo(runDir) {
+  const dirName = path.basename(runDir);
+  
+  // Try META.json first
+  const meta = readMetaJson(runDir);
+  if (meta) {
+    return {
+      path: runDir,
+      dirName,
+      timestamp: meta.timestamp,
+      url: meta.url,
+      siteSlug: meta.siteSlug,
+      policy: meta.policy,
+      result: meta.result,
+      durationMs: meta.durationMs,
+      attempts: meta.attempts
+    };
+  }
+  
+  // Silently skip if no META.json
+  return null;
+}
+
+/**
+ * Format and sort runs for display
+ * 
+ * @param {Array} runs - Array of run info objects
+ * @returns {Array} sorted by timestamp (newest first)
+ */
+function sortRuns(runs) {
+  return runs
+    .filter(r => r !== null)
+    .sort((a, b) => {
+      const timeA = new Date(a.timestamp).getTime();
+      const timeB = new Date(b.timestamp).getTime();
+      return timeB - timeA; // newest first
+    });
+}
+
+/**
+ * Format time string from ISO timestamp
+ * 
+ * @param {string} isoString - ISO-8601 timestamp
+ * @returns {string} formatted local time (YYYY-MM-DD HH:MM:SS)
+ */
+function formatTime(isoString) {
+  const date = new Date(isoString);
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hours = String(date.getHours()).padStart(2, '0');
+  const minutes = String(date.getMinutes()).padStart(2, '0');
+  const seconds = String(date.getSeconds()).padStart(2, '0');
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Calculate column widths for table display
+ * 
+ * @param {Array} runs - Run records
+ * @returns {Object} widths for each column
+ */
+function calculateColumnWidths(runs) {
+  // Use fixed reasonable widths for 100-char display
+  return {
+    time: 19,      // "YYYY-MM-DD HH:MM:SS"
+    site: 14,
+    policy: 10,
+    result: 7,
+    duration: 10,
+    path: 30
+  };
+}
+
+/**
+ * Format a single row for table output
+ * 
+ * @param {Object} run - Run info
+ * @param {Object} widths - Column widths
+ * @returns {string} formatted row
+ */
+function formatRow(run, widths) {
+  const time = formatTime(run.timestamp);
+  const site = (run.siteSlug || 'unknown').substring(0, widths.site);
+  const policy = (run.policy || 'default').substring(0, widths.policy);
+  const result = (run.result || 'UNKNOWN').substring(0, widths.result);
+  const duration = formatDuration(run.durationMs).substring(0, widths.duration);
+  const path = run.dirName.substring(0, widths.path);
+  
+  return `${time}  ${site.padEnd(widths.site)}  ${policy.padEnd(widths.policy)}  ${result.padEnd(widths.result)}  ${duration.padEnd(widths.duration)}  ${path}`;
+}
+
+/**
+ * Main list command with filtering
+ * 
+ * @param {string} artifactsDir - Path to artifacts directory
+ * @param {Object} filters - Filter options
+ * @param {boolean} filters.failed - Show only FAILED runs
+ * @param {string} filters.site - Show only runs for specific site slug
+ * @param {number} filters.limit - Show only newest N runs
+ */
+function listRuns(artifactsDir = './artifacts', filters = {}) {
+  const runDirs = findRunDirs(artifactsDir);
+  
+  if (runDirs.length === 0) {
+    console.log('No runs found.');
+    return 0;
+  }
+  
+  // Load metadata for all runs
+  let runs = runDirs
+    .map(dir => loadRunInfo(dir))
+    .filter(r => r !== null);
+  
+  if (runs.length === 0) {
+    console.log('No completed runs with META.json found.');
+    return 0;
+  }
+  
+  // Apply filters
+  if (filters.failed) {
+    runs = runs.filter(r => r.result === 'FAILED');
+  }
+  
+  if (filters.site) {
+    runs = runs.filter(r => r.siteSlug === filters.site);
+  }
+  
+  if (runs.length === 0) {
+    console.log('No runs matching the filters.');
+    return 0;
+  }
+  
+  // Sort by timestamp (newest first)
+  const sorted = sortRuns(runs);
+  
+  // Apply limit filter
+  let displayed = sorted;
+  if (filters.limit && filters.limit > 0) {
+    displayed = sorted.slice(0, filters.limit);
+  }
+  
+  // Calculate column widths
+  const widths = calculateColumnWidths(displayed);
+  
+  // Print header
+  console.log('');
+  console.log('Guardian Runs');
+  console.log('='.repeat(100));
+  const header = 'Time'.padEnd(widths.time + 2) +
+    'Site'.padEnd(widths.site + 2) +
+    'Policy'.padEnd(widths.policy + 2) +
+    'Result'.padEnd(widths.result + 2) +
+    'Duration'.padEnd(widths.duration + 2) +
+    'Path';
+  console.log(header);
+  console.log('-'.repeat(100));
+  
+  // Print rows
+  for (const run of displayed) {
+    console.log(formatRow(run, widths));
+  }
+  
+  console.log('='.repeat(100));
+  console.log(`Total: ${runs.length} run(s)${displayed.length < runs.length ? ` (showing ${displayed.length})` : ''}\n`);
+  
+  return 0;
+}
+
+module.exports = {
+  listRuns,
+  findRunDirs,
+  loadRunInfo,
+  sortRuns
+};

package/src/guardian/run-summary.js

@@ -0,0 +1,20 @@
+function deriveBaselineVerdict({ baselineCreated, diffResult }) {
+  if (baselineCreated) return 'BASELINE_CREATED';
+  if (!diffResult) return 'NO_BASELINE';
+  const hasRegressions = diffResult.regressions && Object.keys(diffResult.regressions).length > 0;
+  const hasImprovements = diffResult.improvements && Object.keys(diffResult.improvements).length > 0;
+  if (hasRegressions) return 'REGRESSION_DETECTED';
+  if (hasImprovements) return 'IMPROVEMENT_DETECTED';
+  return 'NO_REGRESSION';
+}
+
+function formatRunSummary({ flowResults = [], diffResult = null, baselineCreated = false, exitCode = 0 }, options = {}) {
+  const success = flowResults.filter(f => f.outcome === 'SUCCESS').length;
+  const friction = flowResults.filter(f => f.outcome === 'FRICTION').length;
+  const failure = flowResults.filter(f => f.outcome === 'FAILURE').length;
+  const baseline = deriveBaselineVerdict({ baselineCreated, diffResult });
+  const label = options.label || 'Summary';
+  return `${label}: flows=${flowResults.length} success=${success} friction=${friction} failure=${failure} | baseline=${baseline} | exit=${exitCode}`;
+}
+
+module.exports = { formatRunSummary, deriveBaselineVerdict };

package/src/guardian/scan-presets.js

@@ -2,6 +2,8 @@
  * Scan Presets (Phase 6)
  * Opinionated defaults for one-command scans
  * Deterministic mappings: attempts, flows, policy thresholds.
+ * Each preset must fully define coverage (enabled/disabled attempts), flows,
+ * policy strictness, and operational defaults (fail-fast, evidence expectations).
  */
 
 const { getDefaultAttemptIds } = require('./attempt-registry');
@@ -10,50 +12,137 @@ const { getDefaultFlowIds } = require('./flow-registry');
 function resolveScanPreset(name = 'landing') {
   const preset = (name || '').toLowerCase();
 
+  if (!preset) {
+    throw new Error('Preset name is required');
+  }
+
   // Defaults: curated attempts + curated flows
   const defaults = {
+    id: 'default',
     attempts: getDefaultAttemptIds(),
+    disabledAttempts: [],
     flows: getDefaultFlowIds(),
-    policy: null
+    policy: null,
+    failFast: true,
+    evidence: {
+      requireScreenshots: true,
+      requireTraces: true,
+      minCompleteness: 1.0,
+      minIntegrity: 0.9
+    }
   };
 
   switch (preset) {
     case 'landing':
       return {
-        attempts: ['contact_form', 'language_switch', 'newsletter_signup'],
+        id: 'landing',
+        attempts: ['site_smoke', 'primary_ctas', 'contact_discovery_v2', 'contact_form', 'language_switch', 'newsletter_signup'],
+        disabledAttempts: ['signup', 'login', 'checkout'],
         flows: [], // focus on landing conversion, flows optional
         policy: {
           // lenient warnings, strict criticals
           failOnSeverity: 'CRITICAL',
-          maxWarnings: 999,
-          visualGates: { CRITICAL: 0, WARNING: 999, maxDiffPercent: 25 }
-        }
+          maxWarnings: 5,
+          visualGates: { CRITICAL: 0, WARNING: 5, maxDiffPercent: 25 },
+          coverage: { failOnGap: false, warnOnGap: true },
+          evidence: { minCompleteness: 0.6, minIntegrity: 0.7, requireScreenshots: true, requireTraces: false }
+        },
+        failFast: true,
+        evidence: { requireScreenshots: true, requireTraces: false, minCompleteness: 0.6, minIntegrity: 0.7 }
+      };
+    case 'landing-demo':
+      return {
+        id: 'landing-demo',
+        attempts: ['site_smoke', 'primary_ctas', 'contact_discovery_v2', 'contact_form', 'language_switch'],
+        disabledAttempts: ['signup', 'login', 'checkout', 'newsletter_signup'],
+        flows: [],
+        policy: {
+          // Strict on broken navigation and CTA, lenient on revenue-related issues
+          failOnSeverity: 'CRITICAL',
+          maxWarnings: 5,
+          failOnNewRegression: false,
+          visualGates: { CRITICAL: 0, WARNING: 999, maxDiffPercent: 30 },
+          coverage: { failOnGap: true, warnOnGap: false },
+          evidence: { minCompleteness: 0.7, minIntegrity: 0.8, requireScreenshots: true, requireTraces: false }
+        },
+        failFast: true,
+        evidence: { requireScreenshots: true, requireTraces: false, minCompleteness: 0.7, minIntegrity: 0.8 }
+      };
+    case 'startup':
+      return {
+        id: 'startup',
+        attempts: getDefaultAttemptIds(),
+        disabledAttempts: [],
+        flows: getDefaultFlowIds(),
+        policy: {
+          failOnSeverity: 'CRITICAL',
+          maxWarnings: 3,
+          maxInfo: 999,
+          failOnNewRegression: false,
+          visualGates: { CRITICAL: 0, WARNING: 5, maxDiffPercent: 30 },
+          coverage: { failOnGap: true, warnOnGap: false },
+          evidence: { minCompleteness: 0.7, minIntegrity: 0.8, requireScreenshots: true, requireTraces: false }
+        },
+        failFast: true,
+        evidence: { requireScreenshots: true, requireTraces: false, minCompleteness: 0.7, minIntegrity: 0.8 }
       };
     case 'saas':
       return {
-        attempts: ['language_switch', 'contact_form', 'newsletter_signup'],
+        id: 'saas',
+        attempts: ['site_smoke', 'primary_ctas', 'contact_discovery_v2', 'language_switch', 'contact_form', 'newsletter_signup'],
         flows: ['signup_flow', 'login_flow'],
         policy: {
           failOnSeverity: 'CRITICAL',
           maxWarnings: 1,
           failOnNewRegression: true,
-          visualGates: { CRITICAL: 0, WARNING: 5, maxDiffPercent: 20 }
-        }
+          visualGates: { CRITICAL: 0, WARNING: 5, maxDiffPercent: 20 },
+          coverage: { failOnGap: true, warnOnGap: false },
+          evidence: { minCompleteness: 0.8, minIntegrity: 0.9, requireScreenshots: true, requireTraces: true }
+        },
+        failFast: true,
+        evidence: { requireScreenshots: true, requireTraces: true, minCompleteness: 0.8, minIntegrity: 0.9 }
       };
     case 'shop':
     case 'ecommerce':
       return {
+        id: 'shop',
         attempts: ['language_switch', 'contact_form', 'newsletter_signup'],
         flows: ['checkout_flow'],
         policy: {
           failOnSeverity: 'CRITICAL',
           maxWarnings: 0,
           failOnNewRegression: true,
-          visualGates: { CRITICAL: 0, WARNING: 0, maxDiffPercent: 15 }
-        }
+          visualGates: { CRITICAL: 0, WARNING: 0, maxDiffPercent: 15 },
+          coverage: { failOnGap: true, warnOnGap: false },
+          evidence: { minCompleteness: 0.9, minIntegrity: 0.95, requireScreenshots: true, requireTraces: true }
+        },
+        failFast: true,
+        evidence: { requireScreenshots: true, requireTraces: true, minCompleteness: 0.9, minIntegrity: 0.95 }
+      };
+    case 'enterprise':
+      return {
+        id: 'enterprise',
+        attempts: getDefaultAttemptIds(),
+        disabledAttempts: [],
+        flows: getDefaultFlowIds(),
+        policy: {
+          failOnSeverity: 'WARNING',
+          maxWarnings: 0,
+          maxInfo: 0,
+          maxTotalRisk: 0,
+          failOnNewRegression: true,
+          failOnSoftFailures: true,
+          softFailureThreshold: 0,
+          requireBaseline: true,
+          visualGates: { CRITICAL: 0, WARNING: 0, maxDiffPercent: 10 },
+          coverage: { failOnGap: true, warnOnGap: false },
+          evidence: { minCompleteness: 1.0, minIntegrity: 0.98, requireScreenshots: true, requireTraces: true }
+        },
+        failFast: true,
+        evidence: { requireScreenshots: true, requireTraces: true, minCompleteness: 1.0, minIntegrity: 0.98 }
       };
     default:
-      return defaults;
+      throw new Error(`Unknown preset: ${name}`);
   }
 }