@diegovelasquezweb/a11y-engine 0.11.14 → 0.11.16

package/package.json

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

package/src/fixes/apply-finding-fix.mjs

@@ -0,0 +1,436 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ASSETS } from "../core/asset-loader.mjs";
+
+const ANTHROPIC_API = "https://api.anthropic.com/v1/messages";
+const DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+const MAX_CANDIDATE_FILES = 12;
+const SUPPORTED_EXTENSIONS = new Set([".html", ".htm", ".jsx", ".tsx", ".vue", ".astro", ".liquid"]);
+
+export const FIX_ERROR_CODES = {
+  INVALID_INPUT: "invalid-input",
+  FINDING_NOT_FOUND: "finding-not-found",
+  RULE_MISSING: "rule-missing",
+  FILE_NOT_RESOLVED: "file-not-resolved",
+  PATCH_GENERATION_FAILED: "patch-generation-failed",
+  PATCH_APPLY_FAILED: "patch-apply-failed",
+};
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isWithin(root, target) {
+  const rel = path.relative(root, target);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+function normalizeRoute(value) {
+  if (typeof value !== "string") return "/";
+  const route = value.trim();
+  return route || "/";
+}
+
+function slugify(value) {
+  return String(value || "fix")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+function mapStatus(applied, reason) {
+  if (applied) return "patched";
+  if (reason === FIX_ERROR_CODES.INVALID_INPUT || reason === FIX_ERROR_CODES.FILE_NOT_RESOLVED) return "error";
+  return "not_applied";
+}
+
+function buildResult(data = {}) {
+  const applied = Boolean(data.applied);
+  const reason = data.reason || "";
+  const changedFiles = Array.isArray(data.changedFiles) ? data.changedFiles : [];
+  const verifyRule = data.verifyRule || "";
+  const verifyRoute = data.verifyRoute || "/";
+  const findingTitle = data.findingTitle || "";
+  const branchSlug = data.branchSlug || "a11y-fix";
+
+  return {
+    applied,
+    reason,
+    message: data.message || "",
+    changedFiles,
+    patch: data.patch || "",
+    verifyRule,
+    verifyRoute,
+    findingTitle,
+    branchSlug,
+
+    status: mapStatus(applied, reason),
+    patchedFile: changedFiles[0] || "",
+  };
+}
+
+function getFindingsPayload(input) {
+  if (!isObject(input)) return null;
+  if (isObject(input.findingsPayload)) return input.findingsPayload;
+  if (isObject(input.payload)) return input.payload;
+  return null;
+}
+
+function getFindings(input) {
+  const payload = getFindingsPayload(input);
+  if (!isObject(payload) || !Array.isArray(payload.findings)) return null;
+  return payload.findings;
+}
+
+function getIntelligenceForRule(ruleId) {
+  const rules = ASSETS.remediation.intelligence?.rules || {};
+  return isObject(rules[ruleId]) ? rules[ruleId] : {};
+}
+
+function listFilesRecursive(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const abs = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === ".git" || entry.name === "node_modules" || entry.name === ".next") continue;
+        stack.push(abs);
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (SUPPORTED_EXTENSIONS.has(ext)) out.push(abs);
+    }
+  }
+  return out;
+}
+
+function selectorTokens(selector) {
+  return String(selector || "")
+    .replace(/[:#\.\[\]>+~(),=*"']/g, " ")
+    .split(/\s+/)
+    .map((t) => t.trim().toLowerCase())
+    .filter((t) => t && t.length > 1 && !/^nth-/.test(t))
+    .slice(0, 8);
+}
+
+function scoreFile(filePath, content, tokens) {
+  if (tokens.length === 0) return 1;
+  const lcPath = filePath.toLowerCase();
+  const lcContent = content.toLowerCase();
+  let score = 0;
+  for (const token of tokens) {
+    if (lcPath.includes(token)) score += 2;
+    if (lcContent.includes(token)) score += 3;
+  }
+  return score;
+}
+
+function getCandidateFiles(projectDir, finding) {
+  const files = listFilesRecursive(projectDir);
+  const tokens = selectorTokens(finding.selector);
+  const ranked = files
+    .map((abs) => {
+      const content = fs.readFileSync(abs, "utf8");
+      const rel = path.relative(projectDir, abs);
+      return { abs, rel, content, score: scoreFile(rel, content, tokens) };
+    })
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, MAX_CANDIDATE_FILES);
+  return ranked;
+}
+
+function buildExecution(ruleId, intelligenceRule, finding) {
+  const ruleVerify = finding.rule_id || ruleId || "";
+  const route = normalizeRoute(finding.area);
+  return {
+    strategy: "ai-dom-patch",
+    operations: ["text-replace"],
+    constraints: {
+      must: intelligenceRule.guardrails_overrides?.must || intelligenceRule.guardrails?.must || [],
+      must_not:
+        intelligenceRule.guardrails_overrides?.must_not || intelligenceRule.guardrails?.must_not || [],
+      verify: intelligenceRule.guardrails_overrides?.verify || intelligenceRule.guardrails?.verify || [],
+    },
+    verify: {
+      ruleId: ruleVerify,
+      route,
+    },
+  };
+}
+
+function buildAiFixInput({ finding, intelligenceRule, execution, candidates }) {
+  return {
+    finding: {
+      id: finding.id,
+      ruleId: finding.rule_id,
+      title: finding.title,
+      severity: finding.severity,
+      selector: finding.selector,
+      actual: finding.actual,
+      expected: finding.expected,
+      area: finding.area,
+      url: finding.url,
+      fixDescription: finding.fix_description || intelligenceRule.fix?.description || "",
+      fixCode: finding.fix_code || intelligenceRule.fix?.code || "",
+    },
+    intelligence: {
+      category: intelligenceRule.category || "",
+      frameworkNotes: intelligenceRule.framework_notes || {},
+      cmsNotes: intelligenceRule.cms_notes || {},
+      fixDifficultyNotes: intelligenceRule.fix_difficulty_notes || "",
+    },
+    execution,
+    files: candidates.map((c) => ({ filePath: c.rel, content: c.content.slice(0, 12000) })),
+  };
+}
+
+function parseJsonBlock(text) {
+  const raw = String(text || "").trim();
+  if (!raw) return null;
+  const codeFence = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const source = codeFence ? codeFence[1] : raw;
+  try {
+    return JSON.parse(source);
+  } catch {
+    const objMatch = source.match(/\{[\s\S]*\}/);
+    if (!objMatch) return null;
+    try {
+      return JSON.parse(objMatch[0]);
+    } catch {
+      return null;
+    }
+  }
+}
+
+async function callClaudeForPatch({ apiKey, model, aiInput }) {
+  const system = [
+    "You are an accessibility fix engine.",
+    "Return JSON only.",
+    "Generate deterministic text replacements for provided files.",
+    "Do not create files. Do not modify paths outside provided filePath values.",
+    "Schema:",
+    "{\"changes\":[{\"filePath\":\"...\",\"search\":\"...\",\"replace\":\"...\"}],\"verifyRule\":\"...\",\"verifyRoute\":\"...\",\"notes\":\"...\"}",
+  ].join("\n");
+
+  const userMessage = JSON.stringify(aiInput, null, 2);
+
+  const res = await fetch(ANTHROPIC_API, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 4096,
+      system,
+      messages: [{ role: "user", content: userMessage }],
+    }),
+  });
+
+  if (!res.ok) {
+    const message = await res.text();
+    throw new Error(`Claude patch generation failed: ${res.status} ${message}`);
+  }
+
+  const data = await res.json();
+  const content = data.content?.[0]?.text || "";
+  const parsed = parseJsonBlock(content);
+  if (!isObject(parsed)) throw new Error("AI patch output is not valid JSON object");
+  return parsed;
+}
+
+function validateAiPatchOutput(output, projectDir, fileSet) {
+  if (!isObject(output)) return { ok: false, reason: "AI patch output is empty" };
+  if (!Array.isArray(output.changes) || output.changes.length === 0) {
+    return { ok: false, reason: "AI patch output has no changes" };
+  }
+
+  for (const change of output.changes) {
+    if (!isObject(change)) return { ok: false, reason: "Invalid change item" };
+    const filePath = typeof change.filePath === "string" ? change.filePath.trim() : "";
+    const search = typeof change.search === "string" ? change.search : "";
+    const replace = typeof change.replace === "string" ? change.replace : "";
+    if (!filePath || !search) return { ok: false, reason: "Change is missing filePath/search" };
+    if (!fileSet.has(filePath)) return { ok: false, reason: `Change file not in candidate set: ${filePath}` };
+
+    const abs = path.resolve(projectDir, filePath);
+    if (!isWithin(projectDir, abs) && abs !== path.resolve(projectDir, filePath)) {
+      return { ok: false, reason: `Change path escapes projectDir: ${filePath}` };
+    }
+    if (replace.length > 20000) return { ok: false, reason: `Replacement too large for ${filePath}` };
+  }
+
+  return { ok: true };
+}
+
+function applyChanges(projectDir, changes) {
+  const changedFiles = [];
+  const patchParts = [];
+
+  for (const change of changes) {
+    const rel = change.filePath;
+    const abs = path.resolve(projectDir, rel);
+    const original = fs.readFileSync(abs, "utf8");
+    if (!original.includes(change.search)) {
+      return { ok: false, reason: `Search block not found in ${rel}` };
+    }
+    const updated = original.replace(change.search, change.replace);
+    if (updated === original) continue;
+    fs.writeFileSync(abs, updated, "utf8");
+    changedFiles.push(rel);
+    patchParts.push(`--- ${rel}\n+++ ${rel}\n@@\n-${change.search}\n+${change.replace}`);
+  }
+
+  if (changedFiles.length === 0) return { ok: false, reason: "No effective changes were applied" };
+
+  return {
+    ok: true,
+    changedFiles: [...new Set(changedFiles)],
+    patch: patchParts.join("\n"),
+  };
+}
+
+/**
+ * @param {{
+ *  findingId: string,
+ *  findingsPayload?: { findings: Array<Record<string, unknown>> },
+ *  payload?: { findings: Array<Record<string, unknown>> },
+ *  projectDir: string,
+ *  ai?: { apiKey?: string, model?: string },
+ * }} input
+ */
+export async function applyFindingFix(input) {
+  if (!isObject(input)) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.INVALID_INPUT,
+      message: "Input must be an object.",
+    });
+  }
+
+  const findingId = typeof input.findingId === "string" ? input.findingId.trim() : "";
+  const projectDir = typeof input.projectDir === "string" ? input.projectDir.trim() : "";
+  const findings = getFindings(input);
+
+  if (!findingId || !projectDir || !findings) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.INVALID_INPUT,
+      message: "Required input is missing: findingId, findingsPayload.findings, or projectDir.",
+    });
+  }
+
+  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.FILE_NOT_RESOLVED,
+      message: `Project directory does not exist: ${projectDir}`,
+    });
+  }
+
+  const finding = findings.find((entry) => isObject(entry) && entry.id === findingId);
+  if (!finding) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.FINDING_NOT_FOUND,
+      message: `Finding ${findingId} was not found in findingsPayload.findings.`,
+    });
+  }
+
+  const ruleId = typeof finding.rule_id === "string" ? finding.rule_id.trim() : "";
+  const verifyRoute = normalizeRoute(finding.area);
+  if (!ruleId) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.RULE_MISSING,
+      message: `Finding ${findingId} does not include a rule_id.`,
+      verifyRoute,
+    });
+  }
+
+  const intelligenceRule = getIntelligenceForRule(ruleId);
+  const execution = buildExecution(ruleId, intelligenceRule, finding);
+  const candidates = getCandidateFiles(projectDir, finding);
+  if (candidates.length === 0) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.FILE_NOT_RESOLVED,
+      message: "No candidate source files were found for this finding.",
+      verifyRule: execution.verify.ruleId,
+      verifyRoute: execution.verify.route,
+      findingTitle: finding.title || "",
+      branchSlug: slugify(`${findingId}-${ruleId}`),
+    });
+  }
+
+  const aiInput = buildAiFixInput({ finding, intelligenceRule, execution, candidates });
+  const candidateSet = new Set(candidates.map((c) => c.rel));
+  const apiKey = input.ai?.apiKey || process.env.ANTHROPIC_API_KEY || "";
+  const model = input.ai?.model || DEFAULT_MODEL;
+
+  let patchOutput = null;
+  if (apiKey) {
+    try {
+      patchOutput = await callClaudeForPatch({ apiKey, model, aiInput });
+    } catch {
+      patchOutput = null;
+    }
+  }
+
+  if (!patchOutput) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.PATCH_GENERATION_FAILED,
+      message: `Could not generate patch output for rule ${ruleId}.`,
+      verifyRule: execution.verify.ruleId,
+      verifyRoute: execution.verify.route,
+      findingTitle: finding.title || "",
+      branchSlug: slugify(`${findingId}-${ruleId}`),
+    });
+  }
+
+  const validation = validateAiPatchOutput(patchOutput, projectDir, candidateSet);
+  if (!validation.ok) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.PATCH_GENERATION_FAILED,
+      message: validation.reason,
+      verifyRule: execution.verify.ruleId,
+      verifyRoute: execution.verify.route,
+      findingTitle: finding.title || "",
+      branchSlug: slugify(`${findingId}-${ruleId}`),
+    });
+  }
+
+  const applied = applyChanges(projectDir, patchOutput.changes);
+  if (!applied.ok) {
+    return buildResult({
+      applied: false,
+      reason: FIX_ERROR_CODES.PATCH_APPLY_FAILED,
+      message: applied.reason,
+      verifyRule: execution.verify.ruleId,
+      verifyRoute: execution.verify.route,
+      findingTitle: finding.title || "",
+      branchSlug: slugify(`${findingId}-${ruleId}`),
+    });
+  }
+
+  return buildResult({
+    applied: true,
+    reason: "",
+    message: "Patch applied successfully.",
+    changedFiles: applied.changedFiles,
+    patch: applied.patch,
+    verifyRule: patchOutput.verifyRule || execution.verify.ruleId,
+    verifyRoute: patchOutput.verifyRoute || execution.verify.route,
+    findingTitle: finding.title || "",
+    branchSlug: slugify(`${findingId}-${ruleId}`),
+  });
+}

package/src/index.d.mts

@@ -528,3 +528,45 @@ export interface AiOptions {
   systemPrompt?: string;
   audience?: "pm" | "dev";
 }
+
+export interface FixDomInput {
+  findingId: string;
+  payload?: {
+    findings: Array<Record<string, unknown>>;
+    metadata?: Record<string, unknown>;
+  };
+  findingsPayload?: {
+    findings: Array<Record<string, unknown>>;
+    metadata?: Record<string, unknown>;
+  };
+  projectDir: string;
+  ai?: {
+    apiKey?: string;
+    model?: string;
+  };
+}
+
+export interface FixDomResult {
+  applied: boolean;
+  reason: string;
+  message: string;
+  changedFiles: string[];
+  patch: string;
+  verifyRule: string;
+  verifyRoute: string;
+  findingTitle?: string;
+  branchSlug?: string;
+  status?: "patched" | "not_applied" | "error";
+  patchedFile?: string;
+}
+
+export const FIX_ERROR_CODES: {
+  INVALID_INPUT: "invalid-input";
+  FINDING_NOT_FOUND: "finding-not-found";
+  RULE_MISSING: "rule-missing";
+  FILE_NOT_RESOLVED: "file-not-resolved";
+  PATCH_GENERATION_FAILED: "patch-generation-failed";
+  PATCH_APPLY_FAILED: "patch-apply-failed";
+};
+
+export function applyFindingFix(input: FixDomInput): Promise<FixDomResult>;

package/src/index.mjs

@@ -6,6 +6,7 @@
 
 import { ASSET_PATHS, loadAssetJson } from "./core/asset-loader.mjs";
 export { DEFAULT_AI_SYSTEM_PROMPT, PM_AI_SYSTEM_PROMPT } from "./ai/claude.mjs";
+export { applyFindingFix, FIX_ERROR_CODES } from "./fixes/apply-finding-fix.mjs";
 
 // Lazy-loaded asset cache
 

package/src/reports/renderers/html.mjs

@@ -313,10 +313,6 @@ export function buildManualCheckCard(check) {
     .map((s, i) => `<li class="text-[13px] text-slate-600 leading-relaxed"><span class="font-bold text-slate-400 mr-1.5">${i + 1}.</span>${escapeHtml(s)}</li>`)
     .join("");
 
-  const criterionPill = check.level !== "AT"
-    ? `<span class="px-2.5 py-1 rounded-full text-[10px] font-mono font-semibold bg-slate-100 text-slate-700 border border-slate-200">${escapeHtml(check.criterion)}</span>`
-    : "";
-
   const levelPill = check.level === "AT"
     ? `<span class="px-2.5 py-1 rounded-full text-[11px] font-bold bg-violet-50 text-violet-700 border border-violet-200">Assistive Technology</span>`
     : `<span class="px-2.5 py-1 rounded-full text-[11px] font-bold bg-indigo-50 text-indigo-700 border border-indigo-100">WCAG ${escapeHtml(check.level)}</span>`;
@@ -356,8 +352,6 @@ export function buildManualCheckCard(check) {
       <div class="flex items-center gap-4">
         <div class="flex-1 min-w-0">
           <div class="flex flex-wrap items-center gap-2 mb-2.5">
-            <span class="manual-badge px-2.5 py-1 rounded-full text-[11px] font-bold bg-amber-100 text-amber-800 border border-amber-200 uppercase tracking-wider">Manual</span>
-            ${criterionPill}
             ${levelPill}
           </div>
           <h3 class="text-base font-extrabold text-slate-900 group-hover:text-amber-900 transition-colors">${escapeHtml(check.title)}</h3>