@webability/core 1.7.0 → 1.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PageLike, a as ScanOptions, S as ScanResult, W as WcagLevel, b as SiteTheme, D as DetectedIssue, c as ScanIssue } from './types-CbNyAKbT.cjs';
-export { B as BrowserDetector, F as FixDetector, d as FixIssueType, I as IssueImpact, e as IssueSource, V as VIEWPORT_SIZES, f as ViewportPreset, g as WCAG_BY_ISSUE } from './types-CbNyAKbT.cjs';
+import { P as PageLike, S as ScanOptions, a as ScanResult, W as WcagLevel, b as SiteTheme, F as FixDetector, I as InternalBug, D as DetectedIssue, c as ScanIssue } from './types-g-bI_MhR.cjs';
+export { B as BrowserDetector, d as DEFAULT_JUDGE_BASE_URL, e as DEFAULT_JUDGE_TEXT_MODEL, f as DEFAULT_JUDGE_VISION_MODEL, g as FixIssueType, h as IssueImpact, i as IssueSource, J as JUDGE_DEFAULT_TIMEOUT_MS, j as JUDGE_SYSTEM_PROMPT, k as JudgeChatBody, l as JudgeItem, m as JudgeOptions, n as JudgeRequest, o as JudgeTransport, p as JudgeVerdict, q as JudgedEntry, V as VIEWPORT_SIZES, r as ViewportPreset, s as WCAG_BY_ISSUE, t as buildJudgeChatBody, u as hostedJudgeTransport, v as judgeUndecided, w as openAiCompatibleTransport, x as resetJudgeCache } from './types-g-bI_MhR.cjs';
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
@@ -55,10 +55,55 @@ interface RunDetectorsOptions {
      * page.keyboard those checks mostly land in needs-review anyway.
      */
     skipFocusMutating?: boolean;
+    /** Test seam: extra detectors run serially after the focus detectors, each guarded. */
+    extraSerialDetectors?: FixDetector[];
+    /** Out: invariant-P entries (state a detector left behind, unmarked injections). */
+    internalBugs?: InternalBug[];
 }
 declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[], options?: RunDetectorsOptions): Promise<DetectedIssue[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
+declare const REASON_TEXT: {
+    readonly 'not-found': "selector matched no elements";
+    readonly 'not-verifiable': "not checked by any WebAbility tool";
+    readonly unknown_rule: "not a known rule id";
+    readonly 'unsupported-selector': "selectors that pierce shadow DOM (\">>>\") or iframes cannot be scoped by verify_fix";
+};
+/** Shadow-piercing / frame-piercing selector joiners (axe-style `>>>`, `>>`). */
+declare function isPiercingSelector(selector: string): boolean;
+interface CoverageSources {
+    axeRules: () => Array<{
+        tags?: string[];
+    }> | Promise<Array<{
+        tags?: string[];
+    }>>;
+    detectorCriteria: () => readonly string[];
+    /** Every rule id verify_fix accepts as `wcag` besides a criterion: axe ids + detector issue types. */
+    ruleIds: () => readonly string[] | Promise<readonly string[]>;
+}
+/** Union of every engine's criteria. Throws if any registry cannot be read. */
+declare function coveredCriteria(sources?: CoverageSources): Promise<Set<string>>;
+type Verifiability = {
+    verifiable: true;
+} | {
+    verifiable: false;
+    reason: 'not-verifiable';
+};
+/** Fail closed: empty or unbuildable coverage, or an uncovered criterion, is not-verifiable. */
+declare function criterionVerifiability(wcag: string, sources?: CoverageSources): Promise<Verifiability>;
+interface VerifyFixRefusal {
+    reason: keyof typeof REASON_TEXT;
+    text: string;
+    isError?: boolean;
+}
+/**
+ * The pre-scan refusals verify_fix applies, in one place: a rule id no engine
+ * knows (an unknown id matches nothing, which would read as VERIFIED), a
+ * criterion no engine can fail, and a selector that crosses a shadow root or
+ * iframe. Returns null when verification may proceed.
+ */
+declare function verifyFixRefusal(wcag: string | undefined, selector: string, sources?: CoverageSources): Promise<VerifyFixRefusal | null>;
+
 interface AxeViolation {
     id: string;
     impact: string;
@@ -74,6 +119,17 @@ interface AxeViolation {
             data?: {
                 messageKey?: string;
             };
+            relatedNodes?: Array<{
+                target?: unknown;
+            }>;
+        }>;
+        none?: Array<{
+            data?: {
+                messageKey?: string;
+            };
+            relatedNodes?: Array<{
+                target?: unknown;
+            }>;
         }>;
     }>;
 }
@@ -163,4 +219,4 @@ interface DevSuggestion {
 }
 declare function generateDevSuggestion(issue: ScanIssue, framework: Framework, elementClasses?: string, fgColor?: string, bgColor?: string): DevSuggestion;
 
-export { type ContrastSuggestion, DetectedIssue, type DevSuggestion, type Framework, type FrameworkInfo, PageLike, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, WCAG_LEVEL_MAP, WcagLevel, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, issueLevel, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport, withinLevel };
+export { type ContrastSuggestion, type CoverageSources, DetectedIssue, type DevSuggestion, FixDetector, type Framework, type FrameworkInfo, InternalBug, PageLike, REASON_TEXT, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, type Verifiability, WCAG_LEVEL_MAP, WcagLevel, coveredCriteria, criterionVerifiability, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, isPiercingSelector, issueLevel, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport, verifyFixRefusal, withinLevel };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PageLike, a as ScanOptions, S as ScanResult, W as WcagLevel, b as SiteTheme, D as DetectedIssue, c as ScanIssue } from './types-CbNyAKbT.js';
-export { B as BrowserDetector, F as FixDetector, d as FixIssueType, I as IssueImpact, e as IssueSource, V as VIEWPORT_SIZES, f as ViewportPreset, g as WCAG_BY_ISSUE } from './types-CbNyAKbT.js';
+import { P as PageLike, S as ScanOptions, a as ScanResult, W as WcagLevel, b as SiteTheme, F as FixDetector, I as InternalBug, D as DetectedIssue, c as ScanIssue } from './types-g-bI_MhR.js';
+export { B as BrowserDetector, d as DEFAULT_JUDGE_BASE_URL, e as DEFAULT_JUDGE_TEXT_MODEL, f as DEFAULT_JUDGE_VISION_MODEL, g as FixIssueType, h as IssueImpact, i as IssueSource, J as JUDGE_DEFAULT_TIMEOUT_MS, j as JUDGE_SYSTEM_PROMPT, k as JudgeChatBody, l as JudgeItem, m as JudgeOptions, n as JudgeRequest, o as JudgeTransport, p as JudgeVerdict, q as JudgedEntry, V as VIEWPORT_SIZES, r as ViewportPreset, s as WCAG_BY_ISSUE, t as buildJudgeChatBody, u as hostedJudgeTransport, v as judgeUndecided, w as openAiCompatibleTransport, x as resetJudgeCache } from './types-g-bI_MhR.js';
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
@@ -55,10 +55,55 @@ interface RunDetectorsOptions {
      * page.keyboard those checks mostly land in needs-review anyway.
      */
     skipFocusMutating?: boolean;
+    /** Test seam: extra detectors run serially after the focus detectors, each guarded. */
+    extraSerialDetectors?: FixDetector[];
+    /** Out: invariant-P entries (state a detector left behind, unmarked injections). */
+    internalBugs?: InternalBug[];
 }
 declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[], options?: RunDetectorsOptions): Promise<DetectedIssue[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
+declare const REASON_TEXT: {
+    readonly 'not-found': "selector matched no elements";
+    readonly 'not-verifiable': "not checked by any WebAbility tool";
+    readonly unknown_rule: "not a known rule id";
+    readonly 'unsupported-selector': "selectors that pierce shadow DOM (\">>>\") or iframes cannot be scoped by verify_fix";
+};
+/** Shadow-piercing / frame-piercing selector joiners (axe-style `>>>`, `>>`). */
+declare function isPiercingSelector(selector: string): boolean;
+interface CoverageSources {
+    axeRules: () => Array<{
+        tags?: string[];
+    }> | Promise<Array<{
+        tags?: string[];
+    }>>;
+    detectorCriteria: () => readonly string[];
+    /** Every rule id verify_fix accepts as `wcag` besides a criterion: axe ids + detector issue types. */
+    ruleIds: () => readonly string[] | Promise<readonly string[]>;
+}
+/** Union of every engine's criteria. Throws if any registry cannot be read. */
+declare function coveredCriteria(sources?: CoverageSources): Promise<Set<string>>;
+type Verifiability = {
+    verifiable: true;
+} | {
+    verifiable: false;
+    reason: 'not-verifiable';
+};
+/** Fail closed: empty or unbuildable coverage, or an uncovered criterion, is not-verifiable. */
+declare function criterionVerifiability(wcag: string, sources?: CoverageSources): Promise<Verifiability>;
+interface VerifyFixRefusal {
+    reason: keyof typeof REASON_TEXT;
+    text: string;
+    isError?: boolean;
+}
+/**
+ * The pre-scan refusals verify_fix applies, in one place: a rule id no engine
+ * knows (an unknown id matches nothing, which would read as VERIFIED), a
+ * criterion no engine can fail, and a selector that crosses a shadow root or
+ * iframe. Returns null when verification may proceed.
+ */
+declare function verifyFixRefusal(wcag: string | undefined, selector: string, sources?: CoverageSources): Promise<VerifyFixRefusal | null>;
+
 interface AxeViolation {
     id: string;
     impact: string;
@@ -74,6 +119,17 @@ interface AxeViolation {
             data?: {
                 messageKey?: string;
             };
+            relatedNodes?: Array<{
+                target?: unknown;
+            }>;
+        }>;
+        none?: Array<{
+            data?: {
+                messageKey?: string;
+            };
+            relatedNodes?: Array<{
+                target?: unknown;
+            }>;
         }>;
     }>;
 }
@@ -163,4 +219,4 @@ interface DevSuggestion {
 }
 declare function generateDevSuggestion(issue: ScanIssue, framework: Framework, elementClasses?: string, fgColor?: string, bgColor?: string): DevSuggestion;
 
-export { type ContrastSuggestion, DetectedIssue, type DevSuggestion, type Framework, type FrameworkInfo, PageLike, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, WCAG_LEVEL_MAP, WcagLevel, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, issueLevel, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport, withinLevel };
+export { type ContrastSuggestion, type CoverageSources, DetectedIssue, type DevSuggestion, FixDetector, type Framework, type FrameworkInfo, InternalBug, PageLike, REASON_TEXT, ScanIssue, ScanOptions, ScanResult, SiteTheme, type TailwindSuggestion, type Verifiability, WCAG_LEVEL_MAP, WcagLevel, coveredCriteria, criterionVerifiability, detectFramework, dismissModals, extractSiteTheme, generateDevSuggestion, getContrastRatio, getWcagLevel, isPiercingSelector, issueLevel, runAxe, runDetectors, scan, solveContrast, suggestTailwindFix, toHtmlReport, verifyFixRefusal, withinLevel };