@diegovelasquezweb/a11y-engine 0.11.0 → 0.11.2

package/docs/api-reference.md

@@ -24,6 +24,7 @@
 - [Constants](#constants)
   - [VIEWPORT_PRESETS](#viewport_presets)
   - [DEFAULT_AI_SYSTEM_PROMPT](#default_ai_system_prompt)
+  - [PM_AI_SYSTEM_PROMPT](#pm_ai_system_prompt)
 
 ---
 
@@ -52,6 +53,7 @@ import {
   getKnowledge,
   VIEWPORT_PRESETS,
   DEFAULT_AI_SYSTEM_PROMPT,
+  PM_AI_SYSTEM_PROMPT,
 } from "@diegovelasquezweb/a11y-engine";
 ```
 
@@ -121,6 +123,7 @@ Returns a `ScanPayload` object consumed by all other functions.
 | `ai.githubToken` | `string` | — | GitHub PAT | Used to fetch source files from the repo for AI context |
 | `ai.model` | `string` | `"claude-haiku-4-5-20251001"` | Anthropic model ID | Claude model to use |
 | `ai.systemPrompt` | `string` | Built-in prompt | — | Overrides the default Claude system prompt for the entire scan |
+| `ai.audience` | `string` | `"dev"` | `"dev"` \| `"pm"` | Controls the AI enrichment tone. `"dev"` generates code-level fixes; `"pm"` generates business impact summaries |
 | `clearCache` | `boolean` | `false` | — | Clear browser cache before each page navigation via CDP `Network.clearBrowserCache`. Ensures fresh results on repeated scans of the same domain |
 | `serverMode` | `boolean` | `false` | — | Enable server/EC2/Docker Chrome launch flags: `--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`, `--disable-gpu`, `--no-zygote`, `--disable-accelerated-2d-canvas`. Use in CI, Docker, or EC2 environments |
 | `onProgress` | `function` | — | — | Callback fired at each pipeline step |
@@ -328,6 +331,11 @@ Returns: `EnrichedFinding[]`
   guardrails: object | null,             // Guardrail metadata from the engine
   checkData: object | null,              // Raw check data from the engine
 
+  // PM audience fields (always present from intelligence DB)
+  pmSummary: string | null,              // One-line business impact for PMs
+  pmImpact: string | null,              // Business/legal/UX consequences
+  pmEffort: string | null,              // "quick-win" | "medium" | "strategic"
+
   // AI enrichment (only when ai.enabled ran)
   aiEnhanced?: boolean,                  // true when AI enriched this finding
   aiFixDescription?: string,             // Claude-generated fix explanation
@@ -671,6 +679,18 @@ Type: `string`
 
 ---
 
+### `PM_AI_SYSTEM_PROMPT`
+
+The system prompt used for PM-audience AI enrichment. Instructs Claude to generate business-oriented summaries instead of developer-focused fixes. Used automatically when `ai.audience` is `"pm"`.
+
+```ts
+import { PM_AI_SYSTEM_PROMPT } from "@diegovelasquezweb/a11y-engine";
+```
+
+Type: `string`
+
+---
+
 > **Note on `ai_enriched_findings` fast path**: When `getFindings()` receives a payload that contains `ai_enriched_findings` and no `screenshotUrlBuilder` option is provided, it returns `ai_enriched_findings` directly without re-normalizing the raw `findings` array. If a `screenshotUrlBuilder` is provided, normalization always runs so paths can be rewritten.
 
 ---

package/docs/intelligence.md

@@ -68,6 +68,9 @@ Each rule entry can include:
 | `cms_notes` | CMS-specific fix guidance |
 | `preferred_relationship_checks` | axe check IDs to prioritize for relationship hints |
 | `guardrails` / `guardrails_overrides` | Must/must-not/verify constraints for automated fixes |
+| `pm.summary` | One-line business impact for PM audience (e.g. "Buttons without labels block screen reader users from key actions") |
+| `pm.impact` | Business/legal/UX consequences for non-technical stakeholders |
+| `pm.effort` | Effort classification: `quick-win`, `medium`, or `strategic` |
 
 When a framework is detected (e.g. `nextjs`), only the relevant framework notes are included in the output. React-based frameworks (`nextjs`, `gatsby`) resolve to `react` notes.
 
@@ -250,6 +253,16 @@ AI enrichment runs automatically when `ANTHROPIC_API_KEY` is present in the envi
 
 The default system prompt instructs Claude to go beyond the generic fix: explain why the issue matters for users, reference the specific selector and violation data, and provide a more complete code example than the engine's default. The prompt can be overridden per-scan via the `AI_SYSTEM_PROMPT` env var or `options.ai.systemPrompt` in the programmatic API.
 
+### PM audience mode
+
+When `ai.audience` is set to `"pm"`, the AI enrichment uses a PM-specific system prompt that generates business-oriented guidance instead of developer-focused fixes. The PM prompt instructs Claude to produce:
+
+- `pmSummary` — one-line business impact in plain language
+- `pmImpact` — 2-3 sentences on legal/compliance/UX consequences
+- `pmEffort` — `quick-win`, `medium`, or `strategic` with time estimate
+
+These AI-generated PM fields override the static PM fields from the intelligence database for Critical and Serious findings, similar to how `fixDescription` overrides the static fix for dev audience.
+
 ## Assets Reference
 
 | Asset | Used by | Purpose |

package/docs/outputs.md

@@ -185,6 +185,9 @@ The primary enriched data artifact. Written by `src/enrichment/analyzer.mjs`. Th
 | `verification_command_fallback` | `string\|null` | Fallback verify command |
 | `pages_affected` | `number\|null` | Number of pages with this violation |
 | `affected_urls` | `string[]\|null` | All URLs where this violation appears |
+| `pm_summary` | `string\|null` | One-line business impact for PM audience. Populated from the intelligence database for all findings. |
+| `pm_impact` | `string\|null` | Business/legal/UX consequences for non-technical stakeholders. |
+| `pm_effort` | `string\|null` | Effort classification: `quick-win`, `medium`, or `strategic`. |
 | `aiEnhanced` | `boolean` | `true` when Claude improved the fix for this finding. Only present on AI-enriched findings. |
 | `ai_fix_description` | `string\|null` | Claude-generated fix description. More specific than `fix_description` — references the actual selector, colors, and violation data. Only present when `aiEnhanced` is `true`. |
 | `ai_fix_code` | `string\|null` | Claude-generated code snippet in the correct framework syntax. Separate from the engine's `fix_code`. Only present when `aiEnhanced` is `true`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "WCAG 2.2 accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/src/pipeline/dom-scanner.mjs

@@ -961,7 +961,7 @@ async function runCdpChecks(page) {
  *   The browser is NOT closed by this function — the caller is responsible for lifecycle.
  * @returns {Promise<Object[]>} Array of pa11y-sourced violations in axe-compatible format.
  */
-async function runPa11yChecks(routeUrl, axeTags, sharedBrowser = null) {
+async function runPa11yChecks(routeUrl, axeTags, sharedBrowser = null, includeWarnings = false) {
   const violations = [];
   const equivalenceMap = PA11Y_CONFIG.equivalenceMap || {};
   const impactMap = {};
@@ -985,6 +985,8 @@ async function runPa11yChecks(routeUrl, axeTags, sharedBrowser = null) {
       timeout: 30000,
       wait: 2000,
       ignore: ignoreList,
+      includeWarnings: Boolean(includeWarnings),
+      includeNotices: false,
     };
 
     if (sharedBrowser) {
@@ -1126,6 +1128,8 @@ function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
 /**
  * Runs the DOM scanner programmatically.
  * @param {Object} options - Scanner configuration (same shape as CLI args object).
+ * @param {boolean} [options.includeWarnings] - Include pa11y WARNING-level issues (default: false). Automatically enabled when includeIncomplete is true.
+ * @param {boolean} [options.includeIncomplete] - Include axe incomplete findings and activates includeWarnings (default: false).
  * @param {{ onProgress?: (step: string, status: string, extra?: object) => void }} [callbacks={}]
  * @returns {Promise<Object>} The scan payload { generated_at, base_url, onlyRule, projectContext, routes }.
  */
@@ -1153,6 +1157,7 @@ export async function runDomScanner(options = {}, callbacks = {}) {
       cdp: options.engines?.cdp !== false,
       pa11y: options.engines?.pa11y !== false,
     },
+    includeWarnings: options.includeWarnings ?? options.includeIncomplete ?? false,
     clearCache: options.clearCache ?? false,
     serverMode: options.serverMode ?? false,
   };
@@ -1409,7 +1414,7 @@ async function _runDomScannerInternal(args) {
             let pa11yPromise = Promise.resolve([]);
             if (args.engines.pa11y) {
               if (!emittedDone.has("pa11y")) writeProgress("pa11y", "running");
-              pa11yPromise = runPa11yChecks(targetUrl, args.axeTags, pa11yBrowser)
+              pa11yPromise = runPa11yChecks(targetUrl, args.axeTags, pa11yBrowser, args.includeWarnings)
                 .then((violations) => {
                   if (!emittedDone.has("pa11y")) {
                     writeProgress("pa11y", "done", { found: violations.length });