@wcag-audit/cli 1.0.0-alpha.11

package/src/discovery/manual.js

@@ -0,0 +1,38 @@
+// Manual routes file loader. Format: one path per line, # starts a
+// line comment, blank lines are ignored, leading slash is optional.
+
+import { readFile } from "fs/promises";
+
+export async function loadManualRoutes(path, { excludePaths = [] } = {}) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return [];
+  }
+
+  const routes = [];
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith("#")) continue;
+    const normalized = line.startsWith("/") ? line : "/" + line;
+    if (isExcluded(normalized, excludePaths)) continue;
+    routes.push({ path: normalized, sourceFile: `(${path})` });
+  }
+  return routes;
+}
+
+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/manual.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { loadManualRoutes } from "./manual.js";
+
+let dir;
+beforeEach(async () => { dir = await mkdtemp(join(tmpdir(), "manroutes-")); });
+afterEach(async () => { await rm(dir, { recursive: true, force: true }); });
+
+describe("loadManualRoutes", () => {
+  it("returns [] when file is missing", async () => {
+    const routes = await loadManualRoutes(join(dir, "missing.txt"));
+    expect(routes).toEqual([]);
+  });
+
+  it("parses one path per line", async () => {
+    const path = join(dir, "routes.txt");
+    await writeFile(path, "/\n/about\n/pricing\n", "utf8");
+    const routes = await loadManualRoutes(path);
+    expect(routes.map((r) => r.path)).toEqual(["/", "/about", "/pricing"]);
+  });
+
+  it("ignores blank lines and # comments", async () => {
+    const path = join(dir, "routes.txt");
+    await writeFile(
+      path,
+      "# top comment\n/\n\n/about   # inline comment won't be stripped\n  /pricing  \n",
+      "utf8",
+    );
+    const routes = await loadManualRoutes(path);
+    expect(routes.map((r) => r.path)).toEqual([
+      "/",
+      "/about   # inline comment won't be stripped",
+      "/pricing",
+    ]);
+  });
+
+  it("normalizes leading slash", async () => {
+    const path = join(dir, "routes.txt");
+    await writeFile(path, "about\npricing\n/contact\n", "utf8");
+    const routes = await loadManualRoutes(path);
+    expect(routes.map((r) => r.path)).toEqual(["/about", "/pricing", "/contact"]);
+  });
+
+  it("applies excludePaths", async () => {
+    const path = join(dir, "routes.txt");
+    await writeFile(path, "/\n/admin\n/about\n", "utf8");
+    const routes = await loadManualRoutes(path, { excludePaths: ["/admin"] });
+    expect(routes.map((r) => r.path)).toEqual(["/", "/about"]);
+  });
+});

package/src/discovery/nextjs.js

@@ -0,0 +1,136 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative, sep } from "path";
+import { readdir } from "fs/promises";
+
+// Returns "app" | "pages" | null
+export async function detectNextjsProject(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    const hasNext =
+      (pkg.dependencies && pkg.dependencies.next) ||
+      (pkg.devDependencies && pkg.devDependencies.next);
+    if (!hasNext) return null;
+  } catch {
+    return null;
+  }
+
+  // App Router takes precedence
+  if (existsSync(join(root, "app"))) return "app";
+  if (existsSync(join(root, "src", "app"))) return "app";
+  if (existsSync(join(root, "pages"))) return "pages";
+  if (existsSync(join(root, "src", "pages"))) return "pages";
+  return null;
+}
+
+export async function discoverNextjsRoutes(root, { excludePaths = [] } = {}) {
+  const kind = await detectNextjsProject(root);
+  if (!kind) return [];
+
+  const routes =
+    kind === "app"
+      ? await discoverAppRouter(root)
+      : await discoverPagesRouter(root);
+
+  return routes.filter((r) => !isExcluded(r.path, excludePaths));
+}
+
+// ── App Router ───────────────────────────────────────────────────
+async function discoverAppRouter(root) {
+  const appDirCandidates = [join(root, "app"), join(root, "src", "app")];
+  const appDir = appDirCandidates.find((d) => existsSync(d));
+  if (!appDir) return [];
+
+  const files = await walk(appDir);
+  const routes = [];
+
+  for (const abs of files) {
+    const base = abs.split(sep).pop();
+    const isPageFile = /^page\.(tsx|jsx|ts|js)$/.test(base);
+    if (!isPageFile) continue;
+
+    const rel = relative(appDir, abs).replace(/\\/g, "/");
+    const segs = rel.split("/").slice(0, -1);
+
+    if (segs.some((s) => s.startsWith("[") && s.endsWith("]"))) continue;
+
+    const visible = segs.filter((s) => !(s.startsWith("(") && s.endsWith(")")));
+    const path = "/" + visible.join("/");
+    const normalized = path === "/" || path === "" ? "/" : path;
+
+    routes.push({
+      path: normalized,
+      sourceFile: relative(root, abs).replace(/\\/g, "/"),
+    });
+  }
+
+  return dedupByPath(routes);
+}
+
+// ── Pages Router ─────────────────────────────────────────────────
+async function discoverPagesRouter(root) {
+  const candidates = [join(root, "pages"), join(root, "src", "pages")];
+  const pagesDir = candidates.find((d) => existsSync(d));
+  if (!pagesDir) return [];
+
+  const files = await walk(pagesDir);
+  const routes = [];
+
+  for (const abs of files) {
+    const rel = relative(pagesDir, abs).replace(/\\/g, "/");
+    if (!/\.(tsx|jsx|ts|js)$/.test(rel)) continue;
+
+    if (rel.startsWith("api/")) continue;
+    const noExt = rel.replace(/\.(tsx|jsx|ts|js)$/, "");
+    const base = noExt.split("/").pop();
+    if (base === "_app" || base === "_document" || base === "_error") continue;
+
+    if (noExt.split("/").some((s) => s.startsWith("[") && s.endsWith("]"))) continue;
+
+    const path =
+      noExt === "index"
+        ? "/"
+        : "/" + noExt.replace(/\/index$/, "");
+
+    routes.push({
+      path,
+      sourceFile: relative(root, abs).replace(/\\/g, "/"),
+    });
+  }
+
+  return dedupByPath(routes);
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+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) {
+    // Trailing "/*" matches the bare prefix too: "/admin/*" matches "/admin" and "/admin/x"
+    const hasTrailingStar = /\/\*$/.test(pat);
+    const base = hasTrailingStar ? pat.replace(/\/\*$/, "") : pat;
+    const escaped = base.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    const regexStr = hasTrailingStar ? `^${escaped}(/.*)?$` : `^${escaped}$`;
+    if (new RegExp(regexStr).test(routePath)) return true;
+  }
+  return false;
+}

package/src/discovery/nextjs.test.js

@@ -0,0 +1,141 @@
+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 { discoverNextjsRoutes, detectNextjsProject } from "./nextjs.js";
+
+let root;
+
+async function touch(relPath) {
+  const abs = join(root, relPath);
+  await mkdir(join(abs, ".."), { recursive: true });
+  await writeFile(abs, "// test", "utf8");
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), "nextproj-"));
+});
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+describe("detectNextjsProject", () => {
+  it("returns null when no package.json", async () => {
+    expect(await detectNextjsProject(root)).toBeNull();
+  });
+
+  it("returns 'app' when app/page.tsx exists", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" } }),
+      "utf8"
+    );
+    await touch("app/page.tsx");
+    expect(await detectNextjsProject(root)).toBe("app");
+  });
+
+  it("returns 'app' when src/app/page.tsx exists", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" } }),
+      "utf8"
+    );
+    await touch("src/app/page.tsx");
+    expect(await detectNextjsProject(root)).toBe("app");
+  });
+
+  it("returns 'pages' when pages/index.tsx exists and no app dir", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { next: "14.0.0" } }),
+      "utf8"
+    );
+    await touch("pages/index.tsx");
+    expect(await detectNextjsProject(root)).toBe("pages");
+  });
+
+  it("returns 'app' when both exist (App Router wins)", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" } }),
+      "utf8"
+    );
+    await touch("app/page.tsx");
+    await touch("pages/index.tsx");
+    expect(await detectNextjsProject(root)).toBe("app");
+  });
+});
+
+describe("discoverNextjsRoutes — App Router", () => {
+  beforeEach(async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" } }),
+      "utf8"
+    );
+  });
+
+  it("discovers a single root page", async () => {
+    await touch("app/page.tsx");
+    const routes = await discoverNextjsRoutes(root);
+    expect(routes).toEqual([{ path: "/", sourceFile: "app/page.tsx" }]);
+  });
+
+  it("discovers nested routes", async () => {
+    await touch("app/page.tsx");
+    await touch("app/about/page.tsx");
+    await touch("app/pricing/page.tsx");
+    await touch("app/blog/hello/page.tsx");
+    const routes = await discoverNextjsRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about", "/blog/hello", "/pricing"]);
+  });
+
+  it("strips route groups like (marketing)", async () => {
+    await touch("app/(marketing)/page.tsx");
+    await touch("app/(marketing)/about/page.tsx");
+    const routes = await discoverNextjsRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+  });
+
+  it("skips dynamic routes by default", async () => {
+    await touch("app/page.tsx");
+    await touch("app/blog/[slug]/page.tsx");
+    await touch("app/[...catchall]/page.tsx");
+    const routes = await discoverNextjsRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+
+  it("excludes paths matching excludePaths glob", async () => {
+    await touch("app/page.tsx");
+    await touch("app/api/route.ts");
+    await touch("app/admin/page.tsx");
+    const routes = await discoverNextjsRoutes(root, { excludePaths: ["/admin/*", "/api/*"] });
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+});
+
+describe("discoverNextjsRoutes — Pages Router", () => {
+  beforeEach(async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { next: "14.0.0" } }),
+      "utf8"
+    );
+  });
+
+  it("discovers pages routes and skips _app/_document/api", async () => {
+    await touch("pages/index.tsx");
+    await touch("pages/about.tsx");
+    await touch("pages/_app.tsx");
+    await touch("pages/_document.tsx");
+    await touch("pages/api/health.ts");
+    const routes = await discoverNextjsRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+  });
+});

package/src/discovery/registry.js

@@ -0,0 +1,80 @@
+// Framework detection registry. Each entry exports:
+//   name: human-readable framework name (e.g. "nextjs-app")
+//   detect(cwd): async () => { framework, strategy } | null
+//   discoverRoutes(cwd, options): async () => [{ path, sourceFile }]
+//
+// Detectors are tried in registration order; the first one whose
+// detect() returns a non-null value wins. This keeps Next.js
+// detection first (most common) and lets later frameworks match
+// when Next.js is absent.
+
+import { detectNextjsProject, discoverNextjsRoutes } from "./nextjs.js";
+import { detectVite, discoverViteRoutes } from "./vite.js";
+import { detectSvelteKit, discoverSvelteKitRoutes } from "./sveltekit.js";
+import { detectRemix, discoverRemixRoutes } from "./remix.js";
+import { detectAstro, discoverAstroRoutes } from "./astro.js";
+
+function getBuiltinDetectors() {
+  return [
+    {
+      name: "nextjs",
+      detect: async (cwd) => {
+        const kind = await detectNextjsProject(cwd);
+        if (!kind) return null;
+        return { framework: `nextjs-${kind}`, strategy: "source-walk" };
+      },
+      discoverRoutes: async (cwd, options) => discoverNextjsRoutes(cwd, options),
+    },
+    {
+      name: "vite",
+      detect: async (cwd) => detectVite(cwd),
+      discoverRoutes: async (cwd, options) => discoverViteRoutes(cwd, options),
+    },
+    {
+      name: "sveltekit",
+      detect: async (cwd) => detectSvelteKit(cwd),
+      discoverRoutes: async (cwd, options) => discoverSvelteKitRoutes(cwd, options),
+    },
+    {
+      name: "remix",
+      detect: async (cwd) => detectRemix(cwd),
+      discoverRoutes: async (cwd, options) => discoverRemixRoutes(cwd, options),
+    },
+    {
+      name: "astro",
+      detect: async (cwd) => detectAstro(cwd),
+      discoverRoutes: async (cwd, options) => discoverAstroRoutes(cwd, options),
+    },
+  ];
+}
+
+let registered = getBuiltinDetectors();
+
+// Test seam — lets tests replace the registry without touching real
+// framework detectors.
+export function __setDetectorsForTest(detectors) {
+  registered = detectors;
+}
+
+export function __resetDetectorsForTest() {
+  registered = getBuiltinDetectors();
+}
+
+export function registerDetector(detector) {
+  registered.push(detector);
+}
+
+export async function detectFramework(cwd) {
+  for (const det of registered) {
+    const hit = await det.detect(cwd);
+    if (hit) {
+      return {
+        name: det.name,
+        framework: hit.framework,
+        strategy: hit.strategy,
+        discoverRoutes: det.discoverRoutes,
+      };
+    }
+  }
+  return null;
+}

package/src/discovery/registry.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { detectFramework, __setDetectorsForTest } from "./registry.js";
+
+describe("detectFramework", () => {
+  it("returns null when no detector matches", async () => {
+    __setDetectorsForTest([
+      { name: "fake", detect: async () => null, discoverRoutes: async () => [] },
+    ]);
+    const result = await detectFramework("/tmp/nowhere");
+    expect(result).toBeNull();
+  });
+
+  it("returns the first detector whose detect returns non-null", async () => {
+    __setDetectorsForTest([
+      { name: "fake-a", detect: async () => null, discoverRoutes: async () => [] },
+      { name: "fake-b", detect: async () => ({ framework: "fake-b", strategy: "test" }), discoverRoutes: async () => [{ path: "/", sourceFile: "x" }] },
+      { name: "fake-c", detect: async () => ({ framework: "fake-c", strategy: "test" }), discoverRoutes: async () => [] },
+    ]);
+    const result = await detectFramework("/tmp/x");
+    expect(result).not.toBeNull();
+    expect(result.name).toBe("fake-b");
+    expect(result.framework).toBe("fake-b");
+  });
+
+  it("attaches the detector so discoverRoutes works via result", async () => {
+    __setDetectorsForTest([
+      { name: "m", detect: async () => ({ framework: "m", strategy: "walk" }), discoverRoutes: async () => [{ path: "/", sourceFile: "page.tsx" }] },
+    ]);
+    const result = await detectFramework("/tmp/x");
+    const routes = await result.discoverRoutes("/tmp/x", {});
+    expect(routes).toEqual([{ path: "/", sourceFile: "page.tsx" }]);
+  });
+});

package/src/discovery/remix.js

@@ -0,0 +1,82 @@
+// Remix v2 detector with flat-file convention.
+// Conventions:
+//   app/routes/_index.tsx → /
+//   app/routes/about.tsx → /about
+//   app/routes/blog.hello.tsx → /blog/hello (dot = segment)
+//   app/routes/$slug.tsx → /:slug (dynamic, skipped)
+//   app/routes/api.*.tsx → API route (skipped)
+
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative } from "path";
+
+export async function detectRemix(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    const hasRemix = Object.keys(all).some((k) => k.startsWith("@remix-run/"));
+    if (!hasRemix) return null;
+    return { framework: "remix", strategy: "source-walk" };
+  } catch {
+    return null;
+  }
+}
+
+export async function discoverRemixRoutes(root, { excludePaths = [] } = {}) {
+  const routesDir = join(root, "app", "routes");
+  if (!existsSync(routesDir)) return [];
+
+  const entries = await readdir(routesDir, { withFileTypes: true }).catch(() => []);
+  const routes = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!/\.(tsx|jsx|ts|js)$/.test(entry.name)) continue;
+
+    const noExt = entry.name.replace(/\.(tsx|jsx|ts|js)$/, "");
+
+    // Skip dynamic + catch-all + api routes
+    if (noExt.startsWith("$")) continue;
+    if (noExt.split(".").some((seg) => seg.startsWith("$"))) continue;
+    if (noExt.startsWith("api.") || noExt === "api") continue;
+
+    let path;
+    if (noExt === "_index") {
+      path = "/";
+    } else if (noExt.endsWith("._index")) {
+      // e.g. settings._index.tsx → /settings
+      path = "/" + noExt.replace(/\._index$/, "").split(".").join("/");
+    } else {
+      path = "/" + noExt.split(".").join("/");
+    }
+
+    if (!isExcluded(path, excludePaths)) {
+      routes.push({
+        path,
+        sourceFile: relative(root, join(routesDir, entry.name)).replace(/\\/g, "/"),
+      });
+    }
+  }
+
+  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/remix.test.js

@@ -0,0 +1,77 @@
+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 { detectRemix, discoverRemixRoutes } from "./remix.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(), "remix-")); });
+afterEach(async () => { await rm(root, { recursive: true, force: true }); });
+
+describe("detectRemix", () => {
+  it("returns null when @remix-run/* not in deps", async () => {
+    await writeFile(join(root, "package.json"), JSON.stringify({ dependencies: {} }), "utf8");
+    expect(await detectRemix(root)).toBeNull();
+  });
+
+  it("returns match when @remix-run/react is a dep", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { "@remix-run/react": "2.0.0" } }),
+      "utf8",
+    );
+    const result = await detectRemix(root);
+    expect(result?.framework).toBe("remix");
+  });
+});
+
+describe("discoverRemixRoutes", () => {
+  beforeEach(async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { "@remix-run/react": "2.0.0" } }),
+      "utf8",
+    );
+  });
+
+  it("treats _index.tsx as root", async () => {
+    await touch("app/routes/_index.tsx");
+    await touch("app/routes/about.tsx");
+    const routes = await discoverRemixRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+  });
+
+  it("treats dot-delimited filenames as nested paths", async () => {
+    await touch("app/routes/_index.tsx");
+    await touch("app/routes/blog.tsx");
+    await touch("app/routes/blog.hello.tsx");
+    await touch("app/routes/settings.profile.tsx");
+    const routes = await discoverRemixRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/blog", "/blog/hello", "/settings/profile"]);
+  });
+
+  it("skips $dynamic segments", async () => {
+    await touch("app/routes/_index.tsx");
+    await touch("app/routes/blog.$slug.tsx");
+    await touch("app/routes/users.$id.tsx");
+    const routes = await discoverRemixRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+
+  it("skips api.* routes and files starting with $", async () => {
+    await touch("app/routes/_index.tsx");
+    await touch("app/routes/api.health.tsx");
+    await touch("app/routes/$catchall.tsx");
+    const routes = await discoverRemixRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+});