agentic-qe 3.15.11 → 3.15.13

package/dist/domains/visual-accessibility/services/accessibility-tester-heuristics.d.ts

@@ -1,8 +1,14 @@
 /**
- * Agentic QE v3 - Accessibility Tester Heuristic Analysis
- * Extracted from accessibility-tester.ts - URL-pattern-based heuristic checks
- */
-import type { AccessibilityViolation, ViolationNode, WCAGCriterion, ContrastAnalysis, KeyboardNavigationReport } from '../interfaces.js';
+ * Agentic QE v3 - Accessibility Tester Rules and Simulation
+ * Extracted from accessibility-tester.ts.
+ *
+ * #1145: the URL-pattern "heuristic" checks that used to live here guessed
+ * violations, contrast ratios, keyboard reports and WCAG verdicts from the URL
+ * text alone, without loading the page. They were removed: only a browser run
+ * measures a page. What remains is the rule catalogue and the opt-in
+ * simulation mode, whose synthetic output is always labelled unmeasured.
+ */
+import type { AccessibilityViolation, ViolationNode } from '../interfaces.js';
 export interface AccessibilityRule {
     id: string;
     description: string;
@@ -24,28 +30,14 @@ export declare function initializeRules(): AccessibilityRule[];
  */
 export declare function filterRulesByLevel(rules: AccessibilityRule[], level: 'A' | 'AA' | 'AAA'): AccessibilityRule[];
 /**
- * Run a rule and return violation nodes, pass status, and checked count
+ * Run a rule in simulation mode: synthetic, URL-hash-derived nodes for tests.
+ * The result is NOT a measurement (#1145); callers must label it unmeasured.
  */
-export declare function runRule(rule: AccessibilityRule, context: RuleContext, simulationMode: boolean, enableColorContrastCheck: boolean): {
+export declare function runSimulatedRule(rule: AccessibilityRule, context: RuleContext): {
     nodes: ViolationNode[];
     passed: boolean;
     checkedNodes: number;
 };
-/**
- * Validate a specific WCAG criterion deterministically
- */
-export declare function validateCriterion(criterion: WCAGCriterion, urlHash: number): {
-    passed: boolean;
-    reason?: string;
-};
-/**
- * Analyze contrast for common UI elements using heuristics
- */
-export declare function analyzeContrastForElements(url: string): ContrastAnalysis[];
-/**
- * Generate keyboard navigation report using heuristics
- */
-export declare function generateKeyboardReportWithHeuristics(url: string): KeyboardNavigationReport;
 /**
  * Hash a URL to a deterministic string
  */

package/dist/domains/visual-accessibility/services/accessibility-tester-heuristics.js

@@ -1,6 +1,12 @@
 /**
- * Agentic QE v3 - Accessibility Tester Heuristic Analysis
- * Extracted from accessibility-tester.ts - URL-pattern-based heuristic checks
+ * Agentic QE v3 - Accessibility Tester Rules and Simulation
+ * Extracted from accessibility-tester.ts.
+ *
+ * #1145: the URL-pattern "heuristic" checks that used to live here guessed
+ * violations, contrast ratios, keyboard reports and WCAG verdicts from the URL
+ * text alone, without loading the page. They were removed: only a browser run
+ * measures a page. What remains is the rule catalogue and the opt-in
+ * simulation mode, whose synthetic output is always labelled unmeasured.
  */
 import { WCAG_CRITERIA } from './accessibility-tester-browser.js';
 /**
@@ -34,149 +40,17 @@ export function filterRulesByLevel(rules, level) {
     });
 }
 // ============================================================================
-// Heuristic Rule Checking
+// Simulation Mode (Deterministic)
 // ============================================================================
 /**
- * Run a rule and return violation nodes, pass status, and checked count
+ * Run a rule in simulation mode: synthetic, URL-hash-derived nodes for tests.
+ * The result is NOT a measurement (#1145); callers must label it unmeasured.
  */
-export function runRule(rule, context, simulationMode, enableColorContrastCheck) {
-    if (simulationMode) {
-        const nodes = checkRuleDeterministic(rule, context);
-        const checkedNodes = estimateCheckedNodes(rule, context);
-        return { nodes, passed: nodes.length === 0, checkedNodes };
-    }
-    const nodes = checkRuleWithHeuristics(rule, context, enableColorContrastCheck);
+export function runSimulatedRule(rule, context) {
+    const nodes = checkRuleDeterministic(rule, context);
     const checkedNodes = estimateCheckedNodes(rule, context);
     return { nodes, passed: nodes.length === 0, checkedNodes };
 }
-/**
- * Heuristic-based WCAG rule checking for production mode.
- */
-function checkRuleWithHeuristics(rule, context, enableColorContrastCheck) {
-    const nodes = [];
-    const url = context.url.toLowerCase();
-    switch (rule.id) {
-        case 'image-alt':
-            if (isLikelyImageHeavyPage(url))
-                nodes.push(...generateImageAltWarnings());
-            break;
-        case 'button-name':
-            if (isLikelyInteractivePage(url))
-                nodes.push(...generateButtonNameWarnings());
-            break;
-        case 'color-contrast':
-            if (enableColorContrastCheck)
-                nodes.push(...generateContrastWarnings());
-            break;
-        case 'html-lang':
-            if (isLikelyMissingLang(url)) {
-                nodes.push({
-                    selector: 'html', html: '<html>', target: ['html'],
-                    failureSummary: 'Page may be missing lang attribute',
-                    fixSuggestion: 'Add lang attribute to <html> element (e.g., <html lang="en">)',
-                });
-            }
-            break;
-        case 'link-name':
-            if (hasNavigationPatterns(url))
-                nodes.push(...generateLinkNameWarnings());
-            break;
-        case 'focus-visible':
-            if (isLikelySPA(url))
-                nodes.push(...generateFocusVisibleWarnings());
-            break;
-        case 'bypass-blocks':
-            if (!hasSkipLinkPattern(url)) {
-                nodes.push({
-                    selector: 'body', html: '<body>', target: ['body'],
-                    failureSummary: 'Page may lack skip navigation mechanism',
-                    fixSuggestion: 'Add a skip link at the beginning of the page to bypass repeated content',
-                });
-            }
-            break;
-        case 'label':
-            if (isFormPage(url))
-                nodes.push(...generateFormLabelWarnings());
-            break;
-        case 'keyboard-trap':
-            if (hasModalPatterns(url))
-                nodes.push(...generateKeyboardTrapWarnings());
-            break;
-        case 'focus-order':
-            if (hasComplexLayoutPatterns(url))
-                nodes.push(...generateFocusOrderWarnings());
-            break;
-    }
-    return nodes;
-}
-// ============================================================================
-// URL Pattern Detection
-// ============================================================================
-function isLikelyImageHeavyPage(url) {
-    return url.includes('gallery') || url.includes('photo') || url.includes('image') ||
-        url.includes('product') || url.includes('portfolio') || url.includes('media');
-}
-function isLikelyInteractivePage(url) {
-    return url.includes('app') || url.includes('dashboard') || url.includes('editor') ||
-        url.includes('tool') || url.includes('builder') || url.includes('widget');
-}
-function isLikelyMissingLang(url) {
-    return url.includes('cdn') || url.includes('static') || url.includes('.html') || url.includes('file://');
-}
-function hasNavigationPatterns(url) {
-    return url.includes('nav') || url.includes('menu') || url.includes('header') ||
-        url.includes('sidebar') || url.includes('footer');
-}
-function isLikelySPA(url) {
-    return url.includes('app') || url.includes('dashboard') || url.includes('#/') ||
-        url.includes('react') || url.includes('angular') || url.includes('vue');
-}
-function hasSkipLinkPattern(url) {
-    return url.includes('gov') || url.includes('edu') || url.includes('a11y') || url.includes('accessible');
-}
-function isFormPage(url) {
-    return url.includes('form') || url.includes('contact') || url.includes('register') ||
-        url.includes('signup') || url.includes('login') || url.includes('checkout') ||
-        url.includes('submit') || url.includes('search');
-}
-function hasModalPatterns(url) {
-    return url.includes('modal') || url.includes('dialog') || url.includes('popup') ||
-        url.includes('overlay') || url.includes('lightbox');
-}
-function hasComplexLayoutPatterns(url) {
-    return url.includes('dashboard') || url.includes('admin') || url.includes('grid') ||
-        url.includes('layout') || url.includes('multi');
-}
-// ============================================================================
-// Warning Generators
-// ============================================================================
-function generateImageAltWarnings() {
-    return [{ selector: 'img', html: '<img src="...">', target: ['img'], failureSummary: 'Images should have descriptive alt text', fixSuggestion: 'Add alt attribute with meaningful description to all <img> elements' }];
-}
-function generateButtonNameWarnings() {
-    return [{ selector: 'button:not([aria-label])', html: '<button>', target: ['button'], failureSummary: 'Buttons should have accessible names', fixSuggestion: 'Ensure buttons have visible text or aria-label attribute' }];
-}
-function generateContrastWarnings() {
-    return [{ selector: '.text-content', html: '<div class="text-content">', target: ['.text-content'], failureSummary: 'Text elements should meet WCAG 2.2 AA contrast ratio (4.5:1)', fixSuggestion: 'Verify text color has sufficient contrast against background' }];
-}
-function generateLinkNameWarnings() {
-    return [{ selector: 'a:not([aria-label])', html: '<a href="#">', target: ['a'], failureSummary: 'Links should have descriptive text', fixSuggestion: 'Add meaningful link text or aria-label attribute' }];
-}
-function generateFocusVisibleWarnings() {
-    return [{ selector: ':focus', html: '<element>:focus', target: [':focus'], failureSummary: 'Interactive elements should have visible focus indicators', fixSuggestion: 'Do not remove outline on :focus; use :focus-visible for styling' }];
-}
-function generateFormLabelWarnings() {
-    return [{ selector: 'input:not([aria-label]):not([id])', html: '<input type="text">', target: ['input'], failureSummary: 'Form inputs should have associated labels', fixSuggestion: 'Add <label for="id"> or aria-label to form inputs' }];
-}
-function generateKeyboardTrapWarnings() {
-    return [{ selector: '[role="dialog"]', html: '<div role="dialog">', target: ['[role="dialog"]'], failureSummary: 'Modal dialogs should not trap keyboard focus', fixSuggestion: 'Ensure Escape key closes modal and Tab cycles within dialog' }];
-}
-function generateFocusOrderWarnings() {
-    return [{ selector: '[tabindex]', html: '<div tabindex="...">', target: ['[tabindex]'], failureSummary: 'Focus order should follow logical reading sequence', fixSuggestion: 'Avoid positive tabindex values; use tabindex="0" or "-1"' }];
-}
-// ============================================================================
-// Simulation Mode (Deterministic)
-// ============================================================================
 function checkRuleDeterministic(rule, context) {
     const nodes = [];
     const urlHash = hashUrl(context.url);
@@ -228,164 +102,6 @@ function estimateCheckedNodes(rule, context) {
     return 10 + (context.url.length % 10);
 }
 // ============================================================================
-// WCAG Validation
-// ============================================================================
-/**
- * Validate a specific WCAG criterion deterministically
- */
-export function validateCriterion(criterion, urlHash) {
-    const criterionFailureRates = {
-        '1.1.1': 0.12, '1.3.1': 0.08, '1.4.1': 0.05, '1.4.3': 0.15,
-        '1.4.6': 0.25, '2.1.1': 0.10, '2.1.2': 0.03, '2.4.1': 0.08,
-        '2.4.3': 0.06, '2.4.4': 0.10, '2.4.7': 0.12, '3.1.1': 0.04,
-        '4.1.1': 0.02, '4.1.2': 0.09,
-    };
-    const failureRate = criterionFailureRates[criterion.id] ?? 0.1;
-    const criterionHashOffset = criterion.id.charCodeAt(0) * 100;
-    const determinant = ((urlHash + criterionHashOffset) % 100) / 100;
-    const passed = determinant >= failureRate;
-    return {
-        passed,
-        reason: passed ? undefined : `Criterion ${criterion.id} (${criterion.title}) not fully satisfied`,
-    };
-}
-// ============================================================================
-// Contrast Analysis (Heuristic)
-// ============================================================================
-/**
- * Analyze contrast for common UI elements using heuristics
- */
-export function analyzeContrastForElements(url) {
-    const elements = ['h1', 'p', 'a', 'button', '.card-text', '.nav-link'];
-    const analyses = [];
-    const urlHash = hashUrl(url);
-    const hashNum = parseInt(urlHash, 36);
-    for (let i = 0; i < elements.length; i++) {
-        const element = elements[i];
-        const baseRatio = 4.5 + ((hashNum + i * 1000) % 100) / 10;
-        const ratio = Math.round(baseRatio * 100) / 100;
-        const isLargeText = element === 'h1' || element === 'button';
-        const requiredRatio = isLargeText ? 3 : 4.5;
-        const passes = ratio >= requiredRatio;
-        const fgValue = 20 + ((hashNum + i * 50) % 30);
-        const bgValue = 200 + ((hashNum + i * 30) % 55);
-        const fgHex = fgValue.toString(16).padStart(2, '0');
-        const bgHex = bgValue.toString(16).padStart(2, '0');
-        analyses.push({
-            element,
-            foreground: `#${fgHex}${fgHex}${fgHex}`,
-            background: `#${bgHex}${bgHex}${bgHex}`,
-            ratio,
-            requiredRatio,
-            passes,
-            wcagLevel: 'AA',
-        });
-    }
-    return analyses;
-}
-// ============================================================================
-// Keyboard Navigation (Heuristic)
-// ============================================================================
-/**
- * Generate keyboard navigation report using heuristics
- */
-export function generateKeyboardReportWithHeuristics(url) {
-    const urlHash = hashUrl(url);
-    const tabOrder = generateTabOrder(url, urlHash);
-    const issues = detectKeyboardIssues(tabOrder);
-    const traps = detectFocusTraps(url, urlHash);
-    return {
-        url,
-        focusableElements: tabOrder.length,
-        tabOrder,
-        issues,
-        traps,
-    };
-}
-function generateTabOrder(url, urlHash) {
-    const items = [];
-    const hashNum = parseInt(urlHash, 36);
-    const elements = [
-        { selector: '#skip-link', type: 'link' },
-        { selector: 'header nav a.logo', type: 'link' },
-        { selector: 'header nav a.menu-item', type: 'link' },
-        { selector: '#search-input', type: 'input' },
-        { selector: '#search-button', type: 'button' },
-        { selector: 'main a', type: 'link' },
-        { selector: 'main button', type: 'button' },
-        { selector: 'form input', type: 'input' },
-        { selector: 'form select', type: 'input' },
-        { selector: 'form button[type="submit"]', type: 'button' },
-        { selector: 'footer a', type: 'link' },
-    ];
-    elements.forEach((elem, index) => {
-        const focusVisibleDeterminant = (hashNum + index * 17) % 100;
-        const hasVisibleFocus = focusVisibleDeterminant >= 12;
-        items.push({
-            index,
-            selector: elem.selector,
-            elementType: elem.type,
-            hasVisibleFocus,
-        });
-    });
-    return items;
-}
-function detectKeyboardIssues(tabOrder) {
-    const issues = [];
-    for (const item of tabOrder) {
-        if (!item.hasVisibleFocus) {
-            issues.push({
-                type: 'no-focus-indicator',
-                selector: item.selector,
-                description: `Element ${item.selector} does not have a visible focus indicator`,
-            });
-        }
-    }
-    if (!tabOrder.some((item) => item.selector.includes('skip'))) {
-        issues.push({
-            type: 'skip-link-missing',
-            selector: 'body',
-            description: 'Page is missing a skip navigation link',
-        });
-    }
-    const hasLogicalOrder = tabOrder.every((item, index) => {
-        if (index === 0)
-            return true;
-        const isNav = item.selector.includes('nav') || item.selector.includes('header');
-        const prevIsMain = tabOrder[index - 1].selector.includes('main');
-        return !(isNav && prevIsMain);
-    });
-    if (!hasLogicalOrder) {
-        issues.push({
-            type: 'incorrect-tab-order',
-            selector: 'body',
-            description: 'Focus order does not follow logical reading sequence',
-        });
-    }
-    return issues;
-}
-function detectFocusTraps(url, urlHash) {
-    const traps = [];
-    const hashNum = parseInt(urlHash, 36);
-    const hasModal = url.includes('modal') || url.includes('dialog') || url.includes('popup');
-    const hasForm = url.includes('form') || url.includes('checkout') || url.includes('register');
-    if (hasModal && hashNum % 100 < 8) {
-        traps.push({
-            selector: '.modal, [role="dialog"]',
-            description: 'Modal dialog may trap focus without escape mechanism',
-            escapePath: 'Ensure Escape key closes modal and focus returns to trigger element',
-        });
-    }
-    if (hasForm && hashNum % 100 < 5) {
-        traps.push({
-            selector: 'form .autocomplete, form .datepicker',
-            description: 'Form widget may trap keyboard focus',
-            escapePath: 'Add keyboard navigation (Tab/Escape) to exit widget',
-        });
-    }
-    return traps;
-}
-// ============================================================================
 // URL Hashing Utility
 // ============================================================================
 /**

package/dist/domains/visual-accessibility/services/accessibility-tester.d.ts

@@ -3,9 +3,10 @@
  * Implements WCAG 2.2 compliance auditing with browser mode support
  *
  * This service supports multiple modes of operation:
- * 1. Heuristic Mode (default): URL-pattern-based analysis without browser automation
- * 2. Browser Mode (agent-browser): Real DOM inspection via unified browser client
- * 3. Browser Mode (Vibium): Real DOM inspection via Vibium MCP integration
+ * 1. Browser Mode (agent-browser): Real DOM inspection via unified browser client
+ * 2. Browser Mode (Vibium): Real DOM inspection via Vibium MCP integration
+ * 3. Not measured: no browser could load the page. The report says so
+ *    (`measured: false`) and carries no findings (#1145).
  *
  * Browser mode provides more accurate results by:
  * - Running actual axe-core accessibility checks in the browser
@@ -15,7 +16,8 @@
  * Browser Client Integration:
  * - Prefers agent-browser when available (supports snapshots and axe-core injection)
  * - Falls back to Vibium if agent-browser unavailable
- * - Uses heuristic mode when no browser tool is available
+ * - Reports "not measured" when no browser tool could audit the page; it never
+ *   guesses findings from the URL (#1145)
  *
  * @module domains/visual-accessibility/services/accessibility-tester
  */
@@ -33,6 +35,7 @@ export interface AccessibilityTesterConfig {
     auditTimeout: number;
     enableColorContrastCheck: boolean;
     enableKeyboardCheck: boolean;
+    /** Synthetic, URL-hash-derived results for tests; always reported unmeasured. */
     simulationMode: boolean;
     useBrowserMode: boolean;
     browserConfig: {
@@ -55,7 +58,12 @@ export declare class AccessibilityTesterService implements IAccessibilityAuditin
     private getBrowserClient;
     audit(url: string, options?: AuditOptions): Promise<Result<AccessibilityReport, Error>>;
     auditElement(url: string, selector: string): Promise<Result<AccessibilityReport, Error>>;
-    private auditWithHeuristics;
+    private measuredReport;
+    private notMeasuredReason;
+    /** A report that says nothing was measured: no violations, no passes, no verdict. */
+    private notMeasuredReport;
+    /** Simulation mode: synthetic results, labelled unmeasured and never stored. */
+    private auditSimulated;
     checkContrast(url: string): Promise<Result<ContrastAnalysis[], Error>>;
     validateWCAGLevel(url: string, level: 'A' | 'AA' | 'AAA'): Promise<Result<WCAGValidationResult, Error>>;
     checkKeyboardNavigation(url: string): Promise<Result<KeyboardNavigationReport, Error>>;