@diegovelasquezweb/a11y-engine 0.8.4 → 0.9.0

package/README.md

@@ -1,4 +1,4 @@
-# @diegovelasquezweb/a11y-engine
+# a11y Engine
 
 [![npm](https://img.shields.io/npm/v/@diegovelasquezweb/a11y-engine)](https://www.npmjs.com/package/@diegovelasquezweb/a11y-engine)
 
@@ -15,6 +15,7 @@ Accessibility automation engine for web applications. It orchestrates multi engi
 | **AI enrichment** | Optional Claude-powered analysis that adds contextual fix suggestions based on detected stack, repo structure, and finding patterns |
 | **Report generation** | Produces HTML dashboard, PDF compliance report, manual testing checklist, and Markdown remediation guide |
 | **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect. Works with local paths or remote GitHub repos |
+| **Knowledge API** | Exposes WCAG conformance levels, severity definitions, persona profiles, glossary, scanner help, and documentation |
 
 ## Installation
 
@@ -40,12 +41,6 @@ import {
   getChecklist,
   getRemediationGuide,
   getSourcePatterns,
-  getScannerHelp,
-  getPersonaReference,
-  getUiHelp,
-  getConformanceLevels,
-  getWcagPrinciples,
-  getSeverityLevels,
   getKnowledge,
 } from "@diegovelasquezweb/a11y-engine";
 ```
@@ -121,19 +116,21 @@ These functions render final artifacts from scan payload data.
 
 ### Knowledge API
 
-These functions expose scanner help content, persona explanations, conformance levels, and UI copy so frontends or agents can render guidance from engine-owned data.
+Returns all accessibility knowledge in a single call: scanner help, persona profiles, concepts, glossary, documentation, conformance levels, WCAG principles, and severity definitions.
 
-| Function | Returns | Description |
-| :--- | :--- | :--- |
-| `getScannerHelp(options?)` | `{ locale, version, title, engines, options }` | Scanner option and engine help metadata |
-| `getPersonaReference(options?)` | `{ locale, version, personas }` | Persona labels, descriptions, and mapping hints |
-| `getUiHelp(options?)` | `{ locale, version, concepts, glossary }` | Shared concept definitions and glossary entries |
-| `getConformanceLevels(options?)` | `{ locale, version, conformanceLevels }` | WCAG conformance level definitions with axe tag mappings |
-| `getWcagPrinciples(options?)` | `{ locale, version, wcagPrinciples }` | The four WCAG principles with criterion prefix patterns |
-| `getSeverityLevels(options?)` | `{ locale, version, severityLevels }` | Severity level definitions with labels and ordering |
-| `getKnowledge(options?)` | Full knowledge pack | Combines all knowledge APIs into a single response for UI or agent flows |
-
-See [API Reference](docs/api-reference.md) for exact options and return types.
+```ts
+const knowledge = getKnowledge({ locale: "en" });
+// knowledge.scanner          → engine and option descriptions
+// knowledge.personas         → persona labels and descriptions
+// knowledge.concepts         → concept definitions
+// knowledge.glossary         → accessibility glossary
+// knowledge.docs             → documentation articles
+// knowledge.conformanceLevels → A/AA/AAA with axe tag mappings
+// knowledge.wcagPrinciples   → the four WCAG principles
+// knowledge.severityLevels   → Critical/Serious/Moderate/Minor definitions
+```
+
+See [API Reference](docs/api-reference.md) for the full `EngineKnowledge` shape.
 
 ## CLI
 

package/docs/api-reference.md

@@ -353,95 +353,28 @@ Returns: `Promise<SourcePatternResult>`
 
 ## Knowledge API
 
-These functions expose engine-owned content for UIs and agents to render. All accept an optional `{ locale?: string }` option (default: `"en"`).
-
 ### `getKnowledge(options?)`
 
-Returns the full knowledge pack — combines all knowledge functions into one call. Useful for pre-loading UI help content.
+Returns all accessibility knowledge in a single call. Accepts an optional `{ locale?: string }` option (default: `"en"`).
 
 ```ts
 import { getKnowledge } from "@diegovelasquezweb/a11y-engine";
 
 const knowledge = getKnowledge({ locale: "en" });
-
-// knowledge.scanner         → scan options help and engine descriptions
-// knowledge.personas        → persona labels, icons, descriptions
-// knowledge.concepts        → UI concept definitions
-// knowledge.glossary        → accessibility glossary
-// knowledge.conformanceLevels → WCAG A/AA/AAA definitions with axe tags
-// knowledge.wcagPrinciples  → the 4 WCAG principles
-// knowledge.severityLevels  → Critical/Serious/Moderate/Minor definitions
-```
-
-Returns: `EngineKnowledge`
-
----
-
-### `getScannerHelp(options?)`
-
-Returns scan option descriptions, allowed values, and engine metadata — used to render Advanced Settings UI.
-
-```ts
-const help = getScannerHelp();
-// help.engines → [{ id: "axe", label: "axe-core", description: "..." }, ...]
-// help.options → [{ id: "maxRoutes", label: "Max Routes", type: "number", ... }, ...]
-```
-
----
-
-### `getPersonaReference(options?)`
-
-Returns persona labels, descriptions, and disability group definitions.
-
-```ts
-const ref = getPersonaReference();
-// ref.personas → [{ id: "screenReader", label: "Screen Readers", icon: "...", description: "..." }, ...]
-```
-
----
-
-### `getUiHelp(options?)`
-
-Returns shared concept definitions and a glossary of accessibility terms.
-
-```ts
-const ui = getUiHelp();
-// ui.concepts  → { wcag: "...", aria: "...", ... }
-// ui.glossary  → [{ term: "ARIA", definition: "..." }, ...]
-```
-
----
-
-### `getConformanceLevels(options?)`
-
-Returns WCAG conformance level definitions with their corresponding axe-core tag sets.
-
-```ts
-const { conformanceLevels } = getConformanceLevels();
-// conformanceLevels[0] → { id: "AA", label: "WCAG 2.2 AA", axeTags: ["wcag2a", "wcag2aa", ...] }
-```
-
----
-
-### `getWcagPrinciples(options?)`
-
-Returns the four WCAG principles (Perceivable, Operable, Understandable, Robust) with criterion prefix patterns.
-
-```ts
-const { wcagPrinciples } = getWcagPrinciples();
-// wcagPrinciples[0] → { id: "perceivable", label: "Perceivable", prefix: "1.", description: "..." }
 ```
 
----
-
-### `getSeverityLevels(options?)`
-
-Returns severity level definitions with labels, descriptions, and ordering.
-
-```ts
-const { severityLevels } = getSeverityLevels();
-// severityLevels[0] → { id: "Critical", label: "Critical", order: 0, description: "..." }
-```
+**Returns:** `EngineKnowledge`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `scanner` | `{ title, engines, options }` | Scan option descriptions, allowed values, and engine metadata |
+| `personas` | `PersonaReferenceItem[]` | Persona labels, icons, descriptions, and mapped rules |
+| `concepts` | `Record<string, ConceptEntry>` | Concept definitions with title, body, and context |
+| `glossary` | `GlossaryEntry[]` | Accessibility term definitions |
+| `docs` | `KnowledgeDocs` | Documentation articles organized by section and group |
+| `conformanceLevels` | `ConformanceLevel[]` | WCAG A/AA/AAA definitions with axe-core tag mappings |
+| `wcagPrinciples` | `WcagPrinciple[]` | The four WCAG principles with criterion prefix patterns |
+| `severityLevels` | `SeverityLevel[]` | Critical/Serious/Moderate/Minor definitions with ordering |
 
 ---
 

package/package.json

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

package/src/ai/claude.mjs

@@ -236,7 +236,7 @@ async function fetchSourceFilesForFindings(findings, repoUrl, githubToken) {
       try {
         const content = await fetchRepoFile(repoUrl, filePath, githubToken);
         if (content) sourceFiles[filePath] = content;
-      } catch { /* non-fatal */ }
+      } catch { }
     }
   }
 

package/src/ai/enrich.mjs

@@ -74,6 +74,6 @@ async function main() {
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   main().catch((err) => {
     log.warn(`AI enrichment failed (non-fatal): ${err.message}`);
-    process.exit(0); // non-fatal — never block the pipeline
+    process.exit(0);
   });
 }

package/src/index.d.mts

@@ -449,18 +449,6 @@ export function getSourcePatterns(
   options?: SourcePatternOptions
 ): Promise<SourcePatternResult>;
 
-export function getScannerHelp(options?: KnowledgeOptions): ScannerHelp;
-
-export function getPersonaReference(options?: KnowledgeOptions): PersonaReference;
-
-export function getUiHelp(options?: KnowledgeOptions): UiHelp;
-
-export function getConformanceLevels(options?: KnowledgeOptions): ConformanceLevelsResult;
-
-export function getWcagPrinciples(options?: KnowledgeOptions): WcagPrinciplesResult;
-
-export function getSeverityLevels(options?: KnowledgeOptions): SeverityLevelsResult;
-
 export function getKnowledge(options?: KnowledgeOptions): EngineKnowledge;
 
 export const DEFAULT_AI_SYSTEM_PROMPT: string;

package/src/index.mjs

@@ -7,9 +7,7 @@
 import { ASSET_PATHS, loadAssetJson } from "./core/asset-loader.mjs";
 export { DEFAULT_AI_SYSTEM_PROMPT } from "./ai/claude.mjs";
 
-// ---------------------------------------------------------------------------
 // Lazy-loaded asset cache
-// ---------------------------------------------------------------------------
 
 let _intelligence = null;
 let _pa11yConfig = null;
@@ -59,9 +57,7 @@ function resolveKnowledgeLocale(locale = "en") {
   return "en";
 }
 
-// ---------------------------------------------------------------------------
 // Pa11y rule canonicalization (internal)
-// ---------------------------------------------------------------------------
 
 function normalizePa11yToken(value) {
   return value
@@ -98,9 +94,7 @@ function mapPa11yRuleToCanonical(ruleId, sourceRuleId = null, checkData = null)
   return ruleId;
 }
 
-// ---------------------------------------------------------------------------
 // Raw finding normalization (internal)
-// ---------------------------------------------------------------------------
 
 const SEVERITY_ORDER = { Critical: 1, Serious: 2, Moderate: 3, Minor: 4 };
 
@@ -170,9 +164,7 @@ function normalizeSingleFinding(item, index, screenshotUrlBuilder) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Finding enrichment
-// ---------------------------------------------------------------------------
 
 /**
  * Normalizes and enriches raw findings with intelligence data.
@@ -189,19 +181,16 @@ export function getFindings(input, options = {}) {
   const { screenshotUrlBuilder = null } = options;
   const rules = getIntelligence().rules || {};
 
-  // If AI enrichment ran, return those findings directly (already normalized + enriched)
   if (input?.ai_enriched_findings?.length > 0 && !screenshotUrlBuilder) {
     return input.ai_enriched_findings;
   }
 
   const rawFindings = input?.findings || [];
 
-  // Normalize raw findings
   const normalized = rawFindings.map((item, index) =>
     normalizeSingleFinding(item, index, screenshotUrlBuilder)
   );
 
-  // Enrich with intelligence and output camelCase-only findings
   const enriched = normalized.map((finding) => {
     const canonical = mapPa11yRuleToCanonical(
       finding.rule_id,
@@ -209,7 +198,6 @@ export function getFindings(input, options = {}) {
       finding.check_data,
     );
 
-    // Build camelCase-only enriched finding
     const enrichedFinding = {
       id: finding.id,
       ruleId: canonical,
@@ -281,7 +269,6 @@ export function getFindings(input, options = {}) {
     return enrichedFinding;
   });
 
-  // Sort by severity then by ID
   enriched.sort((a, b) => {
     const sa = SEVERITY_ORDER[a.severity] ?? 99;
     const sb = SEVERITY_ORDER[b.severity] ?? 99;
@@ -292,9 +279,7 @@ export function getFindings(input, options = {}) {
   return enriched;
 }
 
-// ---------------------------------------------------------------------------
 // Score computation (internal)
-// ---------------------------------------------------------------------------
 
 function getComplianceScore(totals) {
   const config = getComplianceConfig();
@@ -325,9 +310,7 @@ function getComplianceScore(totals) {
   return { score, label, wcagStatus };
 }
 
-// ---------------------------------------------------------------------------
 // Persona grouping (internal)
-// ---------------------------------------------------------------------------
 
 function getPersonaGroups(findings) {
   const ref = getWcagReference();
@@ -384,9 +367,7 @@ function getPersonaGroups(findings) {
   return groups;
 }
 
-// ---------------------------------------------------------------------------
 // Audit summary
-// ---------------------------------------------------------------------------
 
 /**
  * Computes a complete audit summary from enriched findings: severity totals,
@@ -444,9 +425,7 @@ export function getOverview(findings, payload = null) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Knowledge APIs
-// ---------------------------------------------------------------------------
 
 /**
  * Returns scanner-facing help metadata including engine descriptions,
@@ -455,7 +434,7 @@ export function getOverview(findings, payload = null) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, title: string, engines: object[], options: object[] }}
  */
-export function getScannerHelp(options = {}) {
+function getScannerHelp(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const scanner = payload.locales[locale]?.scanner || { title: "Scanner Help", engines: [], options: [] };
@@ -476,7 +455,7 @@ export function getScannerHelp(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, personas: object[] }}
  */
-export function getPersonaReference(options = {}) {
+function getPersonaReference(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const wcagRef = getWcagReference();
@@ -513,7 +492,7 @@ export function getPersonaReference(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, tooltips: Record<string, object>, glossary: object[] }}
  */
-export function getUiHelp(options = {}) {
+function getConceptsAndGlossary(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const localePayload = payload.locales[locale] || {};
@@ -539,7 +518,7 @@ export function getUiHelp(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, conformanceLevels: object[] }}
  */
-export function getConformanceLevels(options = {}) {
+function getConformanceLevels(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const levels = payload.locales[locale]?.conformanceLevels || [];
@@ -556,7 +535,7 @@ export function getConformanceLevels(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, wcagPrinciples: object[] }}
  */
-export function getWcagPrinciples(options = {}) {
+function getWcagPrinciples(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const principles = payload.locales[locale]?.wcagPrinciples || [];
@@ -573,7 +552,7 @@ export function getWcagPrinciples(options = {}) {
  * @param {{ locale?: string }} [options={}]
  * @returns {{ locale: string, version: string, severityLevels: object[] }}
  */
-export function getSeverityLevels(options = {}) {
+function getSeverityLevels(options = {}) {
   const locale = resolveKnowledgeLocale(options.locale || "en");
   const payload = getKnowledgeData();
   const levels = payload.locales[locale]?.severityLevels || [];
@@ -594,7 +573,7 @@ export const VIEWPORT_PRESETS = [
 export function getKnowledge(options = {}) {
   const scanner = getScannerHelp(options);
   const personas = getPersonaReference(options);
-  const ui = getUiHelp(options);
+  const ui = getConceptsAndGlossary(options);
   const conformance = getConformanceLevels(options);
   const principles = getWcagPrinciples(options);
   const severity = getSeverityLevels(options);
@@ -619,9 +598,7 @@ export function getKnowledge(options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Full audit pipeline
-// ---------------------------------------------------------------------------
 
 /**
  * Runs a complete accessibility audit: crawl + scan (axe + CDP + pa11y) + analyze.
@@ -826,9 +803,7 @@ export async function runAudit(options) {
   return findingsPayload;
 }
 
-// ---------------------------------------------------------------------------
 // Report generation
-// ---------------------------------------------------------------------------
 
 import {
   normalizeFindings as normalizeForReports,
@@ -1011,9 +986,7 @@ export async function getChecklist(options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // HTML Report
-// ---------------------------------------------------------------------------
 
 /**
  * Generates an interactive HTML audit dashboard from raw scan findings.
@@ -1143,9 +1116,7 @@ export async function getHTMLReport(payload, options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Remediation Guide (Markdown)
-// ---------------------------------------------------------------------------
 
 /**
  * Generates a Markdown remediation guide from raw scan findings.
@@ -1171,9 +1142,7 @@ export async function getRemediationGuide(payload, options = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // Source Pattern Scanner
-// ---------------------------------------------------------------------------
 
 /**
  * Scans a project's source code for accessibility patterns not detectable by axe-core.

package/src/pipeline/dom-scanner.mjs

@@ -935,17 +935,12 @@ function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
     }
   }
 
-  // Step 3: pa11y findings — check via canonical rule ID (axe-equivalent) + selector
+  // Step 3: pa11y findings — only skip if same rule + same target already exists
   for (const v of pa11yViolations) {
     const target = v.nodes?.[0]?.target?.[0] || "";
     const key = `${v.id}::${target}`;
 
-    // If pa11y was mapped to an axe rule ID, check if that rule already covers this target
-    const isAxeEquivDuplicate = v.id && seenRuleTargets.has(v.id) && target && seenRuleTargets.get(v.id).has(target);
-    // Also check if any existing finding covers this exact target (broader dedup)
-    const selectorCovered = target && [...seen].some((k) => k.endsWith(`::${target}`));
-
-    if (!seen.has(key) && !isAxeEquivDuplicate && (!selectorCovered || !target)) {
+    if (!seen.has(key)) {
       seen.add(key);
       if (!seenRuleTargets.has(v.id)) seenRuleTargets.set(v.id, new Set());
       seenRuleTargets.get(v.id).add(target);