@diegovelasquezweb/a11y-engine 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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,67 @@
+// ---------------------------------------------------------------------------
+// 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;
+  falsePositiveRisk: string | null;
+  fixDifficultyNotes: string | string[] | null;
+}
+
 export interface SeverityTotals {
   Critical: number;
   Serious: number;
@@ -5,7 +69,7 @@ export interface SeverityTotals {
   Minor: number;
 }
 
-export interface ScoreResult {
+export interface ComplianceScore {
   score: number;
   label: string;
   wcagStatus: "Pass" | "Conditional Pass" | "Fail";
@@ -17,33 +81,12 @@ export interface PersonaGroup {
   icon: string;
 }
 
-export interface EngineAssets {
-  intelligence: Record<string, unknown>;
-  pa11yConfig: Record<string, unknown>;
-  complianceConfig: Record<string, unknown>;
-  wcagReference: Record<string, unknown>;
-}
-
-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 +95,34 @@ 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 getComplianceScore(totals: SeverityTotals): ComplianceScore;
+
+export function getPersonaGroups(
+  findings: EnrichedFinding[] | Record<string, unknown>[]
+): Record<string, PersonaGroup>;
+
+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) => {
@@ -168,7 +168,7 @@ export function enrichFindings(findings) {
  * @param {{ Critical: number, Serious: number, Moderate: number, Minor: number }} totals
  * @returns {{ score: number, label: string, wcagStatus: "Pass" | "Conditional Pass" | "Fail" }}
  */
-export function computeScore(totals) {
+export function getComplianceScore(totals) {
   const config = getComplianceConfig();
   const penalties = config.complianceScore.penalties;
   const thresholds = config.gradeThresholds;
@@ -206,7 +206,7 @@ export function computeScore(totals) {
  * @param {object[]} findings - Array of findings with ruleId, wcagCriterionId, impactedUsers.
  * @returns {Record<string, { label: string, count: number, icon: string }>}
  */
-export function computePersonaGroups(findings) {
+export function getPersonaGroups(findings) {
   const ref = getWcagReference();
   const personaConfig = ref.personaConfig || {};
   const personaMapping = ref.personaMapping || {};
@@ -281,7 +281,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 +334,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 +349,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 +368,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 +444,9 @@ export async function generateChecklist(options = {}) {
   <\/script>
 </body>
 </html>`;
+
+  return {
+    html,
+    contentType: "text/html",
+  };
 }