@wcag-audit/cli 1.0.0-alpha.3

package/src/license/validate.js

@@ -0,0 +1,58 @@
+const LICENSE_KEY_RE = /^WCAG-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/;
+
+const DEFAULT_API_URL = "https://api.wcagaudit.io/v1/license/validate";
+
+export function isValidLicenseFormat(key) {
+  return typeof key === "string" && LICENSE_KEY_RE.test(key);
+}
+
+export async function validateLicense(key, { machineId, source = "cli", version = "1.0.0-alpha.1", apiUrl } = {}) {
+  const normalized = (key || "").trim().toUpperCase();
+
+  if (!isValidLicenseFormat(normalized)) {
+    return {
+      valid: false,
+      tier: "free",
+      error: "Invalid license key format. Expected WCAG-XXXX-XXXX-XXXX-XXXX.",
+    };
+  }
+
+  const url = apiUrl || process.env.WCAG_LICENSE_VALIDATE_URL || DEFAULT_API_URL;
+
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        key: normalized,
+        machineId,
+        version,
+        source,
+      }),
+    });
+
+    const body = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      return {
+        valid: false,
+        tier: body.tier || "free",
+        error: body.error || `License server returned ${res.status}`,
+      };
+    }
+
+    return {
+      valid: !!body.valid,
+      tier: body.tier || "free",
+      expiresAt: body.expiresAt || null,
+      creditsRemaining: body.creditsRemaining || null,
+      features: body.features || [],
+    };
+  } catch (err) {
+    return {
+      valid: false,
+      tier: "free",
+      error: `Network error: ${err.message}`,
+    };
+  }
+}

package/src/license/validate.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { validateLicense } from "./validate.js";
+
+describe("validateLicense", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("rejects invalid format without hitting the network", async () => {
+    const result = await validateLicense("not-a-key", { machineId: "m1" });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/format/i);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns valid result for accepted license", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        valid: true,
+        tier: "pro",
+        expiresAt: null,
+        creditsRemaining: { server: 153, total: 153 },
+      }),
+    });
+    const result = await validateLicense("WCAG-TEST-AAAA-BBBB-CCCC", {
+      machineId: "m1",
+    });
+    expect(result.valid).toBe(true);
+    expect(result.tier).toBe("pro");
+    expect(result.creditsRemaining.total).toBe(153);
+  });
+
+  it("returns invalid result when API rejects the key", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      json: async () => ({ valid: false, error: "License revoked" }),
+    });
+    const result = await validateLicense("WCAG-TEST-AAAA-BBBB-CCCC", {
+      machineId: "m1",
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toBe("License revoked");
+  });
+
+  it("returns network-error result when fetch throws", async () => {
+    global.fetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    const result = await validateLicense("WCAG-TEST-AAAA-BBBB-CCCC", {
+      machineId: "m1",
+    });
+    expect(result.valid).toBe(false);
+    expect(result.error).toMatch(/network|econnrefused/i);
+  });
+});

package/src/output/agents-md.js

@@ -0,0 +1,58 @@
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+
+// Markers let us find and rewrite exactly our section without
+// disturbing hand-written content before/after.
+export const WCAG_SECTION_START = "<!-- wcag-audit:start -->";
+export const WCAG_SECTION_END = "<!-- wcag-audit:end -->";
+
+function buildSection(body) {
+  return [
+    WCAG_SECTION_START,
+    "## WCAG Accessibility Fixes",
+    "",
+    "The latest @wcagaudit/cli scan produced the fixes below.",
+    "Apply them when editing the affected files.",
+    "",
+    body.trimEnd(),
+    "",
+    WCAG_SECTION_END,
+  ].join("\n");
+}
+
+export async function upsertAgentsMd(projectDir, body) {
+  const path = join(projectDir, "AGENTS.md");
+  let current = "";
+  try {
+    current = await readFile(path, "utf8");
+  } catch {
+    // no existing file — we'll create one
+  }
+
+  const wantsRemoval = body === "";
+  const startIdx = current.indexOf(WCAG_SECTION_START);
+  const endIdx = current.indexOf(WCAG_SECTION_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = current.slice(0, startIdx).trimEnd();
+    const after = current.slice(endIdx + WCAG_SECTION_END.length).trimStart();
+    if (wantsRemoval) {
+      const merged = [before, after].filter(Boolean).join("\n\n").trimEnd() + "\n";
+      await writeFile(path, merged, "utf8");
+      return;
+    }
+    const merged = [before, buildSection(body), after].filter(Boolean).join("\n\n").trimEnd() + "\n";
+    await writeFile(path, merged, "utf8");
+    return;
+  }
+
+  if (wantsRemoval) {
+    // Nothing to remove — leave the file alone.
+    return;
+  }
+
+  const next = current.trim().length
+    ? current.trimEnd() + "\n\n" + buildSection(body) + "\n"
+    : buildSection(body) + "\n";
+  await writeFile(path, next, "utf8");
+}

package/src/output/agents-md.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { upsertAgentsMd, WCAG_SECTION_START, WCAG_SECTION_END } from "./agents-md.js";
+
+let dir;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "agentsmd-"));
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe("upsertAgentsMd", () => {
+  it("creates AGENTS.md when it does not exist", async () => {
+    await upsertAgentsMd(dir, "- Issue A\n- Issue B\n");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).toMatch(WCAG_SECTION_START);
+    expect(raw).toMatch(/Issue A/);
+    expect(raw).toMatch(WCAG_SECTION_END);
+  });
+
+  it("appends the WCAG section to an existing AGENTS.md", async () => {
+    await writeFile(join(dir, "AGENTS.md"), "# Project\n\nExisting content.\n", "utf8");
+    await upsertAgentsMd(dir, "- Issue X\n");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).toMatch(/Existing content/);
+    expect(raw).toMatch(WCAG_SECTION_START);
+    expect(raw).toMatch(/Issue X/);
+  });
+
+  it("replaces the WCAG section in-place when it already exists", async () => {
+    await writeFile(
+      join(dir, "AGENTS.md"),
+      `# Project\n\n${WCAG_SECTION_START}\n- Old issue\n${WCAG_SECTION_END}\n\nTrailing content.`,
+      "utf8",
+    );
+    await upsertAgentsMd(dir, "- Fresh issue\n");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).not.toMatch(/Old issue/);
+    expect(raw).toMatch(/Fresh issue/);
+    expect(raw).toMatch(/Trailing content/);
+    // Single occurrence of the markers
+    expect(raw.match(new RegExp(WCAG_SECTION_START, "g"))?.length).toBe(1);
+  });
+
+  it("removes the WCAG section when body is empty string", async () => {
+    await writeFile(
+      join(dir, "AGENTS.md"),
+      `# Project\n\n${WCAG_SECTION_START}\n- Old\n${WCAG_SECTION_END}\n\nDone.\n`,
+      "utf8",
+    );
+    await upsertAgentsMd(dir, "");
+    const raw = await readFile(join(dir, "AGENTS.md"), "utf8");
+    expect(raw).not.toMatch(WCAG_SECTION_START);
+    expect(raw).not.toMatch(WCAG_SECTION_END);
+    expect(raw).toMatch(/Done\./);
+  });
+});

package/src/output/cursor-rules.js

@@ -0,0 +1,57 @@
+// Renders `.cursor/rules/wcag-fixes.mdc` — Cursor's native rule format.
+// When a user edits any file under the globs, Cursor auto-attaches the
+// rule as context, so the agent "knows" about the WCAG issues in that
+// file without needing a separate prompt.
+
+export function renderCursorRules({ findings, projectName }) {
+  const frontMatter = [
+    "---",
+    "description: WCAG accessibility fixes generated by @wcagaudit/cli",
+    `globs: ${JSON.stringify(["src/app/**/*.tsx", "src/app/**/*.ts", "src/components/**/*.tsx"])}`,
+    "alwaysApply: false",
+    "---",
+    "",
+  ].join("\n");
+
+  if (!findings || findings.length === 0) {
+    return (
+      frontMatter +
+      `# WCAG Fixes (${projectName})\n\n✅ No outstanding WCAG issues found in the last scan.\n`
+    );
+  }
+
+  // Group findings by source file so the rule is contextually useful
+  // when the agent is editing one of those files.
+  const byFile = new Map();
+  for (const f of findings) {
+    const key = f.sourceFile || "(unknown)";
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(f);
+  }
+
+  const lines = [
+    frontMatter,
+    `# WCAG Fixes (${projectName})`,
+    "",
+    "When editing any file listed below, apply the recommended accessibility fix.",
+    "Each item has the WCAG criterion, impact level, and specific remediation.",
+    "",
+  ];
+
+  for (const [file, items] of byFile.entries()) {
+    lines.push(`## ${file}`);
+    lines.push("");
+    for (const f of items) {
+      const criteriaList = Array.isArray(f.criteria) ? f.criteria : f.criteria ? [f.criteria] : [];
+      const crit = criteriaList.join(", ") || "?";
+      lines.push(`- **${f.description || f.ruleId}** — ${crit} (${f.level || "?"}, ${f.impact || "minor"})`);
+      if (f.help) lines.push(`  - Fix: ${f.help}`);
+      if (f.evidence) lines.push(`  - Evidence: \`${String(f.evidence).replace(/`/g, "'").slice(0, 120)}\``);
+      if (f.route) lines.push(`  - Observed on route: \`${f.route}\``);
+      if (f.helpUrl) lines.push(`  - Reference: ${f.helpUrl}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/output/cursor-rules.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { renderCursorRules } from "./cursor-rules.js";
+
+describe("renderCursorRules", () => {
+  const findings = [
+    {
+      source: "axe",
+      ruleId: "image-alt",
+      criteria: ["1.1.1"],
+      level: "A",
+      impact: "critical",
+      description: "Images must have alternate text",
+      help: "Add an alt attribute.",
+      helpUrl: "https://example/axe/image-alt",
+      selector: "img.hero",
+      evidence: "<img src='/x.png'>",
+      route: "/",
+      sourceFile: "src/app/page.tsx",
+    },
+    {
+      source: "playwright",
+      ruleId: "kbd/focus-visible",
+      criteria: "2.4.7",
+      level: "AA",
+      impact: "serious",
+      description: "No visible focus indicator.",
+      help: "Add :focus-visible styles.",
+      helpUrl: "https://example/focus-visible",
+      selector: "button",
+      evidence: "<button/>",
+      route: "/about",
+      sourceFile: "src/app/about/page.tsx",
+    },
+  ];
+
+  it("includes Cursor MDC front-matter with globs", () => {
+    const out = renderCursorRules({ findings, projectName: "demo" });
+    expect(out).toMatch(/^---\n/);
+    expect(out).toMatch(/description: WCAG accessibility fixes/);
+    expect(out).toMatch(/globs: \["src\/app\/\*\*\/\*.tsx","src\/app\/\*\*\/\*.ts","src\/components\/\*\*\/\*.tsx"\]/);
+    expect(out).toMatch(/alwaysApply: false/);
+  });
+
+  it("returns a minimal no-issues rule when findings is empty", () => {
+    const out = renderCursorRules({ findings: [], projectName: "demo" });
+    expect(out).toMatch(/^---\n/);
+    expect(out).toMatch(/No outstanding WCAG issues found/);
+  });
+
+  it("groups findings by source file so Cursor attaches the rule contextually", () => {
+    const out = renderCursorRules({ findings, projectName: "demo" });
+    expect(out).toMatch(/src\/app\/page\.tsx/);
+    expect(out).toMatch(/src\/app\/about\/page\.tsx/);
+    expect(out.indexOf("src/app/page.tsx")).toBeLessThan(out.indexOf("src/app/about/page.tsx"));
+  });
+
+  it("tags each finding with its criterion + impact", () => {
+    const out = renderCursorRules({ findings, projectName: "demo" });
+    expect(out).toMatch(/1\.1\.1 \(A, critical\)/);
+    expect(out).toMatch(/2\.4\.7 \(AA, serious\)/);
+  });
+});

package/src/output/markdown.js

@@ -0,0 +1,119 @@
+// Renders findings as an AI-ready markdown document. The format is
+// designed for Cursor / Claude Code / Windsurf — each finding has
+// enough context (route, file, snippet, criterion, fix hint) for an
+// AI agent to open the file and apply the fix directly.
+
+const IMPACT_ORDER = ["critical", "serious", "moderate", "minor"];
+
+export function renderFindingsMarkdown({
+  projectName,
+  generator,
+  totalPages,
+  wcagVersion,
+  levels,
+  findings,
+}) {
+  const header = [
+    `# WCAG Audit Findings — ${projectName}`,
+    ``,
+    `Generated by ${generator}`,
+    `Total pages audited: ${totalPages}`,
+    `Total issues: ${findings.length}`,
+    `Criteria: WCAG ${wcagVersion} Level ${levels.join(" + ")}`,
+    ``,
+  ].join("\n");
+
+  if (findings.length === 0) {
+    return header + "\n✅ No issues found!\n";
+  }
+
+  const merged = mergeFindings(findings);
+
+  const groups = new Map(IMPACT_ORDER.map((k) => [k, []]));
+  for (const f of merged) {
+    const bucket = IMPACT_ORDER.includes(f.impact) ? f.impact : "minor";
+    groups.get(bucket).push(f);
+  }
+
+  const sections = [];
+  for (const impact of IMPACT_ORDER) {
+    const items = groups.get(impact);
+    if (!items.length) continue;
+    sections.push(
+      `## ${capitalize(impact)} Issues (${items.length})`,
+      ``,
+      ...items.map((f, i) => renderFinding(f, i + 1)),
+    );
+  }
+
+  return header + "\n" + sections.join("\n") + "\n";
+}
+
+function renderFinding(f, index) {
+  // criteria may be a string like "1.1.1" or an array ["1.1.1", "2.4.7"]
+  const criteriaList = Array.isArray(f.criteria)
+    ? f.criteria
+    : f.criteria
+    ? [f.criteria]
+    : [];
+  const criteria = criteriaList.join(", ") || "—";
+  const routesLine =
+    f.routes.length === 1
+      ? `- **Route:** \`${f.routes[0]}\``
+      : `- Routes affected: ${f.routes.length}\n${f.routes.map((r) => `- \`${r}\``).join("\n")}`;
+
+  const fileLine = f.sourceFile
+    ? `- **File:** \`${f.sourceFile}\``
+    : "- **File:** _approximate — source map not available_";
+
+  const snippet = f.evidence
+    ? "\n**Current code:**\n\n```html\n" + escapeCodeBlock(f.evidence) + "\n```\n"
+    : "";
+
+  const fixHint = f.help
+    ? `\n**How to fix:** ${f.help}\n`
+    : "";
+
+  return [
+    `### ${index}. ${f.description || f.ruleId}`,
+    ``,
+    fileLine,
+    routesLine,
+    `- **Criterion:** ${criteria} (Level ${f.level || "?"})`,
+    `- **Rule:** \`${f.ruleId}\``,
+    `- **Detected by:** ${f.source}`,
+    f.helpUrl ? `- **Reference:** ${f.helpUrl}` : "",
+    snippet,
+    fixHint,
+    "---",
+    "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function mergeFindings(findings) {
+  const byKey = new Map();
+  for (const f of findings) {
+    const key = `${f.ruleId}::${f.selector || ""}::${f.evidence || ""}`;
+    if (!byKey.has(key)) {
+      byKey.set(key, { ...f, routes: [], sourceFiles: new Set() });
+    }
+    const entry = byKey.get(key);
+    if (f.route) entry.routes.push(f.route);
+    if (f.sourceFile) entry.sourceFiles.add(f.sourceFile);
+  }
+  for (const entry of byKey.values()) {
+    entry.routes = [...new Set(entry.routes)];
+    entry.sourceFile = [...entry.sourceFiles][0] || null;
+  }
+  return [...byKey.values()];
+}
+
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function escapeCodeBlock(s) {
+  return String(s).replace(/```/g, "\\`\\`\\`");
+}

package/src/output/markdown.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { renderFindingsMarkdown } from "./markdown.js";
+
+describe("renderFindingsMarkdown", () => {
+  const baseFinding = {
+    source: "axe",
+    ruleId: "image-alt",
+    criteria: ["1.1.1"],
+    level: "A",
+    impact: "critical",
+    description: "Images must have alternate text",
+    help: "Add an alt attribute describing the image",
+    helpUrl: "https://dequeuniversity.com/rules/axe/4.10/image-alt",
+    selector: "img.hero",
+    evidence: "<img src='/hero.png'>",
+  };
+
+  it("includes a header with project + generator metadata", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "my-nextjs-app",
+      generator: "@wcagaudit/cli v1.0.0-alpha.1",
+      totalPages: 47,
+      wcagVersion: "2.2",
+      levels: ["A", "AA"],
+      findings: [],
+    });
+    expect(md).toMatch(/# WCAG Audit Findings — my-nextjs-app/);
+    expect(md).toMatch(/@wcagaudit\/cli v1\.0\.0-alpha\.1/);
+    expect(md).toMatch(/Total pages audited: 47/);
+    expect(md).toMatch(/WCAG 2\.2 Level A \+ AA/);
+    expect(md).toMatch(/No issues found!/);
+  });
+
+  it("groups findings by impact descending", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "x",
+      generator: "x",
+      totalPages: 1,
+      wcagVersion: "2.2",
+      levels: ["A"],
+      findings: [
+        { ...baseFinding, impact: "minor", ruleId: "minor-rule" },
+        { ...baseFinding, impact: "critical", ruleId: "image-alt" },
+        { ...baseFinding, impact: "serious", ruleId: "serious-rule" },
+      ],
+    });
+    const criticalIdx = md.indexOf("## Critical");
+    const seriousIdx = md.indexOf("## Serious");
+    const minorIdx = md.indexOf("## Minor");
+    expect(criticalIdx).toBeGreaterThan(-1);
+    expect(criticalIdx).toBeLessThan(seriousIdx);
+    expect(seriousIdx).toBeLessThan(minorIdx);
+  });
+
+  it("renders a finding with route, file, criterion, and snippet", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "x",
+      generator: "x",
+      totalPages: 1,
+      wcagVersion: "2.2",
+      levels: ["A"],
+      findings: [
+        {
+          ...baseFinding,
+          route: "/",
+          sourceFile: "src/app/page.tsx",
+        },
+      ],
+    });
+    expect(md).toMatch(/\*\*Route:\*\* `\/`/);
+    expect(md).toMatch(/\*\*File:\*\* `src\/app\/page\.tsx`/);
+    expect(md).toMatch(/1\.1\.1/);
+    expect(md).toMatch(/image-alt/);
+    expect(md).toMatch(/<img src='\/hero\.png'>/);
+  });
+
+  it("merges findings that share ruleId but appear on multiple routes", () => {
+    const md = renderFindingsMarkdown({
+      projectName: "x",
+      generator: "x",
+      totalPages: 3,
+      wcagVersion: "2.2",
+      levels: ["A"],
+      findings: [
+        { ...baseFinding, route: "/", sourceFile: "src/app/page.tsx" },
+        { ...baseFinding, route: "/about", sourceFile: "src/app/about/page.tsx" },
+        { ...baseFinding, route: "/pricing", sourceFile: "src/app/pricing/page.tsx" },
+      ],
+    });
+    expect(md).toMatch(/Routes affected: 3/);
+    expect(md).toMatch(/- `\/`/);
+    expect(md).toMatch(/- `\/about`/);
+    expect(md).toMatch(/- `\/pricing`/);
+  });
+});