@dallask/a11y-mcp-srv 1.1.13 → 2.2.0

package/dist/core/normalize-audit-result.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Normalize audit result input so tools that accept "result or URL" receive the same
+ * canonical AuditResult shape that audit_url returns. Handles JSON strings, MCP
+ * response wrappers, batch results, and alternate metadata shapes (e.g. ACE vs axe).
+ */
+import type { AuditResult } from '../types/index.js';
+/**
+ * Normalize audit result input from a client.
+ * - URL string: returns null (caller should run audit).
+ * - JSON string of single result: parses and normalizes.
+ * - MCP wrapper { content: [{ text: "..." }] }: extracts and normalizes.
+ * - Batch { results: [...] }: normalizes first element.
+ * - Plain object: fills missing fields with defaults.
+ *
+ * @param value - Raw value (string, or object from previous tool output).
+ * @returns Normalized AuditResult, or null when value is a URL (run audit) or parsing fails.
+ */
+export declare function normalizeAuditResult(value: unknown): AuditResult | null;
+//# sourceMappingURL=normalize-audit-result.d.ts.map

package/dist/core/normalize-audit-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-audit-result.d.ts","sourceRoot":"","sources":["../../src/core/normalize-audit-result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,mBAAmB,CAAA;AA+G1B;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAkEvE"}

package/dist/core/normalize-audit-result.js

@@ -0,0 +1,173 @@
+/**
+ * Normalize audit result input so tools that accept "result or URL" receive the same
+ * canonical AuditResult shape that audit_url returns. Handles JSON strings, MCP
+ * response wrappers, batch results, and alternate metadata shapes (e.g. ACE vs axe).
+ */
+const DEFAULT_SUMMARY = {
+    totalIssues: 0,
+    score: 0,
+    wcagCompliance: { A: 0, AA: 0, AAA: 0 },
+    byCategory: {},
+    byImpact: {},
+};
+function isUrlString(value) {
+    const t = value.trim();
+    return t.startsWith('http://') || t.startsWith('https://');
+}
+function isJsonLikeString(value) {
+    return value.trim().startsWith('{');
+}
+/**
+ * Build canonical TestMetadata from any raw object (top-level or metadata in various shapes).
+ * Ensures all tools receive the same metadata shape regardless of engine (axe, ACE) or API.
+ */
+function buildCanonicalMetadata(obj) {
+    const meta = obj.metadata != null && typeof obj.metadata === 'object' ? obj.metadata : {};
+    const url = (typeof obj.url === 'string' ? obj.url : undefined) ??
+        (typeof meta.url === 'string' ? meta.url : undefined);
+    const timestamp = (typeof obj.timestamp === 'string' ? obj.timestamp : undefined) ??
+        (typeof meta.timestamp === 'string' ? meta.timestamp : undefined) ??
+        (typeof meta.testDate === 'string' ? meta.testDate : undefined);
+    if (!url && !timestamp && meta.testEngine == null && meta.testRunner == null) {
+        return undefined;
+    }
+    const testEngine = meta.testEngine != null && typeof meta.testEngine === 'object' && !Array.isArray(meta.testEngine)
+        ? {
+            name: String(meta.testEngine.name ?? 'Unknown'),
+            version: String(meta.testEngine.version ?? ''),
+        }
+        : { name: String(meta.testEngine ?? 'Unknown'), version: '' };
+    const testRunner = meta.testRunner != null && typeof meta.testRunner === 'object' && !Array.isArray(meta.testRunner)
+        ? { name: String(meta.testRunner.name ?? 'Unknown') }
+        : { name: String(meta.testRunner ?? 'Unknown') };
+    const env = meta.testEnvironment != null && typeof meta.testEnvironment === 'object' && !Array.isArray(meta.testEnvironment)
+        ? meta.testEnvironment
+        : {};
+    const viewport = typeof meta.viewport === 'string' ? meta.viewport : '';
+    const [w, h] = viewport ? viewport.split('x').map((n) => parseInt(n, 10)) : [env.windowWidth, env.windowHeight];
+    const testEnvironment = {
+        userAgent: String(env.userAgent ?? 'unknown'),
+        windowWidth: typeof w === 'number' && !Number.isNaN(w) ? w : 1280,
+        windowHeight: typeof h === 'number' && !Number.isNaN(h) ? h : 720,
+        orientationType: env.orientationType,
+        orientationAngle: env.orientationAngle,
+    };
+    return {
+        testEngine,
+        testRunner,
+        testEnvironment,
+        timestamp: timestamp ?? new Date().toISOString(),
+        url: url ?? '',
+    };
+}
+/**
+ * Normalize a raw object into the canonical AuditResult shape (same as audit_url returns).
+ * Metadata is always normalized to TestMetadata when present.
+ */
+function normalizeObject(obj) {
+    const prioritizedIssues = Array.isArray(obj.prioritizedIssues) ? obj.prioritizedIssues : [];
+    const quickWins = Array.isArray(obj.quickWins) ? obj.quickWins : [];
+    const criticalBlockers = Array.isArray(obj.criticalBlockers) ? obj.criticalBlockers : [];
+    let summary = DEFAULT_SUMMARY;
+    if (obj.summary != null && typeof obj.summary === 'object') {
+        const s = obj.summary;
+        const wcag = s.wcagCompliance != null && typeof s.wcagCompliance === 'object'
+            ? s.wcagCompliance
+            : { A: 0, AA: 0, AAA: 0 };
+        summary = {
+            totalIssues: typeof s.totalIssues === 'number' ? s.totalIssues : 0,
+            score: typeof s.score === 'number' ? s.score : 0,
+            wcagCompliance: wcag,
+            byCategory: s.byCategory != null && typeof s.byCategory === 'object' && !Array.isArray(s.byCategory)
+                ? s.byCategory
+                : {},
+            byImpact: s.byImpact != null && typeof s.byImpact === 'object' && !Array.isArray(s.byImpact)
+                ? s.byImpact
+                : {},
+        };
+    }
+    const metadata = buildCanonicalMetadata(obj);
+    return {
+        summary,
+        prioritizedIssues,
+        quickWins,
+        criticalBlockers,
+        conversationalSummary: typeof obj.conversationalSummary === 'string' ? obj.conversationalSummary : '',
+        issuesTable: typeof obj.issuesTable === 'string' ? obj.issuesTable : '',
+        appliedFilters: obj.appliedFilters != null && typeof obj.appliedFilters === 'object' ? obj.appliedFilters : undefined,
+        metadata: metadata ?? (obj.metadata != null && typeof obj.metadata === 'object' ? obj.metadata : undefined),
+        rawResults: obj.rawResults,
+        responseStatus: typeof obj.responseStatus === 'number' ? obj.responseStatus : undefined,
+    };
+}
+/**
+ * Normalize audit result input from a client.
+ * - URL string: returns null (caller should run audit).
+ * - JSON string of single result: parses and normalizes.
+ * - MCP wrapper { content: [{ text: "..." }] }: extracts and normalizes.
+ * - Batch { results: [...] }: normalizes first element.
+ * - Plain object: fills missing fields with defaults.
+ *
+ * @param value - Raw value (string, or object from previous tool output).
+ * @returns Normalized AuditResult, or null when value is a URL (run audit) or parsing fails.
+ */
+export function normalizeAuditResult(value) {
+    if (value == null) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (isUrlString(trimmed)) {
+            return null;
+        }
+        if (isJsonLikeString(trimmed)) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                return normalizeAuditResult(parsed);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    if (typeof value !== 'object') {
+        return null;
+    }
+    const obj = value;
+    // MCP response wrapper: { content: [ { type, text } ] }
+    const content = obj.content;
+    if (Array.isArray(content) && content.length > 0) {
+        const first = content[0];
+        if (first != null && typeof first === 'object' && 'text' in first && typeof first.text === 'string') {
+            try {
+                const parsed = JSON.parse(first.text);
+                return normalizeAuditResult(parsed);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    // Batch result from audit_multiple_urls: { results: AuditResult[], ... }
+    const resultsArray = obj.results;
+    if (Array.isArray(resultsArray) && resultsArray.length > 0) {
+        return normalizeAuditResult(resultsArray[0]);
+    }
+    // Wrapped single result: { results: <audit object>, format?: string, ... } (e.g. full tool args passed as results)
+    const singleResult = obj.results;
+    if (singleResult != null &&
+        typeof singleResult === 'object' &&
+        !Array.isArray(singleResult) &&
+        (('summary' in singleResult && singleResult.summary != null) ||
+            ('prioritizedIssues' in singleResult && Array.isArray(singleResult.prioritizedIssues)))) {
+        return normalizeAuditResult(singleResult);
+    }
+    // Plain audit result (single): must look like one (has summary or prioritizedIssues)
+    if ('summary' in obj || 'prioritizedIssues' in obj) {
+        return normalizeObject(obj);
+    }
+    // Empty or unrecognized object: return minimal valid result so callers don't throw
+    return normalizeObject(obj);
+}
+//# sourceMappingURL=normalize-audit-result.js.map

package/dist/core/normalize-audit-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-audit-result.js","sourceRoot":"","sources":["../../src/core/normalize-audit-result.ts"],"names":[],"mappings":"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"}

package/dist/core/result-processor.d.ts

@@ -3,19 +3,36 @@
  * Converts raw accessibility results into structured, prioritized, and human-readable format
  */
 import type { AccessibilityResults, AuditResult, AppliedFilters } from '../types/index.js';
+/** Options passed when processing audit results (e.g. WCAG label used for the audit) */
+export interface ProcessOptions {
+    /** WCAG version and level used for the audit (e.g. "WCAG 2.2 AA"). Used when rule tags are empty. */
+    auditWcagLabel?: string;
+}
+/**
+ * Derive full WCAG label from engine tags (e.g. wcag22aa -> "WCAG 2.2 AA").
+ * Used for display and for audit fallback.
+ */
+export declare function getWcagLabelFromTags(tags: string[]): string;
+/** True if wcagLevel string matches the given level (A, AA, AAA); supports full label e.g. "WCAG 2.2 AA". */
+export declare function wcagLevelMatches(level: string, target: 'A' | 'AA' | 'AAA'): boolean;
+/** Numeric order for sorting by WCAG level (A=3, AA=2, AAA=1). Supports full label e.g. "WCAG 2.2 AA". */
+export declare function wcagLevelOrder(level: string): number;
 /**
  * ResultProcessor class - Formats and processes accessibility results
  */
 export declare class ResultProcessor {
     /**
-     * Get WCAG level from tags
+     * Get WCAG level for display (full label e.g. "WCAG 2.2 AA"). Uses tags when present, else audit fallback.
      */
     private getWCAGLevel;
     /**
-     * Determine impact level from category, rule, and optional engine-reported impact.
-     * When ruleData.impact is set (e.g. from ACE), use it so output matches the browser tool.
+     * Determine impact level from engine-reported impact (axe or ACE native levels).
      */
     private getImpactLevel;
+    /**
+     * Get impact rank for ordering (higher = worse). Uses IMPACT_ORDER.
+     */
+    private impactRank;
     /**
      * Calculate priority score for an issue (higher = more important)
      */
@@ -25,7 +42,7 @@ export declare class ResultProcessor {
      */
     private generateFixSuggestion;
     /**
-     * Generate user impact description
+     * Generate user impact description from engine-native impact level.
      */
     private generateUserImpact;
     /**
@@ -64,6 +81,6 @@ export declare class ResultProcessor {
     /**
      * Process accessibility results into structured audit result
      */
-    process(accessibilityResults: AccessibilityResults, appliedFilters?: AppliedFilters): AuditResult;
+    process(accessibilityResults: AccessibilityResults, appliedFilters?: AppliedFilters, options?: ProcessOptions): AuditResult;
 }
 //# sourceMappingURL=result-processor.d.ts.map

package/dist/core/result-processor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result-processor.d.ts","sourceRoot":"","sources":["../../src/core/result-processor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAEpB,WAAW,EAOX,cAAc,EAEf,MAAM,mBAAmB,CAAA;AAE1B;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiBtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmCzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAwC7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqEzB;;OAEG;IACH,OAAO,CAAC,cAAc;IA8BtB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAmB/B;;OAEG;IACH,OAAO,CAAC,eAAe;IA0BvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6CzB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA4ChC;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAsErC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAqC3B;;OAEG;IACH,OAAO,CACL,oBAAoB,EAAE,oBAAoB,EAC1C,cAAc,CAAC,EAAE,cAAc,GAC9B,WAAW;CAiDf"}
+{"version":3,"file":"result-processor.d.ts","sourceRoot":"","sources":["../../src/core/result-processor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAEpB,WAAW,EAOX,cAAc,EAEf,MAAM,mBAAmB,CAAA;AAG1B,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,qGAAqG;IACrG,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAW3D;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,OAAO,CAInF;AAED,0GAA0G;AAC1G,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAwC7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiFzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAqBtB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAmB/B;;OAEG;IACH,OAAO,CAAC,eAAe;IA0BvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAwChC;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAsErC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAoC3B;;OAEG;IACH,OAAO,CACL,oBAAoB,EAAE,oBAAoB,EAC1C,cAAc,CAAC,EAAE,cAAc,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW;CAiDf"}

package/dist/core/result-processor.js

@@ -2,74 +2,85 @@
  * Result Processor - Formats accessibility results into conversational, actionable format
  * Converts raw accessibility results into structured, prioritized, and human-readable format
  */
+import { IMPACT_ORDER } from '../types/index.js';
+/**
+ * Derive full WCAG label from engine tags (e.g. wcag22aa -> "WCAG 2.2 AA").
+ * Used for display and for audit fallback.
+ */
+export function getWcagLabelFromTags(tags) {
+    if (!tags || tags.length === 0)
+        return 'N/A';
+    const level = tags.some((t) => t.endsWith('aaa')) ? 'AAA'
+        : tags.some((t) => t.endsWith('aa')) ? 'AA'
+            : tags.some((t) => t.endsWith('a')) ? 'A'
+                : null;
+    if (!level)
+        return 'N/A';
+    if (tags.some((t) => t.startsWith('wcag22')))
+        return `WCAG 2.2 ${level}`;
+    if (tags.some((t) => t.startsWith('wcag21')))
+        return `WCAG 2.1 ${level}`;
+    if (tags.some((t) => t.startsWith('wcag2')))
+        return `WCAG 2.0 ${level}`;
+    return `WCAG ${level}`;
+}
+/** True if wcagLevel string matches the given level (A, AA, AAA); supports full label e.g. "WCAG 2.2 AA". */
+export function wcagLevelMatches(level, target) {
+    if (target === 'AAA')
+        return level === 'AAA' || level.endsWith(' AAA');
+    if (target === 'AA')
+        return level === 'AA' || (level.endsWith(' AA') && !level.endsWith(' AAA'));
+    return level === 'A' || (level.endsWith(' A') && !level.endsWith(' AA'));
+}
+/** Numeric order for sorting by WCAG level (A=3, AA=2, AAA=1). Supports full label e.g. "WCAG 2.2 AA". */
+export function wcagLevelOrder(level) {
+    if (wcagLevelMatches(level, 'A'))
+        return 3;
+    if (wcagLevelMatches(level, 'AA'))
+        return 2;
+    if (wcagLevelMatches(level, 'AAA'))
+        return 1;
+    return 0;
+}
 /**
  * ResultProcessor class - Formats and processes accessibility results
  */
 export class ResultProcessor {
     /**
-     * Get WCAG level from tags
+     * Get WCAG level for display (full label e.g. "WCAG 2.2 AA"). Uses tags when present, else audit fallback.
      */
-    getWCAGLevel(tags) {
-        if (tags.includes('wcag2aaa') || tags.includes('wcag21aaa'))
-            return 'AAA';
-        if (tags.includes('wcag2aa') || tags.includes('wcag21aa'))
-            return 'AA';
-        if (tags.includes('wcag2a') || tags.includes('wcag21a'))
-            return 'A';
-        return 'N/A';
+    getWCAGLevel(tags, auditWcagLabel) {
+        if (tags && tags.length > 0)
+            return getWcagLabelFromTags(tags);
+        return auditWcagLabel ?? 'N/A';
     }
     /**
-     * Determine impact level from category, rule, and optional engine-reported impact.
-     * When ruleData.impact is set (e.g. from ACE), use it so output matches the browser tool.
+     * Determine impact level from engine-reported impact (axe or ACE native levels).
      */
-    getImpactLevel(category, ruleId, ruleData) {
-        // Use engine-reported impact (ACE or axe) when available
-        if (ruleData?.impact) {
-            return ruleData.impact;
-        }
-        // Fallback for rules without explicit impact (e.g. older axe results)
-        if (category === 'error')
-            return 'violation';
-        if (category === 'contrast')
-            return 'needs-review';
-        if (ruleId.includes('label') || ruleId.includes('form'))
-            return 'needs-review';
-        if (ruleId.includes('alt'))
-            return 'violation';
-        return 'recommendation';
+    getImpactLevel(_category, _ruleId, ruleData) {
+        return ruleData?.impact ?? 'moderate';
+    }
+    /**
+     * Get impact rank for ordering (higher = worse). Uses IMPACT_ORDER.
+     */
+    impactRank(impact) {
+        return IMPACT_ORDER[impact.toLowerCase()] ?? 2;
     }
     /**
      * Calculate priority score for an issue (higher = more important)
      */
     calculatePriority(issue) {
         let priority = 0;
-        // Impact weighting (IBM severity order)
-        switch (issue.impact) {
-            case 'violation':
-                priority += 100;
-                break;
-            case 'needs-review':
-                priority += 50;
-                break;
-            case 'recommendation':
-                priority += 25;
-                break;
-            case 'minor':
-                priority += 10;
-                break;
-        }
-        // WCAG level weighting (AAA > AA > A)
-        switch (issue.wcagLevel) {
-            case 'AAA':
-                priority += 30;
-                break;
-            case 'AA':
-                priority += 20;
-                break;
-            case 'A':
-                priority += 10;
-                break;
-        }
+        // Impact weighting (axe: critical/serious/moderate/minor; ACE: violation/potentialviolation/...)
+        priority += this.impactRank(issue.impact) * 25;
+        // WCAG level weighting (AAA > AA > A); support full label e.g. "WCAG 2.2 AA"
+        const level = issue.wcagLevel;
+        if (level.endsWith('AAA'))
+            priority += 30;
+        else if (level.endsWith('AA'))
+            priority += 20;
+        else if (level.endsWith('A'))
+            priority += 10;
         return priority;
     }
     /**
@@ -109,16 +120,17 @@ export class ResultProcessor {
         };
     }
     /**
-     * Generate user impact description
+     * Generate user impact description from engine-native impact level.
      */
     generateUserImpact(_ruleId, impact) {
-        if (impact === 'violation') {
-            return 'This is a definite accessibility failure that prevents users with disabilities from accessing content or functionality.';
+        const rank = this.impactRank(impact);
+        if (rank >= 5) {
+            return 'This is a definite or likely accessibility failure that prevents users with disabilities from accessing content or functionality.';
         }
-        if (impact === 'needs-review') {
+        if (rank >= 4) {
             return 'This potential issue needs manual review — it may significantly impact users with disabilities.';
         }
-        if (impact === 'recommendation') {
+        if (rank >= 3) {
             return 'This is a best-practice recommendation that improves accessibility for users with disabilities.';
         }
         return 'This may cause minor inconveniences for some users.';
@@ -126,8 +138,9 @@ export class ResultProcessor {
     /**
      * Process accessibility violations into prioritized issues
      */
-    processViolations(violations, _appliedFilters) {
+    processViolations(violations, _appliedFilters, options) {
         const issues = [];
+        const auditWcagLabel = options?.auditWcagLabel;
         Object.entries(violations).forEach(([categoryKey, category]) => {
             if (!category || !category.items) {
                 return;
@@ -144,8 +157,16 @@ export class ResultProcessor {
                     const element = domInfo
                         ? `${domInfo.tagName || 'Unknown'}${domInfo.id ? `#${domInfo.id}` : ''}${domInfo.className ? `.${domInfo.className.replace(/\s+/g, '.')}` : ''}`
                         : xpath;
+                    // Build a selector that identifies the exact element: tag + optional id + optional classes.
+                    // Never leave empty: use tag when no class/id so the column always has a value.
+                    const tag = domInfo?.tagName || 'element';
+                    const idPart = domInfo?.id ? `#${domInfo.id}` : '';
+                    const classPart = domInfo?.className != null && domInfo.className !== ''
+                        ? '.' + String(domInfo.className).trim().replace(/\s+/g, '.')
+                        : '';
+                    const classSelector = tag + idPart + classPart;
                     const tags = ruleData.tags || [];
-                    const wcagLevel = this.getWCAGLevel(tags);
+                    const wcagLevel = this.getWCAGLevel(tags, auditWcagLabel);
                     const impact = this.getImpactLevel(categoryKey, ruleId, ruleData);
                     const fix = this.generateFixSuggestion(ruleId, categoryKey, element, xpath, domInfo);
                     const userImpact = this.generateUserImpact(ruleId, impact);
@@ -157,6 +178,7 @@ export class ResultProcessor {
                         tags,
                         element,
                         xpath,
+                        classSelector,
                         fix,
                         userImpact,
                         priority: 0, // Will be calculated after all issues are collected
@@ -184,22 +206,17 @@ export class ResultProcessor {
         }
         // Base score starts at 100
         let score = 100;
-        // Deduct points based on issues
+        // Deduct points based on impact (axe/ACE native levels via IMPACT_ORDER)
         issues.forEach((issue) => {
-            switch (issue.impact) {
-                case 'violation':
-                    score -= 5;
-                    break;
-                case 'needs-review':
-                    score -= 3;
-                    break;
-                case 'recommendation':
-                    score -= 1;
-                    break;
-                case 'minor':
-                    score -= 0.5;
-                    break;
-            }
+            const rank = this.impactRank(issue.impact);
+            if (rank >= 5)
+                score -= 5;
+            else if (rank >= 4)
+                score -= 3;
+            else if (rank >= 3)
+                score -= 1;
+            else
+                score -= 0.5;
         });
         // Ensure score doesn't go below 0
         return Math.max(0, Math.round(score));
@@ -208,9 +225,9 @@ export class ResultProcessor {
      * Calculate WCAG compliance percentages
      */
     calculateWCAGCompliance(issues) {
-        const levelA = issues.filter((i) => i.wcagLevel === 'A');
-        const levelAA = issues.filter((i) => i.wcagLevel === 'AA');
-        const levelAAA = issues.filter((i) => i.wcagLevel === 'AAA');
+        const levelA = issues.filter((i) => wcagLevelMatches(i.wcagLevel, 'A'));
+        const levelAA = issues.filter((i) => wcagLevelMatches(i.wcagLevel, 'AA'));
+        const levelAAA = issues.filter((i) => wcagLevelMatches(i.wcagLevel, 'AAA'));
         // Calculate compliance as percentage (100% - violation percentage)
         // This is a simplified calculation - in reality, we'd need to know total criteria
         const totalIssues = issues.length;
@@ -259,10 +276,10 @@ export class ResultProcessor {
         });
         ruleGroups.forEach((groupIssues, ruleId) => {
             // Quick wins are issues that:
-            // 1. Have high impact (critical or serious)
+            // 1. Have high impact (axe: critical/serious; ACE: violation/potentialviolation)
             // 2. Are easy to fix (have clear fix suggestions)
             // 3. Affect multiple elements (batch fix opportunity)
-            const highImpactIssues = groupIssues.filter((i) => i.impact === 'violation' || i.impact === 'needs-review');
+            const highImpactIssues = groupIssues.filter((i) => this.impactRank(i.impact) >= 5);
             if (highImpactIssues.length > 0 && groupIssues.length > 1) {
                 const firstIssue = groupIssues[0];
                 quickWins.push({
@@ -277,8 +294,7 @@ export class ResultProcessor {
         });
         // Sort by impact and number of affected elements
         quickWins.sort((a, b) => {
-            const impactOrder = { violation: 3, 'needs-review': 2, recommendation: 1, minor: 0 };
-            const impactDiff = (impactOrder[b.impact] ?? 0) - (impactOrder[a.impact] ?? 0);
+            const impactDiff = this.impactRank(b.impact) - this.impactRank(a.impact);
             if (impactDiff !== 0)
                 return impactDiff;
             return b.affectedElements - a.affectedElements;
@@ -299,12 +315,10 @@ export class ResultProcessor {
             ruleGroups.get(issue.ruleId).push(issue);
         });
         ruleGroups.forEach((groupIssues, ruleId) => {
-            // Critical blockers are:
-            // 1. Definite violations (IBM 'violation' level)
-            // 2. WCAG Level A violations (legal requirement)
-            const violationIssues = groupIssues.filter((i) => i.impact === 'violation');
-            const levelAIssues = groupIssues.filter((i) => i.wcagLevel === 'A');
-            if (violationIssues.length > 0 || levelAIssues.length > 0) {
+            // Critical blockers: high impact (axe critical/serious; ACE violation/potentialviolation) or WCAG Level A
+            const highImpactIssues = groupIssues.filter((i) => this.impactRank(i.impact) >= 5);
+            const levelAIssues = groupIssues.filter((i) => wcagLevelMatches(i.wcagLevel, 'A'));
+            if (highImpactIssues.length > 0 || levelAIssues.length > 0) {
                 const firstIssue = groupIssues[0];
                 blockers.push({
                     ruleId,
@@ -316,14 +330,12 @@ export class ResultProcessor {
                 });
             }
         });
-        // Sort by WCAG level (A first) then IBM severity
+        // Sort by WCAG level (A first) then impact rank
         blockers.sort((a, b) => {
-            const levelOrder = { A: 3, AA: 2, AAA: 1 };
-            const levelDiff = (levelOrder[b.wcagLevel] ?? 0) - (levelOrder[a.wcagLevel] ?? 0);
+            const levelDiff = wcagLevelOrder(b.wcagLevel) - wcagLevelOrder(a.wcagLevel);
             if (levelDiff !== 0)
                 return levelDiff;
-            const impactOrder = { violation: 3, 'needs-review': 2, recommendation: 1, minor: 0 };
-            return (impactOrder[b.impact] ?? 0) - (impactOrder[a.impact] ?? 0);
+            return this.impactRank(b.impact) - this.impactRank(a.impact);
         });
         return blockers;
     }
@@ -395,12 +407,14 @@ export class ResultProcessor {
             return '| Severity | Rule | Description | WCAG | Element |\n|---|---|---|---|---|\n| — | — | No issues found | — | — |';
         }
         const severityIcon = (impact) => {
-            switch (impact) {
-                case 'violation': return '🚫 Violation';
-                case 'needs-review': return '⚠️ Needs Review';
-                case 'recommendation': return 'ℹ️ Recommendation';
-                default: return impact;
-            }
+            const rank = IMPACT_ORDER[impact.toLowerCase()] ?? 2;
+            if (rank >= 5)
+                return `🚫 ${impact}`;
+            if (rank >= 4)
+                return `⚠️ ${impact}`;
+            if (rank >= 3)
+                return `ℹ️ ${impact}`;
+            return impact;
         };
         const truncate = (s, max = 80) => s.length > max ? s.substring(0, max - 1) + '…' : s;
         const escape = (s) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
@@ -421,11 +435,11 @@ export class ResultProcessor {
     /**
      * Process accessibility results into structured audit result
      */
-    process(accessibilityResults, appliedFilters) {
+    process(accessibilityResults, appliedFilters, options) {
         // Use filtered results if available, otherwise use original
         const violations = accessibilityResults.violations;
         // Process violations into prioritized issues
-        const issues = this.processViolations(violations, appliedFilters);
+        const issues = this.processViolations(violations, appliedFilters, options);
         // Calculate metrics
         const score = this.calculateScore(issues);
         const wcagCompliance = this.calculateWCAGCompliance(issues);