@wcag-audit/cli 1.0.0-alpha.11

package/src/discovery/sitemap.js

@@ -0,0 +1,73 @@
+// Sitemap fallback. When no framework detector matches (or user
+// passes --sitemap), try fetching /sitemap.xml from the dev server
+// and extracting same-origin URLs.
+
+import { XMLParser } from "fast-xml-parser";
+
+export function parseSitemapXml(xml) {
+  if (!xml || typeof xml !== "string") return [];
+  try {
+    const parser = new XMLParser({ ignoreAttributes: true, parseTagValue: false });
+    const parsed = parser.parse(xml);
+    const urlset = parsed?.urlset?.url;
+    if (!urlset) return [];
+    const entries = Array.isArray(urlset) ? urlset : [urlset];
+    return entries
+      .map((u) => (typeof u === "string" ? u : u?.loc))
+      .filter((u) => typeof u === "string" && u.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+export async function fetchSitemapRoutes(baseUrl, { excludePaths = [] } = {}) {
+  let url;
+  try {
+    url = new URL("/sitemap.xml", baseUrl);
+  } catch {
+    return [];
+  }
+  let xml;
+  try {
+    const res = await fetch(url.toString());
+    if (!res.ok) return [];
+    xml = await res.text();
+  } catch {
+    return [];
+  }
+  const absoluteUrls = parseSitemapXml(xml);
+  const origin = new URL(baseUrl).origin;
+  const routes = [];
+  for (const abs of absoluteUrls) {
+    try {
+      const u = new URL(abs);
+      if (u.origin !== origin) continue; // cross-origin — skip
+      const path = u.pathname || "/";
+      if (isExcluded(path, excludePaths)) continue;
+      routes.push({ path, sourceFile: "(sitemap.xml)" });
+    } catch {
+      // invalid URL — skip
+    }
+  }
+  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/sitemap.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { fetchSitemapRoutes, parseSitemapXml } from "./sitemap.js";
+
+describe("parseSitemapXml", () => {
+  it("returns [] for empty/invalid xml", () => {
+    expect(parseSitemapXml("")).toEqual([]);
+    expect(parseSitemapXml("not xml")).toEqual([]);
+  });
+
+  it("extracts <loc> URLs from a urlset", () => {
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://example.com/</loc></url>
+  <url><loc>https://example.com/about</loc></url>
+  <url><loc>https://example.com/pricing</loc></url>
+</urlset>`;
+    expect(parseSitemapXml(xml).sort()).toEqual([
+      "https://example.com/",
+      "https://example.com/about",
+      "https://example.com/pricing",
+    ]);
+  });
+
+  it("handles a single-url sitemap (non-array loc)", () => {
+    const xml = `<?xml version="1.0"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://example.com/only</loc></url>
+</urlset>`;
+    expect(parseSitemapXml(xml)).toEqual(["https://example.com/only"]);
+  });
+});
+
+describe("fetchSitemapRoutes", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns empty array when fetch fails", async () => {
+    global.fetch.mockRejectedValue(new Error("ECONNREFUSED"));
+    const routes = await fetchSitemapRoutes("http://localhost:3000");
+    expect(routes).toEqual([]);
+  });
+
+  it("returns empty array on non-2xx response", async () => {
+    global.fetch.mockResolvedValue({ ok: false, status: 404, text: async () => "" });
+    const routes = await fetchSitemapRoutes("http://localhost:3000");
+    expect(routes).toEqual([]);
+  });
+
+  it("maps absolute URLs to route paths (same origin)", async () => {
+    global.fetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () => `<?xml version="1.0"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>http://localhost:3000/</loc></url>
+  <url><loc>http://localhost:3000/about</loc></url>
+  <url><loc>https://other.com/ignored</loc></url>
+</urlset>`,
+    });
+    const routes = await fetchSitemapRoutes("http://localhost:3000");
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+    expect(routes[0].sourceFile).toBe("(sitemap.xml)");
+  });
+});

package/src/discovery/sveltekit.js

@@ -0,0 +1,85 @@
+// SvelteKit detector. Routes live at src/routes/**/+page.svelte.
+// Conventions:
+//   (group) folders are route groups — stripped from URL
+//   [param] folders are dynamic — skipped by default
+//   +layout.svelte, +server.ts, +page.ts are not pages — skipped
+
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative, sep } from "path";
+
+export async function detectSvelteKit(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (!all["@sveltejs/kit"]) return null;
+    return { framework: "sveltekit", strategy: "source-walk" };
+  } catch {
+    return null;
+  }
+}
+
+export async function discoverSvelteKitRoutes(root, { excludePaths = [] } = {}) {
+  const routesDir = join(root, "src", "routes");
+  if (!existsSync(routesDir)) return [];
+
+  const files = await walk(routesDir);
+  const routes = [];
+
+  for (const abs of files) {
+    const base = abs.split(sep).pop();
+    if (base !== "+page.svelte") continue;
+
+    const rel = relative(routesDir, 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.length === 0 ? "/" : "/" + visible.join("/");
+
+    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/sveltekit.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 { detectSvelteKit, discoverSvelteKitRoutes } from "./sveltekit.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(), "svkit-")); });
+afterEach(async () => { await rm(root, { recursive: true, force: true }); });
+
+describe("detectSvelteKit", () => {
+  it("returns null when @sveltejs/kit not in deps", async () => {
+    await writeFile(join(root, "package.json"), JSON.stringify({ dependencies: {} }), "utf8");
+    expect(await detectSvelteKit(root)).toBeNull();
+  });
+
+  it("returns match when @sveltejs/kit is a dep", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ devDependencies: { "@sveltejs/kit": "2.0.0" } }),
+      "utf8",
+    );
+    const result = await detectSvelteKit(root);
+    expect(result?.framework).toBe("sveltekit");
+  });
+});
+
+describe("discoverSvelteKitRoutes", () => {
+  beforeEach(async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ devDependencies: { "@sveltejs/kit": "2.0.0" } }),
+      "utf8",
+    );
+  });
+
+  it("discovers +page.svelte routes", async () => {
+    await touch("src/routes/+page.svelte");
+    await touch("src/routes/about/+page.svelte");
+    await touch("src/routes/blog/hello/+page.svelte");
+    const routes = await discoverSvelteKitRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about", "/blog/hello"]);
+  });
+
+  it("ignores +layout, +server, +page.ts files", async () => {
+    await touch("src/routes/+page.svelte");
+    await touch("src/routes/+layout.svelte");
+    await touch("src/routes/about/+page.ts");
+    await touch("src/routes/api/+server.ts");
+    const routes = await discoverSvelteKitRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+
+  it("strips (group) folders", async () => {
+    await touch("src/routes/(marketing)/+page.svelte");
+    await touch("src/routes/(marketing)/about/+page.svelte");
+    const routes = await discoverSvelteKitRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+  });
+
+  it("skips [slug] dynamic segments", async () => {
+    await touch("src/routes/+page.svelte");
+    await touch("src/routes/blog/[slug]/+page.svelte");
+    const routes = await discoverSvelteKitRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+});

package/src/discovery/vite.js

@@ -0,0 +1,94 @@
+// Vite + React Router v6+ detector.
+// Uses regex-based route extraction (not AST parsing) — sufficient
+// for the common patterns: createBrowserRouter([...]) array and
+// <Route path="..." /> JSX. Dynamic segments (:id, :slug) are
+// skipped by default.
+
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative } from "path";
+
+export async function detectVite(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    const hasVite = !!all.vite;
+    const hasRouter = !!all["react-router-dom"] || !!all["react-router"];
+    if (!hasVite || !hasRouter) return null;
+    return { framework: "vite-react-router", strategy: "source-regex" };
+  } catch {
+    return null;
+  }
+}
+
+// Regex for path strings inside route declarations.
+// Matches `path: "..."` (config-style) and `<Route path="...">` (JSX).
+const PATH_RE = /(?:\bpath\s*:\s*|<Route[^>]*\bpath\s*=\s*)(?:"([^"]*)"|'([^']*)')/g;
+
+export async function discoverViteRoutes(root, { excludePaths = [] } = {}) {
+  const kind = await detectVite(root);
+  if (!kind) return [];
+
+  const srcDir = join(root, "src");
+  if (!existsSync(srcDir)) return [];
+
+  const files = (await walk(srcDir)).filter((f) => /\.(tsx|ts|jsx|js)$/.test(f));
+  const routes = [];
+
+  for (const abs of files) {
+    const text = await readFile(abs, "utf8").catch(() => "");
+    if (!text.includes("path")) continue;
+    let m;
+    PATH_RE.lastIndex = 0;
+    while ((m = PATH_RE.exec(text)) !== null) {
+      const raw = m[1] ?? m[2];
+      if (!raw) continue;
+      if (raw.includes(":")) continue;
+      if (raw.includes("*")) continue;
+      const normalized = raw.startsWith("/") ? raw : "/" + raw;
+      if (!isExcluded(normalized, excludePaths)) {
+        routes.push({
+          path: normalized,
+          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/vite.test.js

@@ -0,0 +1,144 @@
+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 { detectVite, discoverViteRoutes } from "./vite.js";
+
+let root;
+
+async function touch(rel, content = "// test") {
+  const abs = join(root, rel);
+  await mkdir(join(abs, ".."), { recursive: true });
+  await writeFile(abs, content, "utf8");
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), "viteproj-"));
+});
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+describe("detectVite", () => {
+  it("returns null when no package.json", async () => {
+    expect(await detectVite(root)).toBeNull();
+  });
+
+  it("returns null when vite not in deps", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ dependencies: { react: "18.0.0" } }),
+      "utf8",
+    );
+    expect(await detectVite(root)).toBeNull();
+  });
+
+  it("returns match when vite + react-router-dom are deps", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({
+        dependencies: { vite: "5.0.0", "react-router-dom": "6.20.0" },
+      }),
+      "utf8",
+    );
+    const result = await detectVite(root);
+    expect(result).not.toBeNull();
+    expect(result.framework).toBe("vite-react-router");
+  });
+
+  it("matches devDependencies too", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({
+        devDependencies: { vite: "5.0.0" },
+        dependencies: { "react-router-dom": "6.0.0" },
+      }),
+      "utf8",
+    );
+    expect(await detectVite(root)).not.toBeNull();
+  });
+});
+
+describe("discoverViteRoutes", () => {
+  beforeEach(async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({
+        dependencies: { vite: "5.0.0", "react-router-dom": "6.20.0" },
+      }),
+      "utf8",
+    );
+  });
+
+  it("extracts routes from createBrowserRouter call", async () => {
+    await touch(
+      "src/main.tsx",
+      `
+import { createBrowserRouter } from "react-router-dom";
+
+const router = createBrowserRouter([
+  { path: "/", element: <Home /> },
+  { path: "/about", element: <About /> },
+  { path: "/pricing", element: <Pricing /> },
+]);
+`,
+    );
+    const routes = await discoverViteRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about", "/pricing"]);
+    expect(routes[0].sourceFile).toBe("src/main.tsx");
+  });
+
+  it("extracts routes from <Route path=...> JSX", async () => {
+    await touch(
+      "src/App.tsx",
+      `
+import { Routes, Route } from "react-router-dom";
+
+export function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Home />} />
+      <Route path="/contact" element={<Contact />} />
+    </Routes>
+  );
+}
+`,
+    );
+    const routes = await discoverViteRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/contact"]);
+  });
+
+  it("skips dynamic segments like :id", async () => {
+    await touch(
+      "src/main.tsx",
+      `
+const router = createBrowserRouter([
+  { path: "/", element: <Home /> },
+  { path: "/users/:id", element: <User /> },
+  { path: "/about", element: <About /> },
+]);
+`,
+    );
+    const routes = await discoverViteRoutes(root);
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about"]);
+  });
+
+  it("applies excludePaths", async () => {
+    await touch(
+      "src/main.tsx",
+      `
+const router = createBrowserRouter([
+  { path: "/", element: <Home /> },
+  { path: "/admin", element: <Admin /> },
+]);
+`,
+    );
+    const routes = await discoverViteRoutes(root, { excludePaths: ["/admin"] });
+    const paths = routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/"]);
+  });
+});

package/src/license/log-usage.js

@@ -0,0 +1,23 @@
+const DEFAULT_API_URL = "https://wcagaudit.io/api/v1/audit/log";
+
+// Fire-and-forget usage logging. Never throws — billing failures
+// should not break the user's scan.
+export async function logUsage(payload, { apiUrl } = {}) {
+  const url = apiUrl || process.env.WCAG_AUDIT_LOG_URL || DEFAULT_API_URL;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        timestamp: new Date().toISOString(),
+        ...payload,
+      }),
+    });
+    if (!res.ok) {
+      return { ok: false, status: res.status };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}

package/src/license/log-usage.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { logUsage } from "./log-usage.js";
+
+describe("logUsage", () => {
+  beforeEach(() => {
+    global.fetch = vi.fn();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fires a POST with the full usage payload", async () => {
+    global.fetch.mockResolvedValueOnce({ ok: true, json: async () => ({ ok: true }) });
+    const result = await logUsage({
+      licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+      pagesCount: 47,
+      newPagesCount: 12,
+      cachedPagesCount: 35,
+      issuesFound: 89,
+      source: "cli",
+      cliVersion: "1.0.0-alpha.1",
+      framework: "nextjs-app",
+    });
+    expect(result.ok).toBe(true);
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+    const [url, init] = global.fetch.mock.calls[0];
+    expect(url).toMatch(/\/v1\/audit\/log$/);
+    const body = JSON.parse(init.body);
+    expect(body.licenseKey).toBe("WCAG-TEST-AAAA-BBBB-CCCC");
+    expect(body.pagesCount).toBe(47);
+    expect(body.newPagesCount).toBe(12);
+    expect(body.source).toBe("cli");
+  });
+
+  it("never throws on network failure — returns { ok: false }", async () => {
+    global.fetch.mockRejectedValueOnce(new Error("socket closed"));
+    const result = await logUsage({
+      licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+      pagesCount: 1,
+      issuesFound: 0,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/socket closed/);
+  });
+});

package/src/license/request-free.js

@@ -0,0 +1,46 @@
+// Free-tier license request. POSTs to /v1/license/free which creates a
+// User + License row (tier: "free") and emails the key to the user.
+// The key is NEVER returned in the response body — it's mailed out,
+// so users have to paste it from their inbox. This matches the
+// Chrome extension free-tier flow.
+
+const DEFAULT_API_URL = "https://wcagaudit.io/api/v1/license/free";
+
+export async function requestFreeLicense({ email, machineId, apiUrl } = {}) {
+  const url = apiUrl || process.env.WCAG_LICENSE_FREE_URL || DEFAULT_API_URL;
+
+  const trimmedEmail = (email || "").trim();
+  if (!trimmedEmail || !trimmedEmail.includes("@")) {
+    return {
+      ok: false,
+      error: "A valid email address is required",
+    };
+  }
+
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email: trimmedEmail, machineId }),
+    });
+
+    const body = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: body.error || `Free license request failed (HTTP ${res.status})`,
+      };
+    }
+
+    return {
+      ok: true,
+      message: body.message || "Check your email for your free license key",
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Network error: ${err.message}`,
+    };
+  }
+}