@wcag-audit/cli 1.0.0-alpha.11

package/src/config/project.js

@@ -0,0 +1,35 @@
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+
+export const DEFAULT_PROJECT_CONFIG = {
+  routes: "auto",
+  excludePaths: [],
+  failOn: "critical",
+  // Valid values: "excel" (deferred), "markdown", "cursor-rules",
+  // "agents-md", "json". Unknown values are ignored.
+  outputs: ["excel", "markdown"],
+  dynamicRouteSamples: {},
+  devServer: {
+    command: null,
+    port: null,
+    healthCheck: "/",
+    startupTimeout: 60000,
+  },
+};
+
+export async function readProjectConfig(cwd = process.cwd()) {
+  const path = join(cwd, ".wcagauditrc");
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_PROJECT_CONFIG, ...parsed };
+  } catch {
+    return structuredClone(DEFAULT_PROJECT_CONFIG);
+  }
+}
+
+export async function writeProjectConfig(cwd, config) {
+  const path = join(cwd, ".wcagauditrc");
+  const merged = { ...DEFAULT_PROJECT_CONFIG, ...config };
+  await writeFile(path, JSON.stringify(merged, null, 2), "utf8");
+}

package/src/config/project.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  readProjectConfig,
+  writeProjectConfig,
+  DEFAULT_PROJECT_CONFIG,
+} from "./project.js";
+
+let tmpDir;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "wcagproj-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("project config", () => {
+  it("returns defaults when file is missing", async () => {
+    const cfg = await readProjectConfig(tmpDir);
+    expect(cfg).toEqual(DEFAULT_PROJECT_CONFIG);
+  });
+
+  it("reads existing .wcagauditrc", async () => {
+    await writeFile(
+      join(tmpDir, ".wcagauditrc"),
+      JSON.stringify({ failOn: "serious", excludePaths: ["/api/*"] }),
+      "utf8"
+    );
+    const cfg = await readProjectConfig(tmpDir);
+    expect(cfg.failOn).toBe("serious");
+    expect(cfg.excludePaths).toEqual(["/api/*"]);
+    expect(cfg.routes).toBe("auto");
+  });
+
+  it("writeProjectConfig persists to .wcagauditrc with 644", async () => {
+    await writeProjectConfig(tmpDir, { failOn: "moderate" });
+    const cfg = await readProjectConfig(tmpDir);
+    expect(cfg.failOn).toBe("moderate");
+  });
+});

package/src/devserver/spawn.js

@@ -0,0 +1,82 @@
+import { execa } from "execa";
+
+export function detectDevCommand(pkgJson) {
+  const scripts = pkgJson?.scripts || {};
+  if (scripts.dev) return { cmd: "npm", args: ["run", "dev"] };
+  if (scripts.start) return { cmd: "npm", args: ["run", "start"] };
+  return null;
+}
+
+export async function waitForServer(url, { timeoutMs = 60000, intervalMs = 500 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { redirect: "manual" });
+      if (res.status < 500) return true;
+    } catch {
+      // server not up yet — keep polling
+    }
+    await sleep(intervalMs);
+  }
+  return false;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// Spawn a dev server, wait for it to be ready, return a handle with a dispose().
+export async function startDevServer({
+  cwd,
+  cmd,
+  args,
+  port,
+  healthPath = "/",
+  startupTimeout = 60000,
+  useExisting = false,
+  onOutput = () => {},
+}) {
+  const url = `http://localhost:${port}${healthPath}`;
+
+  if (useExisting) {
+    const ok = await waitForServer(url, { timeoutMs: 3000, intervalMs: 250 });
+    if (!ok) {
+      throw new Error(`No server responding at ${url}. Start your dev server or remove --use-existing.`);
+    }
+    return { url, port, dispose: async () => {} };
+  }
+
+  const child = execa(cmd, args, {
+    cwd,
+    env: { ...process.env, PORT: String(port), FORCE_COLOR: "0" },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  child.stdout?.on("data", (chunk) => onOutput(chunk.toString()));
+  child.stderr?.on("data", (chunk) => onOutput(chunk.toString()));
+
+  const ready = await waitForServer(url, {
+    timeoutMs: startupTimeout,
+    intervalMs: 500,
+  });
+
+  if (!ready) {
+    child.kill("SIGTERM");
+    throw new Error(
+      `Dev server did not respond at ${url} within ${startupTimeout}ms. Check that \`${cmd} ${args.join(" ")}\` starts a server on PORT=${port}.`
+    );
+  }
+
+  const dispose = async () => {
+    if (child.killed) return;
+    child.kill("SIGTERM");
+    try {
+      await Promise.race([child, sleep(3000)]);
+    } catch {
+      /* ignore */
+    }
+    if (!child.killed) child.kill("SIGKILL");
+  };
+
+  return { url, port, dispose, child };
+}

package/src/devserver/spawn.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { waitForServer, detectDevCommand } from "./spawn.js";
+
+describe("waitForServer", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("resolves true immediately if server responds OK", async () => {
+    global.fetch.mockResolvedValueOnce({ ok: true, status: 200 });
+    const result = await waitForServer("http://localhost:3000/", { timeoutMs: 1000, intervalMs: 50 });
+    expect(result).toBe(true);
+  });
+
+  it("retries until server is ready", async () => {
+    global.fetch
+      .mockRejectedValueOnce(new Error("ECONNREFUSED"))
+      .mockRejectedValueOnce(new Error("ECONNREFUSED"))
+      .mockResolvedValueOnce({ ok: true, status: 200 });
+    const result = await waitForServer("http://localhost:3000/", { timeoutMs: 2000, intervalMs: 100 });
+    expect(result).toBe(true);
+    expect(global.fetch.mock.calls.length).toBe(3);
+  });
+
+  it("resolves false after timeout", async () => {
+    global.fetch.mockRejectedValue(new Error("ECONNREFUSED"));
+    const result = await waitForServer("http://localhost:3000/", { timeoutMs: 300, intervalMs: 100 });
+    expect(result).toBe(false);
+  });
+
+  it("accepts any 2xx/3xx status as ready", async () => {
+    global.fetch.mockResolvedValueOnce({ ok: false, status: 301 });
+    const result = await waitForServer("http://localhost:3000/", { timeoutMs: 1000, intervalMs: 50 });
+    expect(result).toBe(true);
+  });
+});
+
+describe("detectDevCommand", () => {
+  it("prefers scripts.dev when present", () => {
+    const cmd = detectDevCommand({
+      scripts: { dev: "next dev", build: "next build", start: "next start" },
+    });
+    expect(cmd).toEqual({ cmd: "npm", args: ["run", "dev"] });
+  });
+
+  it("falls back to start when no dev", () => {
+    const cmd = detectDevCommand({ scripts: { start: "node index.js" } });
+    expect(cmd).toEqual({ cmd: "npm", args: ["run", "start"] });
+  });
+
+  it("returns null when no usable script", () => {
+    expect(detectDevCommand({ scripts: {} })).toBeNull();
+    expect(detectDevCommand({})).toBeNull();
+  });
+});

package/src/discovery/astro.js

@@ -0,0 +1,86 @@
+// Astro detector. Pages live at src/pages/**/*.{astro,md,mdx}.
+// Conventions:
+//   index.astro → /
+//   blog/hello.astro → /blog/hello
+//   pages/api/ → API routes, skipped
+//   [slug].astro → dynamic, skipped
+
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative } from "path";
+
+export async function detectAstro(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (!all.astro) return null;
+    return { framework: "astro", strategy: "source-walk" };
+  } catch {
+    return null;
+  }
+}
+
+export async function discoverAstroRoutes(root, { excludePaths = [] } = {}) {
+  const pagesDir = join(root, "src", "pages");
+  if (!existsSync(pagesDir)) return [];
+
+  const files = await walk(pagesDir);
+  const routes = [];
+
+  for (const abs of files) {
+    const rel = relative(pagesDir, abs).replace(/\\/g, "/");
+    if (!/\.(astro|md|mdx)$/.test(rel)) continue;
+
+    // Skip api/ directory
+    if (rel.startsWith("api/") || rel === "api") continue;
+
+    const noExt = rel.replace(/\.(astro|md|mdx)$/, "");
+    if (noExt.split("/").some((s) => s.startsWith("[") && s.endsWith("]"))) continue;
+
+    const path = noExt === "index" ? "/" : "/" + noExt.replace(/\/index$/, "");
+
+    if (!isExcluded(path, excludePaths)) {
+      routes.push({
+        path,
+        sourceFile: relative(root, abs).replace(/\\/g, "/"),
+      });
+    }
+  }
+
+  return dedupByPath(routes);
+}
+
+async function walk(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      out.push(...(await walk(abs)));
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+function dedupByPath(routes) {
+  const seen = new Map();
+  for (const r of routes) if (!seen.has(r.path)) seen.set(r.path, r);
+  return [...seen.values()];
+}
+
+function isExcluded(routePath, patterns) {
+  for (const pat of patterns) {
+    const rx = new RegExp(
+      "^" +
+        pat
+          .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*/g, ".*") +
+        "$",
+    );
+    if (rx.test(routePath)) return true;
+  }
+  return false;
+}

package/src/discovery/astro.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { detectAstro, discoverAstroRoutes } from "./astro.js";
+
+let root;
+async function touch(rel) {
+  const abs = join(root, rel);
+  await mkdir(join(abs, ".."), { recursive: true });
+  await writeFile(abs, "<!-- test -->", "utf8");
+}
+beforeEach(async () => { root = await mkdtemp(join(tmpdir(), "astro-")); });
+afterEach(async () => { await rm(root, { recursive: true, force: true }); });
+
+describe("detectAstro", () => {
+  it("returns null when astro not in deps", async () => {
+    await writeFile(join(root, "package.json"), JSON.stringify({ dependencies: {} }), "utf8");
+    expect(await detectAstro(root)).toBeNull();
+  });
+
+  it("returns match when astro is in deps or devDeps", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ devDependencies: { astro: "4.0.0" } }),
+      "utf8",
+    );
+    const result = await detectAstro(root);
+    expect(result?.framework).toBe("astro");
+  });
+});
+
+describe("discoverAstroRoutes", () => {
+  beforeEach(async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ devDependencies: { astro: "4.0.0" } }),
+      "utf8",
+    );
+  });
+
+  it("discovers .astro pages and treats index.astro as root", async () => {
+    await touch("src/pages/index.astro");
+    await touch("src/pages/about.astro");
+    await touch("src/pages/blog/hello.astro");
+    const routes = await discoverAstroRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about", "/blog/hello"]);
+  });
+
+  it("discovers .md and .mdx pages", async () => {
+    await touch("src/pages/index.astro");
+    await touch("src/pages/post.md");
+    await touch("src/pages/notes/first.mdx");
+    const routes = await discoverAstroRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/notes/first", "/post"]);
+  });
+
+  it("skips pages/api/ routes", async () => {
+    await touch("src/pages/index.astro");
+    await touch("src/pages/api/ping.ts");
+    await touch("src/pages/api/hello.json.ts");
+    const routes = await discoverAstroRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+
+  it("skips [param] dynamic routes", async () => {
+    await touch("src/pages/index.astro");
+    await touch("src/pages/blog/[slug].astro");
+    const routes = await discoverAstroRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+});

package/src/discovery/crawl.js

@@ -0,0 +1,93 @@
+// BFS crawl for deployed sites. Used with --url + --crawl-depth
+// when we don't have source access. Same-origin only, strips
+// fragments/queries, skips mailto/tel/javascript links.
+
+const HREF_RE = /\bhref\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+
+export function extractLinksFromHtml(html, baseUrl) {
+  if (!html) return [];
+  const origin = new URL(baseUrl).origin;
+  const out = new Set();
+  let m;
+  HREF_RE.lastIndex = 0;
+  while ((m = HREF_RE.exec(html)) !== null) {
+    const raw = (m[1] ?? m[2] ?? "").trim();
+    if (!raw) continue;
+    const lower = raw.toLowerCase();
+    if (lower.startsWith("mailto:") || lower.startsWith("tel:") || lower.startsWith("javascript:")) continue;
+    try {
+      const resolved = new URL(raw, baseUrl);
+      if (resolved.origin !== origin) continue;
+      resolved.hash = "";
+      resolved.search = "";
+      out.add(resolved.toString());
+    } catch {
+      // invalid URL — skip
+    }
+  }
+  return [...out];
+}
+
+export async function crawlRoutes(
+  baseUrl,
+  { maxDepth = 2, maxPages = 100, excludePaths = [] } = {},
+) {
+  const origin = new URL(baseUrl).origin;
+  const startPath = new URL(baseUrl).pathname || "/";
+
+  const visited = new Set();
+  const queue = [{ url: new URL(startPath, baseUrl).toString(), depth: 0 }];
+  const routes = [];
+
+  while (queue.length > 0 && routes.length < maxPages) {
+    const { url, depth } = queue.shift();
+    if (visited.has(url)) continue;
+    visited.add(url);
+
+    const pathOnly = new URL(url).pathname || "/";
+    if (isExcluded(pathOnly, excludePaths)) continue;
+
+    // Add this path to results
+    routes.push({ path: pathOnly, sourceFile: "(crawl)" });
+
+    if (depth >= maxDepth) continue;
+
+    let html = "";
+    try {
+      const res = await fetch(url);
+      if (!res.ok) continue;
+      html = await res.text();
+    } catch {
+      continue;
+    }
+
+    const links = extractLinksFromHtml(html, url);
+    for (const l of links) {
+      if (!visited.has(l)) {
+        queue.push({ url: l, depth: depth + 1 });
+      }
+    }
+  }
+
+  return dedupByPath(routes);
+}
+
+function dedupByPath(routes) {
+  const seen = new Map();
+  for (const r of routes) if (!seen.has(r.path)) seen.set(r.path, r);
+  return [...seen.values()];
+}
+
+function isExcluded(routePath, patterns) {
+  for (const pat of patterns) {
+    const rx = new RegExp(
+      "^" +
+        pat
+          .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*/g, ".*") +
+        "$",
+    );
+    if (rx.test(routePath)) return true;
+  }
+  return false;
+}

package/src/discovery/crawl.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { extractLinksFromHtml, crawlRoutes } from "./crawl.js";
+
+describe("extractLinksFromHtml", () => {
+  it("extracts absolute and relative hrefs", () => {
+    const html = `
+<a href="/about">About</a>
+<a href='pricing'>Pricing</a>
+<a href="https://example.com/contact">Contact</a>
+<a href="https://other.com/off">Off-site</a>
+`;
+    const links = extractLinksFromHtml(html, "https://example.com/").sort();
+    expect(links).toEqual([
+      "https://example.com/about",
+      "https://example.com/contact",
+      "https://example.com/pricing",
+    ]);
+  });
+
+  it("strips fragments and query strings", () => {
+    const html = `
+<a href="/about#section">About</a>
+<a href="/pricing?promo=1">Pricing</a>
+`;
+    const links = extractLinksFromHtml(html, "https://example.com/").sort();
+    expect(links).toEqual([
+      "https://example.com/about",
+      "https://example.com/pricing",
+    ]);
+  });
+
+  it("ignores mailto/tel/javascript hrefs", () => {
+    const html = `
+<a href="mailto:hi@x.com">Mail</a>
+<a href="tel:555">Call</a>
+<a href="javascript:void(0)">Nothing</a>
+<a href="/about">About</a>
+`;
+    const links = extractLinksFromHtml(html, "https://example.com/");
+    expect(links).toEqual(["https://example.com/about"]);
+  });
+});
+
+describe("crawlRoutes", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("starts from baseUrl and follows same-origin links up to maxDepth", async () => {
+    global.fetch.mockImplementation(async (url) => {
+      const body = {
+        "https://example.com/": `<a href="/about">A</a><a href="/pricing">P</a>`,
+        "https://example.com/about": `<a href="/team">T</a>`,
+        "https://example.com/pricing": ``,
+        "https://example.com/team": ``,
+      }[url];
+      if (body == null) return { ok: false, status: 404, text: async () => "" };
+      return { ok: true, status: 200, text: async () => body };
+    });
+    const routes = await crawlRoutes("https://example.com/", { maxDepth: 1 });
+    const paths = routes.map((r) => r.path).sort();
+    // Depth 1: start + direct children (about, pricing). NOT grandchildren (team).
+    expect(paths).toEqual(["/", "/about", "/pricing"]);
+  });
+
+  it("respects maxPages cap", async () => {
+    global.fetch.mockImplementation(async (url) => ({
+      ok: true,
+      status: 200,
+      text: async () =>
+        `<a href="/a">A</a><a href="/b">B</a><a href="/c">C</a><a href="/d">D</a>`,
+    }));
+    const routes = await crawlRoutes("https://example.com/", { maxDepth: 2, maxPages: 3 });
+    expect(routes.length).toBeLessThanOrEqual(3);
+  });
+
+  it("applies excludePaths", async () => {
+    global.fetch.mockImplementation(async (url) => ({
+      ok: true,
+      status: 200,
+      text: async () => `<a href="/admin">Admin</a><a href="/about">About</a>`,
+    }));
+    const routes = await crawlRoutes("https://example.com/", {
+      maxDepth: 1,
+      excludePaths: ["/admin"],
+    });
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+  });
+});

package/src/discovery/dynamic-samples.js

@@ -0,0 +1,44 @@
+// Expand dynamic route patterns ([slug], :id) into concrete routes
+// using config-provided sample values. Routes without matching samples
+// are dropped (explicit opt-in per WCAG dynamic-routes design).
+
+export function expandDynamicRoutes(routes, samples = {}) {
+  const out = [];
+  for (const r of routes) {
+    if (!isDynamicRoute(r.path)) {
+      out.push(r);
+      continue;
+    }
+    const entries = samples[r.path];
+    if (!Array.isArray(entries) || entries.length === 0) {
+      continue; // no samples → drop
+    }
+    for (const sample of entries) {
+      const concrete = fillPattern(r.path, sample);
+      out.push({ path: concrete, sourceFile: r.sourceFile });
+    }
+  }
+  return out;
+}
+
+function isDynamicRoute(path) {
+  // Matches Next.js / SvelteKit / Astro [slug] and React Router / Remix :id
+  return /\[[^/]+\]|:[^/]+/.test(path);
+}
+
+function fillPattern(pattern, sample) {
+  // Replace the first [name] or :name with the sample value.
+  // If a pattern has multiple dynamic segments, users should supply
+  // a longer sample separated by `/`.
+  const parts = pattern.split("/");
+  const sampleParts = String(sample).split("/");
+  let si = 0;
+  const filled = parts.map((seg) => {
+    if (/^\[[^/]+\]$/.test(seg) || /^:[^/]+$/.test(seg)) {
+      const v = sampleParts[si++] ?? sample;
+      return v;
+    }
+    return seg;
+  });
+  return filled.join("/");
+}

package/src/discovery/dynamic-samples.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { expandDynamicRoutes } from "./dynamic-samples.js";
+
+describe("expandDynamicRoutes", () => {
+  it("passes static routes through unchanged", () => {
+    const input = [
+      { path: "/", sourceFile: "app/page.tsx" },
+      { path: "/about", sourceFile: "app/about/page.tsx" },
+    ];
+    const out = expandDynamicRoutes(input, {});
+    expect(out).toEqual(input);
+  });
+
+  it("expands /[slug] when samples are provided", () => {
+    const input = [
+      { path: "/blog/[slug]", sourceFile: "app/blog/[slug]/page.tsx" },
+    ];
+    const samples = { "/blog/[slug]": ["hello-world", "another-post"] };
+    const out = expandDynamicRoutes(input, samples);
+    expect(out.map((r) => r.path).sort()).toEqual([
+      "/blog/another-post",
+      "/blog/hello-world",
+    ]);
+    expect(out[0].sourceFile).toBe("app/blog/[slug]/page.tsx");
+  });
+
+  it("expands multiple dynamic patterns independently", () => {
+    const input = [
+      { path: "/blog/[slug]", sourceFile: "a.tsx" },
+      { path: "/users/[id]", sourceFile: "b.tsx" },
+    ];
+    const samples = {
+      "/blog/[slug]": ["hi"],
+      "/users/[id]": ["1", "2"],
+    };
+    const out = expandDynamicRoutes(input, samples);
+    const paths = out.map((r) => r.path).sort();
+    expect(paths).toEqual(["/blog/hi", "/users/1", "/users/2"]);
+  });
+
+  it("handles :param style (React Router / Remix) as well", () => {
+    const input = [
+      { path: "/users/:id", sourceFile: "x.tsx" },
+    ];
+    const samples = { "/users/:id": ["42"] };
+    const out = expandDynamicRoutes(input, samples);
+    expect(out.map((r) => r.path)).toEqual(["/users/42"]);
+  });
+
+  it("drops dynamic routes with no samples (explicit opt-in)", () => {
+    const input = [
+      { path: "/", sourceFile: "a.tsx" },
+      { path: "/blog/[slug]", sourceFile: "b.tsx" },
+    ];
+    const out = expandDynamicRoutes(input, {});
+    expect(out.map((r) => r.path)).toEqual(["/"]);
+  });
+
+  it("treats $slug as static (Remix convention)", () => {
+    const input = [
+      { path: "/$slug", sourceFile: "x.tsx" },
+    ];
+    const out = expandDynamicRoutes(input, {});
+    expect(out).toEqual(input);
+  });
+});