@diegovelasquezweb/a11y-engine 0.1.6 → 0.1.8

package/package.json

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

package/scripts/index.d.mts

@@ -1,3 +1,71 @@
+// ---------------------------------------------------------------------------
+// Core types
+// ---------------------------------------------------------------------------
+
+export interface Finding {
+  id: string;
+  rule_id: string;
+  title: string;
+  severity: string;
+  wcag: string;
+  wcag_classification: string | null;
+  wcag_criterion_id: string | null;
+  category: string | null;
+  area: string;
+  url: string;
+  selector: string;
+  primary_selector: string;
+  impacted_users: string;
+  actual: string;
+  expected: string;
+  primary_failure_mode: string | null;
+  relationship_hint: string | null;
+  failure_checks: unknown[];
+  related_context: unknown[];
+  mdn: string | null;
+  fix_description: string | null;
+  fix_code: string | null;
+  fix_code_lang: string | null;
+  recommended_fix: string;
+  evidence: unknown[];
+  total_instances: number | null;
+  effort: string | null;
+  related_rules: string[];
+  screenshot_path: string | null;
+  false_positive_risk: string | null;
+  guardrails: Record<string, unknown> | null;
+  fix_difficulty_notes: string | string[] | null;
+  framework_notes: string | null;
+  cms_notes: string | null;
+  file_search_pattern: string | null;
+  ownership_status: string;
+  ownership_reason: string | null;
+  primary_source_scope: string[];
+  search_strategy: string;
+  managed_by_library: string | null;
+  component_hint: string | null;
+  verification_command: string | null;
+  verification_command_fallback: string | null;
+  check_data: Record<string, unknown> | null;
+  source?: string;
+  source_rule_id?: string | null;
+  pages_affected?: number | null;
+  affected_urls?: string[] | null;
+}
+
+export interface EnrichedFinding extends Finding {
+  ruleId: string;
+  sourceRuleId: string | null;
+  fixDescription: string | null;
+  fixCode: string | null;
+  fixCodeLang: string | null;
+  falsePositiveRisk: string | null;
+  fixDifficultyNotes: string | string[] | null;
+  screenshotPath: string | null;
+  wcagCriterionId: string | null;
+  impactedUsers: string | null;
+}
+
 export interface SeverityTotals {
   Critical: number;
   Serious: number;
@@ -5,45 +73,26 @@ export interface SeverityTotals {
   Minor: number;
 }
 
-export interface ScoreResult {
-  score: number;
-  label: string;
-  wcagStatus: "Pass" | "Conditional Pass" | "Fail";
-}
-
 export interface PersonaGroup {
   label: string;
   count: number;
   icon: string;
 }
 
-export interface EngineAssets {
-  intelligence: Record<string, unknown>;
-  pa11yConfig: Record<string, unknown>;
-  complianceConfig: Record<string, unknown>;
-  wcagReference: Record<string, unknown>;
+export interface AuditSummary {
+  totals: SeverityTotals;
+  score: number;
+  label: string;
+  wcagStatus: "Pass" | "Conditional Pass" | "Fail";
+  personaGroups: Record<string, PersonaGroup>;
 }
 
-export function getAssets(): EngineAssets;
-
-export function mapPa11yRuleToCanonical(
-  ruleId: string,
-  sourceRuleId?: string | null,
-  checkData?: Record<string, unknown> | null
-): string;
-
-export function enrichFindings<T extends Record<string, unknown>>(
-  findings: T[]
-): T[];
-
-export function computeScore(totals: SeverityTotals): ScoreResult;
-
-export function computePersonaGroups(
-  findings: Record<string, unknown>[]
-): Record<string, PersonaGroup>;
+// ---------------------------------------------------------------------------
+// Report types
+// ---------------------------------------------------------------------------
 
 export interface ScanPayload {
-  findings: Record<string, unknown>[];
+  findings: Finding[] | Record<string, unknown>[];
   metadata?: Record<string, unknown>;
 }
 
@@ -52,11 +101,30 @@ export interface ReportOptions {
   target?: string;
 }
 
-export function generatePDF(
+export interface PDFReport {
+  buffer: Buffer;
+  contentType: "application/pdf";
+}
+
+export interface ChecklistReport {
+  html: string;
+  contentType: "text/html";
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function getEnrichedFindings(findings: Finding[]): EnrichedFinding[];
+export function getEnrichedFindings(findings: Record<string, unknown>[]): EnrichedFinding[];
+
+export function getAuditSummary(findings: EnrichedFinding[] | Record<string, unknown>[]): AuditSummary;
+
+export function getPDFReport(
   payload: ScanPayload,
   options?: ReportOptions
-): Promise<Buffer>;
+): Promise<PDFReport>;
 
-export function generateChecklist(
+export function getChecklist(
   options?: Pick<ReportOptions, "baseUrl">
-): Promise<string>;
+): Promise<ChecklistReport>;

package/scripts/index.mjs

@@ -49,7 +49,7 @@ function getWcagReference() {
  * Returns all engine asset data. Lazy-loaded and cached.
  * @returns {{ intelligence: object, pa11yConfig: object, complianceConfig: object, wcagReference: object }}
  */
-export function getAssets() {
+function getAssets() {
   return {
     intelligence: getIntelligence(),
     pa11yConfig: getPa11yConfig(),
@@ -82,7 +82,7 @@ function normalizePa11yToken(value) {
  * @param {object|null} checkData - The check_data object which may contain a `code` field.
  * @returns {string} The canonical rule ID (e.g., "color-contrast").
  */
-export function mapPa11yRuleToCanonical(ruleId, sourceRuleId = null, checkData = null) {
+function mapPa11yRuleToCanonical(ruleId, sourceRuleId = null, checkData = null) {
   const equivalenceMap = getPa11yConfig().equivalenceMap || {};
 
   const checkCode = checkData && typeof checkData === "object" && typeof checkData.code === "string"
@@ -119,7 +119,7 @@ export function mapPa11yRuleToCanonical(ruleId, sourceRuleId = null, checkData =
  * @param {object[]} findings - Array of findings with camelCase keys.
  * @returns {object[]} Enriched findings.
  */
-export function enrichFindings(findings) {
+export function getEnrichedFindings(findings) {
   const rules = getIntelligence().rules || {};
 
   return findings.map((finding) => {
@@ -129,15 +129,24 @@ export function enrichFindings(findings) {
       finding.checkData || finding.check_data || null,
     );
 
+    // Always create camelCase aliases from snake_case fields
     const normalized = {
       ...finding,
       ruleId: canonical,
       rule_id: canonical,
       sourceRuleId: finding.sourceRuleId || finding.source_rule_id || finding.ruleId || finding.rule_id || null,
+      fixDescription: finding.fixDescription ?? finding.fix_description ?? null,
+      fixCode: finding.fixCode ?? finding.fix_code ?? null,
+      fixCodeLang: finding.fixCodeLang ?? finding.fix_code_lang ?? null,
+      falsePositiveRisk: finding.falsePositiveRisk ?? finding.false_positive_risk ?? null,
+      fixDifficultyNotes: finding.fixDifficultyNotes ?? finding.fix_difficulty_notes ?? null,
+      screenshotPath: finding.screenshotPath ?? finding.screenshot_path ?? null,
+      wcagCriterionId: finding.wcagCriterionId ?? finding.wcag_criterion_id ?? null,
+      impactedUsers: finding.impactedUsers ?? finding.impacted_users ?? null,
     };
 
-    if (normalized.fixDescription || normalized.fix_description ||
-        normalized.fixCode || normalized.fix_code) {
+    // If fix data already exists, no need to look up intelligence
+    if (normalized.fixDescription || normalized.fixCode) {
       return normalized;
     }
 
@@ -148,27 +157,22 @@ export function enrichFindings(findings) {
       ...normalized,
       category: normalized.category ?? info.category ?? null,
       fixDescription: info.fix?.description ?? null,
-      fix_description: info.fix?.description ?? null,
+      fix_description: info.fix?.description ?? normalized.fix_description ?? null,
       fixCode: info.fix?.code ?? null,
-      fix_code: info.fix?.code ?? null,
-      falsePositiveRisk: normalized.falsePositiveRisk ?? normalized.false_positive_risk ?? info.false_positive_risk ?? null,
+      fix_code: info.fix?.code ?? normalized.fix_code ?? null,
+      falsePositiveRisk: normalized.falsePositiveRisk ?? info.false_positive_risk ?? null,
       false_positive_risk: normalized.false_positive_risk ?? info.false_positive_risk ?? null,
-      fixDifficultyNotes: normalized.fixDifficultyNotes ?? normalized.fix_difficulty_notes ?? info.fix_difficulty_notes ?? null,
+      fixDifficultyNotes: normalized.fixDifficultyNotes ?? info.fix_difficulty_notes ?? null,
       fix_difficulty_notes: normalized.fix_difficulty_notes ?? info.fix_difficulty_notes ?? null,
     };
   });
 }
 
 // ---------------------------------------------------------------------------
-// Score computation
+// Score computation (internal)
 // ---------------------------------------------------------------------------
 
-/**
- * Computes compliance score, grade label, and WCAG pass/fail status.
- * @param {{ Critical: number, Serious: number, Moderate: number, Minor: number }} totals
- * @returns {{ score: number, label: string, wcagStatus: "Pass" | "Conditional Pass" | "Fail" }}
- */
-export function computeScore(totals) {
+function getComplianceScore(totals) {
   const config = getComplianceConfig();
   const penalties = config.complianceScore.penalties;
   const thresholds = config.gradeThresholds;
@@ -198,15 +202,10 @@ export function computeScore(totals) {
 }
 
 // ---------------------------------------------------------------------------
-// Persona grouping
+// Persona grouping (internal)
 // ---------------------------------------------------------------------------
 
-/**
- * Groups findings by accessibility persona (screen reader, keyboard, cognitive, etc.).
- * @param {object[]} findings - Array of findings with ruleId, wcagCriterionId, impactedUsers.
- * @returns {Record<string, { label: string, count: number, icon: string }>}
- */
-export function computePersonaGroups(findings) {
+function getPersonaGroups(findings) {
   const ref = getWcagReference();
   const personaConfig = ref.personaConfig || {};
   const personaMapping = ref.personaMapping || {};
@@ -261,6 +260,29 @@ export function computePersonaGroups(findings) {
   return groups;
 }
 
+// ---------------------------------------------------------------------------
+// Audit summary
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes a complete audit summary from enriched findings: severity totals,
+ * compliance score, grade label, WCAG status, and persona impact groups.
+ * @param {object[]} findings - Array of enriched findings.
+ * @returns {{ totals, score, label, wcagStatus, personaGroups }}
+ */
+export function getAuditSummary(findings) {
+  const totals = { Critical: 0, Serious: 0, Moderate: 0, Minor: 0 };
+  for (const f of findings) {
+    const severity = f.severity || f.Severity || "";
+    if (severity in totals) totals[severity] += 1;
+  }
+
+  const { score, label, wcagStatus } = getComplianceScore(totals);
+  const personaGroups = getPersonaGroups(findings);
+
+  return { totals, score, label, wcagStatus, personaGroups };
+}
+
 // ---------------------------------------------------------------------------
 // Report generation
 // ---------------------------------------------------------------------------
@@ -281,7 +303,7 @@ import {
  * @param {{ baseUrl?: string, target?: string }} [options={}]
  * @returns {Promise<Buffer>} The PDF as a Node.js Buffer.
  */
-export async function generatePDF(payload, options = {}) {
+export async function getPDFReport(payload, options = {}) {
   const { chromium } = await import("playwright");
   const {
     buildPdfCoverPage,
@@ -334,7 +356,10 @@ ${buildPdfAuditLimitations()}
       margin: { top: "1cm", right: "1cm", bottom: "1cm", left: "1cm" },
       displayHeaderFooter: false,
     });
-    return Buffer.from(pdfBuffer);
+    return {
+      buffer: Buffer.from(pdfBuffer),
+      contentType: "application/pdf",
+    };
   } finally {
     await browser.close();
   }
@@ -346,7 +371,7 @@ ${buildPdfAuditLimitations()}
  * @param {{ baseUrl?: string }} [options={}]
  * @returns {Promise<string>} The complete checklist HTML document.
  */
-export async function generateChecklist(options = {}) {
+export async function getChecklist(options = {}) {
   const { buildManualCheckCard } = await import("./reports/renderers/html.mjs");
   const { escapeHtml } = await import("./reports/renderers/utils.mjs");
 
@@ -365,7 +390,7 @@ export async function generateChecklist(options = {}) {
   // Import the full checklist builder to reuse its buildHtml
   // The checklist builder module has a main() that auto-runs, so we dynamically
   // construct the same output using the renderer functions directly.
-  return `<!doctype html>
+  const html = `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
@@ -441,4 +466,9 @@ export async function generateChecklist(options = {}) {
   <\/script>
 </body>
 </html>`;
+
+  return {
+    html,
+    contentType: "text/html",
+  };
 }