@webability/core 1.1.2 → 1.1.3

package/dist/index.d.cts

@@ -38,6 +38,15 @@ interface DetectedIssue {
     imageSrc?: string;
     /** Optional: outer HTML snippet (first 300 chars) for Claude context. */
     outerHtml?: string;
+    /**
+     * Detector-side signal that the finding is ambiguous and should land in
+     * `ScanResult.incomplete[]` (e.g. contrast against a gradient). The scanner
+     * propagates this to ScanIssue.confidence so the confidence classifier
+     * doesn't have to reverse-engineer the situation from HTML strings.
+     */
+    needsReview?: boolean;
+    /** Why this finding needs review — surfaced to MCP/SDK consumers. */
+    reviewReason?: string;
 }
 /** Every fix detector must implement this interface. */
 interface FixDetector {
@@ -72,6 +81,15 @@ interface SiteTheme {
 type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
 type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
 type WcagLevel = 'A' | 'AA' | 'AAA';
+/**
+ * Confidence tier for a scan finding. Mirrors axe-core's three-tier output —
+ * `high` is a confirmed violation safe to act on; `needs_review` is ambiguous
+ * (e.g. text on a gradient background, mid-animation opacity, marketing imagery
+ * that may legitimately contain text). Consumers should never auto-apply fixes
+ * to `needs_review` findings — they belong in the `incomplete[]` bucket and
+ * require human judgment.
+ */
+type IssueConfidence = 'high' | 'needs_review';
 interface ScanIssue {
     id: string;
     source: IssueSource;
@@ -82,6 +100,10 @@ interface ScanIssue {
     message: string;
     selector: string;
     html?: string;
+    /** When set, this issue is ambiguous and lives in `ScanResult.incomplete[]`. */
+    confidence?: IssueConfidence;
+    /** Why the classifier demoted this issue. Surfaced to MCP/SDK consumers. */
+    reviewReason?: string;
     fix?: {
         attribute: string;
         currentValue: string;
@@ -92,13 +114,22 @@ interface ScanIssue {
 interface ScanResult {
     url: string;
     timestamp: string;
+    /** High-confidence violations. Safe to surface as bugs. */
     issues: ScanIssue[];
+    /**
+     * Findings the classifier or axe-core flagged as ambiguous. Show to the user
+     * for review — never auto-fix. Empty array (not omitted) when no incompletes,
+     * so consumers can rely on the field.
+     */
+    incomplete: ScanIssue[];
     summary: {
         total: number;
         critical: number;
         serious: number;
         moderate: number;
         minor: number;
+        /** Count of items in `incomplete[]`. */
+        incomplete: number;
     };
     axeResults?: unknown;
 }

package/dist/index.d.ts

@@ -38,6 +38,15 @@ interface DetectedIssue {
     imageSrc?: string;
     /** Optional: outer HTML snippet (first 300 chars) for Claude context. */
     outerHtml?: string;
+    /**
+     * Detector-side signal that the finding is ambiguous and should land in
+     * `ScanResult.incomplete[]` (e.g. contrast against a gradient). The scanner
+     * propagates this to ScanIssue.confidence so the confidence classifier
+     * doesn't have to reverse-engineer the situation from HTML strings.
+     */
+    needsReview?: boolean;
+    /** Why this finding needs review — surfaced to MCP/SDK consumers. */
+    reviewReason?: string;
 }
 /** Every fix detector must implement this interface. */
 interface FixDetector {
@@ -72,6 +81,15 @@ interface SiteTheme {
 type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
 type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
 type WcagLevel = 'A' | 'AA' | 'AAA';
+/**
+ * Confidence tier for a scan finding. Mirrors axe-core's three-tier output —
+ * `high` is a confirmed violation safe to act on; `needs_review` is ambiguous
+ * (e.g. text on a gradient background, mid-animation opacity, marketing imagery
+ * that may legitimately contain text). Consumers should never auto-apply fixes
+ * to `needs_review` findings — they belong in the `incomplete[]` bucket and
+ * require human judgment.
+ */
+type IssueConfidence = 'high' | 'needs_review';
 interface ScanIssue {
     id: string;
     source: IssueSource;
@@ -82,6 +100,10 @@ interface ScanIssue {
     message: string;
     selector: string;
     html?: string;
+    /** When set, this issue is ambiguous and lives in `ScanResult.incomplete[]`. */
+    confidence?: IssueConfidence;
+    /** Why the classifier demoted this issue. Surfaced to MCP/SDK consumers. */
+    reviewReason?: string;
     fix?: {
         attribute: string;
         currentValue: string;
@@ -92,13 +114,22 @@ interface ScanIssue {
 interface ScanResult {
     url: string;
     timestamp: string;
+    /** High-confidence violations. Safe to surface as bugs. */
     issues: ScanIssue[];
+    /**
+     * Findings the classifier or axe-core flagged as ambiguous. Show to the user
+     * for review — never auto-fix. Empty array (not omitted) when no incompletes,
+     * so consumers can rely on the field.
+     */
+    incomplete: ScanIssue[];
     summary: {
         total: number;
         critical: number;
         serious: number;
         moderate: number;
         minor: number;
+        /** Count of items in `incomplete[]`. */
+        incomplete: number;
     };
     axeResults?: unknown;
 }