@diegovelasquezweb/a11y-engine 0.1.0

package/scripts/reports/builders/md.mjs

@@ -0,0 +1,96 @@
+/**
+ * @file report-md.mjs
+ * @description Generates a Markdown-based remediation guide and audit summary.
+ * This report is optimized for developers and intended to be used as a
+ * backlog or README-style remediation roadmap.
+ */
+
+import { readJson, log, getInternalPath, DEFAULTS } from "../../core/utils.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeFindings } from "../renderers/findings.mjs";
+import { buildMarkdownSummary } from "../renderers/md.mjs";
+
+/**
+ * Prints the CLI usage instructions and available options for the Markdown report builder.
+ */
+function printUsage() {
+  log.info(`Usage:
+  node report-md.mjs [options]
+
+Options:
+  --input <path>           Findings JSON path (default: internal)
+  --output <path>          Output Markdown path (default: internal)
+  --base-url <url>         Target website URL
+  --target <text>          Compliance target label (default: WCAG 2.2 AA)
+  -h, --help               Show this help
+`);
+}
+
+/**
+ * Parses command-line arguments into a configuration object for the Markdown builder.
+ * @param {string[]} argv - Array of command-line arguments.
+ * @returns {Object} A configuration object containing input, output, and target settings.
+ */
+function parseArgs(argv) {
+  const args = {
+    input: getInternalPath("a11y-findings.json"),
+    output: getInternalPath("remediation.md"),
+    baseUrl: "",
+    target: DEFAULTS.complianceTarget,
+    framework: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    const value = argv[i + 1];
+    if (key === "--help" || key === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+    if (!key.startsWith("--") || value === undefined) continue;
+
+    if (key === "--input") args.input = value;
+    if (key === "--output") args.output = value;
+    if (key === "--base-url") args.baseUrl = value;
+    if (key === "--target") args.target = value;
+    i += 1;
+  }
+
+  return args;
+}
+
+/**
+ * The main execution function for the Markdown report builder.
+ * Reads scan results, generates the Markdown string, and writes the output file.
+ * @throws {Error} If the input findings file is missing or invalid.
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const inputPayload = readJson(args.input);
+  if (!inputPayload) {
+    throw new Error(`Input findings file not found or invalid: ${args.input}`);
+  }
+
+  const patternInput = getInternalPath("a11y-pattern-findings.json");
+  const patternPayload = fs.existsSync(patternInput) ? readJson(patternInput) : null;
+
+  const findings = normalizeFindings(inputPayload);
+  const md = buildMarkdownSummary(args, findings, {
+    ...inputPayload.metadata,
+    incomplete_findings: inputPayload.incomplete_findings,
+    pattern_findings: patternPayload,
+  });
+
+  fs.mkdirSync(path.dirname(args.output), { recursive: true });
+  fs.writeFileSync(args.output, md, "utf-8");
+
+  log.success(`Remediation guide written to ${args.output}`);
+}
+
+try {
+  main();
+} catch (error) {
+  log.error(`Markdown Generation Error: ${error.message}`);
+  process.exit(1);
+}

package/scripts/reports/builders/pdf.mjs

@@ -0,0 +1,259 @@
+/**
+ * @file report-pdf.mjs
+ * @description Generates a professional PDF audit report using Playwright.
+ * It renders an internal HTML template optimized for print and exports it
+ * as a formal A4 accessibility compliance document.
+ */
+
+import { chromium } from "playwright";
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, log, getInternalPath, DEFAULTS } from "../../core/utils.mjs";
+import {
+  normalizeFindings,
+  buildSummary,
+  computeComplianceScore,
+  wcagOverallStatus,
+} from "../renderers/findings.mjs";
+import {
+  scoreMetrics,
+  buildPdfTableOfContents,
+  buildPdfExecutiveSummary,
+  buildPdfRiskSection,
+  buildPdfRemediationRoadmap,
+  buildPdfMethodologySection,
+  buildPdfIssueSummaryTable,
+  buildPdfNextSteps,
+  buildPdfAuditLimitations,
+  buildPdfCoverPage,
+} from "../renderers/pdf.mjs";
+
+/**
+ * Prints the CLI usage instructions and available options for the PDF report builder.
+ */
+function printUsage() {
+  log.info(`Usage:
+  node report-pdf.mjs [options]
+
+Options:
+  --input <path>           Findings JSON path (default: internal)
+  --output <path>          Output PDF path (required)
+  --base-url <url>         Target website URL
+  --target <text>          Compliance target label (default: WCAG 2.2 AA)
+  -h, --help               Show this help
+`);
+}
+
+/**
+ * Parses command-line arguments into a configuration object for the PDF builder.
+ * @param {string[]} argv - Array of command-line arguments.
+ * @returns {Object} A configuration object containing input, output, and target settings.
+ */
+function parseArgs(argv) {
+  const args = {
+    input: getInternalPath("a11y-findings.json"),
+    output: "",
+    baseUrl: "",
+    target: DEFAULTS.complianceTarget,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    const value = argv[i + 1];
+    if (key === "--help" || key === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+    if (!key.startsWith("--") || value === undefined) continue;
+
+    if (key === "--input") args.input = value;
+    if (key === "--output") args.output = value;
+    if (key === "--base-url") args.baseUrl = value;
+    if (key === "--target") args.target = value;
+    i += 1;
+  }
+
+  return args;
+}
+
+/**
+ * Constructs the HTML structure specifically tailored for PDF rendering.
+ * @param {Object} args - The parsed CLI arguments.
+ * @param {Object[]} findings - The normalized list of audit findings.
+ * @returns {string} The HTML document string fully prepared for PDF export.
+ */
+function buildPdfHtml(args, findings) {
+  const totals = buildSummary(findings);
+  const score = computeComplianceScore(totals);
+
+  let siteHostname = args.baseUrl;
+  try {
+    siteHostname = new URL(
+      args.baseUrl.startsWith("http")
+        ? args.baseUrl
+        : `https://${args.baseUrl}`,
+    ).hostname;
+  } catch {}
+
+  const coverDate = new Date().toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  });
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Accessibility Audit — ${siteHostname}</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500&family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
+  <style>
+    @page { size: A4; margin: 2cm; }
+
+    body {
+      background: white;
+      color: black;
+      font-family: 'Libre Baskerville', serif;
+      font-size: 11pt;
+      line-height: 1.6;
+      margin: 0;
+      padding: 0;
+    }
+
+    h1, h2, h3, h4 {
+      font-family: 'Inter', sans-serif;
+      color: black;
+      margin-top: 1.5rem;
+      margin-bottom: 1rem;
+    }
+
+    .cover-page {
+      height: 25.5cm;
+      display: flex;
+      flex-direction: column;
+      page-break-after: always;
+    }
+
+    .finding-entry {
+      border-top: 1pt solid black;
+      padding-top: 1.5rem;
+      margin-top: 2rem;
+      page-break-inside: avoid;
+    }
+
+    .severity-tag {
+      font-weight: 800;
+      text-transform: uppercase;
+      border: 1.5pt solid black;
+      padding: 2pt 6pt;
+      font-size: 9pt;
+      margin-bottom: 1rem;
+      display: inline-block;
+    }
+
+    .remediation-box {
+      background-color: #f3f4f6;
+      border-left: 4pt solid black;
+      padding: 1rem;
+      margin: 1rem 0;
+      font-style: italic;
+    }
+
+    pre {
+      background: #f9fafb;
+      border: 1pt solid #ddd;
+      padding: 10pt;
+      font-size: 8pt;
+      overflow: hidden;
+      white-space: pre-wrap;
+    }
+
+    .stats-table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 2rem 0;
+    }
+    .stats-table th, .stats-table td {
+      border: 1pt solid black;
+      padding: 10pt;
+      text-align: left;
+      font-size: 9pt;
+      font-family: 'Inter', sans-serif;
+    }
+  </style>
+</head>
+<body>
+  ${buildPdfCoverPage({ siteHostname, target: args.target, score, wcagStatus: wcagOverallStatus(totals), coverDate })}
+  ${buildPdfTableOfContents()}
+  ${buildPdfExecutiveSummary(args, findings, totals)}
+  ${buildPdfRiskSection(totals)}
+  ${buildPdfRemediationRoadmap(findings)}
+  ${buildPdfMethodologySection(args, findings)}
+  ${buildPdfIssueSummaryTable(findings)}
+  ${buildPdfNextSteps(findings, totals)}
+  ${buildPdfAuditLimitations()}
+</body>
+</html>`;
+}
+
+/**
+ * The main execution function for the PDF report builder.
+ * Uses a headless browser (Playwright) to render the report and save it as a PDF file.
+ */
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.output) {
+    log.error("Missing required --output flag for PDF report location.");
+    process.exit(1);
+  }
+
+  const inputPayload = readJson(args.input);
+  if (!inputPayload) {
+    log.error(`Input findings file not found or invalid: ${args.input}`);
+    process.exit(1);
+  }
+
+  const findings = normalizeFindings(inputPayload).filter(
+    (f) => f.wcagClassification !== "AAA" && f.wcagClassification !== "Best Practice",
+  );
+  const html = buildPdfHtml(args, findings);
+
+  log.info("Generating professional PDF report...");
+
+  fs.mkdirSync(path.dirname(args.output), { recursive: true });
+
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  try {
+    await page.setContent(html, { waitUntil: "load" });
+    await page.evaluate(() => document.fonts.ready);
+
+    await page.pdf({
+      path: args.output,
+      format: "A4",
+      printBackground: true,
+      margin: {
+        top: "1cm",
+        right: "1cm",
+        bottom: "1cm",
+        left: "1cm",
+      },
+      displayHeaderFooter: false,
+    });
+
+    log.success(`PDF report generated successfully: ${args.output}`);
+  } catch (error) {
+    log.error(`Failed to generate PDF: ${error.message}`);
+    process.exit(1);
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((error) => {
+  log.error(`Unhandled PDF Generation Error: ${error.message}`);
+  process.exit(1);
+});

package/scripts/reports/renderers/findings.mjs

@@ -0,0 +1,188 @@
+/**
+ * @file findings.mjs
+ * @description Core data normalization and scoring logic for accessibility findings.
+ * Provides functions to process raw scanner results into a structured format used
+ * across all report types (HTML, Markdown, PDF).
+ */
+
+import { ASSET_PATHS, loadAssetJson } from "../../core/asset-loader.mjs";
+
+const SCORING_CONFIG = loadAssetJson(
+  ASSET_PATHS.reporting.complianceConfig,
+  "assets/reporting/compliance-config.json",
+);
+const RULE_METADATA = loadAssetJson(
+  ASSET_PATHS.reporting.wcagReference,
+  "assets/reporting/wcag-reference.json",
+);
+
+/**
+ * Defines the priority order for severity levels, where lower values indicate higher priority.
+ * @type {Object<string, number>}
+ */
+export const SEVERITY_ORDER = SCORING_CONFIG.severityOrder;
+
+
+/**
+ * Normalizes raw scanner finding objects into a consistent structure for reporting.
+ * Sorts the result by severity and then by ID.
+ * @param {Object} payload - The raw scanner result payload.
+ * @param {Object[]} payload.findings - The array of findings to normalize.
+ * @returns {Object[]} An array of normalized and sorted finding objects.
+ * @throws {Error} If the payload structure is invalid.
+ */
+export function normalizeFindings(payload) {
+  if (
+    !payload ||
+    typeof payload !== "object" ||
+    !Array.isArray(payload.findings)
+  ) {
+    throw new Error("Input must be a JSON object with a 'findings' array.");
+  }
+
+  return payload.findings
+    .map((item, index) => ({
+      id: String(item.id ?? `A11Y-${String(index + 1).padStart(3, "0")}`),
+      ruleId: String(item.rule_id ?? ""),
+      category: item.category ?? null,
+      title: String(item.title ?? "Untitled finding"),
+      severity: String(item.severity ?? "Unknown"),
+      wcag: String(item.wcag ?? ""),
+      wcagClassification: item.wcag_classification ?? null,
+      area: String(item.area ?? ""),
+      url: String(item.url ?? ""),
+      selector: String(item.selector ?? ""),
+      primarySelector: String(item.primary_selector ?? item.selector ?? ""),
+      impactedUsers: String(
+        item.impacted_users ?? "Users relying on assistive technology",
+      ),
+      actual: String(item.actual ?? ""),
+      primaryFailureMode: item.primary_failure_mode ?? null,
+      relationshipHint: item.relationship_hint ?? null,
+      failureChecks: Array.isArray(item.failure_checks) ? item.failure_checks : [],
+      relatedContext: Array.isArray(item.related_context) ? item.related_context : [],
+      expected: String(item.expected ?? ""),
+      mdn: item.mdn ?? null,
+      fixDescription: item.fix_description ?? null,
+      fixCode: item.fix_code ?? null,
+      recommendedFix: String(item.recommended_fix ?? item.recommendedFix ?? ""),
+      evidence: Array.isArray(item.evidence) ? item.evidence : [],
+      totalInstances:
+        typeof item.total_instances === "number" ? item.total_instances : null,
+      effort: item.effort ?? null,
+      relatedRules: Array.isArray(item.related_rules) ? item.related_rules : [],
+      fixCodeLang: item.fix_code_lang ?? "html",
+      screenshotPath: item.screenshot_path ?? null,
+      falsePositiveRisk: item.false_positive_risk ?? null,
+      guardrails: item.guardrails ?? null,
+      fixDifficultyNotes: item.fix_difficulty_notes ?? null,
+      frameworkNotes: item.framework_notes ?? null,
+      cmsNotes: item.cms_notes ?? null,
+      fileSearchPattern: item.file_search_pattern ?? null,
+      ownershipStatus: item.ownership_status ?? "unknown",
+      ownershipReason: item.ownership_reason ?? null,
+      primarySourceScope: Array.isArray(item.primary_source_scope)
+        ? item.primary_source_scope
+        : [],
+      searchStrategy: item.search_strategy ?? "verify_ownership_before_search",
+      managedByLibrary: item.managed_by_library ?? null,
+      componentHint: item.component_hint ?? null,
+      verificationCommand: item.verification_command ?? null,
+      verificationCommandFallback: item.verification_command_fallback ?? null,
+      pagesAffected: typeof item.pages_affected === "number" ? item.pages_affected : null,
+      affectedUrls: Array.isArray(item.affected_urls) ? item.affected_urls : null,
+      checkData: item.check_data ?? null,
+    }))
+    .sort((a, b) => {
+      const sa = SEVERITY_ORDER[a.severity] ?? 99;
+      const sb = SEVERITY_ORDER[b.severity] ?? 99;
+      if (sa !== sb) return sa - sb;
+      return a.id.localeCompare(b.id);
+    });
+}
+
+/**
+ * Aggregates findings by their severity level.
+ * @param {Object[]} findings - The normalized list of findings.
+ * @returns {Object<string, number>} An object mapping severity labels to counts.
+ */
+export function buildSummary(findings) {
+  const totals = { Critical: 0, Serious: 0, Moderate: 0, Minor: 0 };
+  for (const finding of findings) {
+    if (finding.severity in totals) totals[finding.severity] += 1;
+  }
+  return totals;
+}
+
+/**
+ * Calculates a global compliance score (0-100) based on weighted severity counts.
+ * @param {Object<string, number>} totals - The summary of counts per severity.
+ * @returns {number} An integer compliance score from 0 to 100.
+ */
+export function computeComplianceScore(totals) {
+  const { baseScore, penalties } = SCORING_CONFIG.complianceScore;
+  const raw =
+    baseScore -
+    totals.Critical * penalties.Critical -
+    totals.Serious * penalties.Serious -
+    totals.Moderate * penalties.Moderate -
+    totals.Minor * penalties.Minor;
+  return Math.max(0, Math.min(100, Math.round(raw)));
+}
+
+/**
+ * Returns a human-readable performance label (grade) based on the compliance score.
+ * @param {number} score - The calculated compliance score.
+ * @returns {string} A label like "Excellent", "Good", "Fair", "Poor", or "Critical".
+ */
+export function scoreLabel(score) {
+  for (const { min, label } of SCORING_CONFIG.gradeThresholds) {
+    if (score >= min) return label;
+  }
+  return "Critical";
+}
+
+export function wcagOverallStatus(totals) {
+  if (totals.Critical > 0 || totals.Serious > 0) return "Fail";
+  if (totals.Moderate > 0 || totals.Minor > 0) return "Conditional Pass";
+  return "Pass";
+}
+
+/**
+ * Analyzes findings to determine the unique number of issues impacting specific user personas.
+ * @param {Object[]} findings - The normalized list of findings.
+ * @returns {Object} An object containing impact counts for screenReader, keyboard, vision, and cognitive personas.
+ */
+export function buildPersonaSummary(findings) {
+  const SMART_MAP = RULE_METADATA.personaMapping;
+
+  const uniqueIssues = {};
+  for (const persona of Object.keys(SMART_MAP)) {
+    uniqueIssues[persona] = new Set();
+  }
+
+  for (const f of findings) {
+    const users = (f.impactedUsers || "").toLowerCase();
+    const ruleId = (f.ruleId || "").toLowerCase();
+    const title = (f.title || "").toLowerCase();
+    const issueKey = f.ruleId || f.title;
+
+    Object.keys(SMART_MAP).forEach((persona) => {
+      const { rules, keywords } = SMART_MAP[persona];
+      const matchRule = rules.some((r) => ruleId.includes(r.toLowerCase()));
+      const matchKeyword = keywords.some(
+        (k) => users.includes(k) || title.includes(k),
+      );
+
+      if (matchRule || matchKeyword) {
+        uniqueIssues[persona].add(issueKey);
+      }
+    });
+  }
+
+  const result = {};
+  for (const persona of Object.keys(SMART_MAP)) {
+    result[persona] = uniqueIssues[persona].size;
+  }
+  return result;
+}