@riverbankcms/qa 0.2.0

package/dist/cli.js

@@ -0,0 +1,2178 @@
+#!/usr/bin/env node
+
+// src/cli/run.ts
+import { CommanderError as CommanderError2 } from "commander";
+
+// src/cli/program.ts
+import { Command } from "commander";
+import { readFileSync as readFileSync3 } from "fs";
+
+// src/cli/qa-command.ts
+import { CommanderError } from "commander";
+
+// src/url/scope.ts
+function compilePathPatterns(include, exclude) {
+  return {
+    include: include.map((p) => new RegExp(p)),
+    exclude: exclude.map((p) => new RegExp(p))
+  };
+}
+function isAllowedOrigin(target, allowedOrigins) {
+  return allowedOrigins.has(target.origin);
+}
+function isInScopePath(pathname, patterns) {
+  for (const rx of patterns.exclude) {
+    if (rx.test(pathname)) return false;
+  }
+  if (patterns.include.length === 0) return true;
+  for (const rx of patterns.include) {
+    if (rx.test(pathname)) return true;
+  }
+  return false;
+}
+function isNonHttpLink(href) {
+  const trimmed = href.trim();
+  if (trimmed === "" || trimmed === "#") return true;
+  const lower = trimmed.toLowerCase();
+  return lower.startsWith("mailto:") || lower.startsWith("tel:") || lower.startsWith("javascript:");
+}
+
+// src/extract/links.ts
+function decodeHtmlEntities(text) {
+  return text.replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&#39;", "'");
+}
+function normalizeWhitespace(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function extractAnchorLinks(html) {
+  const links = [];
+  const anchorRe = /<a\b[^>]*?\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>([\s\S]*?)<\/a>/gi;
+  let match;
+  while (match = anchorRe.exec(html)) {
+    const href = match[1] ?? match[2] ?? match[3] ?? "";
+    if (!href || isNonHttpLink(href)) continue;
+    const inner = match[4] ?? "";
+    const text = normalizeWhitespace(
+      decodeHtmlEntities(inner.replace(/<[^>]+>/g, ""))
+    );
+    links.push({
+      href,
+      anchorText: text || void 0
+    });
+  }
+  return links;
+}
+
+// src/http/fetch.ts
+import { Agent } from "undici";
+function createDispatcher(ignoreHttpsErrors) {
+  if (!ignoreHttpsErrors) return void 0;
+  return new Agent({
+    connect: {
+      rejectUnauthorized: false
+    }
+  });
+}
+function mergeHeaders(headers, userAgent) {
+  const h = new Headers();
+  for (const [k, v] of Object.entries(headers)) {
+    h.set(k, v);
+  }
+  if (userAgent) h.set("user-agent", userAgent);
+  return h;
+}
+async function fetchWithRedirects(url, opts) {
+  const dispatcher = createDispatcher(opts.ignoreHttpsErrors);
+  const headers = mergeHeaders(opts.headers, opts.userAgent);
+  const redirectChain = [];
+  let current = url;
+  for (let hop = 0; hop <= opts.maxRedirects; hop++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+      const init = {
+        method: "GET",
+        redirect: "manual",
+        headers,
+        signal: controller.signal
+      };
+      if (dispatcher) {
+        init.dispatcher = dispatcher;
+      }
+      const res = await fetch(current, init);
+      const status = res.status;
+      const contentType = res.headers.get("content-type") ?? void 0;
+      if (status >= 300 && status < 400) {
+        const location = res.headers.get("location") ?? void 0;
+        redirectChain.push({
+          url: current,
+          status,
+          ...location ? { location } : {}
+        });
+        if (!location) {
+          const base2 = {
+            url,
+            finalUrl: current,
+            status,
+            redirectChain
+          };
+          if (contentType) base2.contentType = contentType;
+          return base2;
+        }
+        if (hop === opts.maxRedirects) {
+          const base2 = {
+            url,
+            finalUrl: current,
+            status,
+            redirectChain,
+            error: `maxRedirects exceeded (${opts.maxRedirects})`
+          };
+          if (contentType) base2.contentType = contentType;
+          return base2;
+        }
+        const next = new URL(location, current).toString();
+        current = next;
+        continue;
+      }
+      const shouldReadBody = opts.readBody === true || contentType?.toLowerCase().includes("text/") === true || contentType?.toLowerCase().includes("application/xml") === true || contentType?.toLowerCase().includes("application/xhtml+xml") === true || contentType?.toLowerCase().includes("application/json") === true;
+      const bodyText = shouldReadBody ? await res.text() : void 0;
+      const base = {
+        url,
+        finalUrl: current,
+        status,
+        redirectChain
+      };
+      if (contentType) base.contentType = contentType;
+      if (bodyText !== void 0) base.bodyText = bodyText;
+      return base;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        url,
+        finalUrl: current,
+        redirectChain,
+        error: message
+      };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  return {
+    url,
+    finalUrl: current,
+    redirectChain,
+    error: `maxRedirects exceeded (${opts.maxRedirects})`
+  };
+}
+
+// src/url/normalize.ts
+function isDefaultPort(scheme, port) {
+  if (!port) return false;
+  if (scheme === "http:" && port === "80") return true;
+  if (scheme === "https:" && port === "443") return true;
+  return false;
+}
+function shouldStripParam(paramName, cfg) {
+  const lower = paramName.toLowerCase();
+  for (const pattern of cfg.ignoredQueryParamPatterns) {
+    try {
+      if (new RegExp(pattern, "i").test(lower)) return true;
+    } catch {
+    }
+  }
+  if (cfg.dropQueryParamsExceptAllowlist) {
+    return !cfg.allowlistedQueryParams.includes(lower);
+  }
+  if (!cfg.stripTrackingParams) return false;
+  if (cfg.trackingParamNames.includes(lower)) return true;
+  for (const prefix of cfg.trackingParamPrefixes) {
+    if (lower.startsWith(prefix)) return true;
+  }
+  return false;
+}
+function normalizeUrl(input, cfg) {
+  const url = new URL(input);
+  url.hash = "";
+  url.protocol = url.protocol.toLowerCase();
+  url.hostname = url.hostname.toLowerCase();
+  if (isDefaultPort(url.protocol, url.port)) {
+    url.port = "";
+  }
+  if (cfg.normalizeTrailingSlash) {
+    if (url.pathname !== "/" && url.pathname.endsWith("/")) {
+      url.pathname = url.pathname.slice(0, -1);
+    }
+  }
+  const params = new URLSearchParams(url.search);
+  const kept = [];
+  for (const [key, value] of params.entries()) {
+    if (shouldStripParam(key, cfg)) continue;
+    kept.push([key, value]);
+  }
+  kept.sort((a, b) => {
+    if (a[0] < b[0]) return -1;
+    if (a[0] > b[0]) return 1;
+    if (a[1] < b[1]) return -1;
+    if (a[1] > b[1]) return 1;
+    return 0;
+  });
+  url.search = kept.length === 0 ? "" : new URLSearchParams(kept).toString();
+  const normalizedUrl = url.toString();
+  return { normalizedUrl, key: normalizedUrl };
+}
+
+// src/crawl/sitemap.ts
+function extractLocs(xml) {
+  const locs = [];
+  const re = /<loc>\s*([^<\s]+)\s*<\/loc>/gi;
+  let match;
+  while (match = re.exec(xml)) {
+    const raw = match[1]?.trim();
+    if (raw) locs.push(raw);
+  }
+  return locs;
+}
+function looksLikeSitemapIndex(xml) {
+  return /<sitemapindex\b/i.test(xml);
+}
+async function fetchSitemapUrls(sitemapUrl, cfg) {
+  const res = await fetchWithRedirects(sitemapUrl, {
+    timeoutMs: cfg.timeoutMs,
+    maxRedirects: cfg.maxRedirects,
+    headers: cfg.headers,
+    userAgent: cfg.userAgent,
+    ignoreHttpsErrors: cfg.ignoreHttpsErrors,
+    readBody: true
+  });
+  if (!res.status || res.status >= 400) {
+    throw new Error(`HTTP ${res.status ?? "error"}`);
+  }
+  const xml = res.bodyText ?? "";
+  if (!xml) return [];
+  const locs = extractLocs(xml);
+  if (!looksLikeSitemapIndex(xml)) {
+    return locs;
+  }
+  const urls = [];
+  const maxChildSitemaps = 25;
+  for (const child of locs.slice(0, maxChildSitemaps)) {
+    const childRes = await fetchWithRedirects(child, {
+      timeoutMs: cfg.timeoutMs,
+      maxRedirects: cfg.maxRedirects,
+      headers: cfg.headers,
+      userAgent: cfg.userAgent,
+      ignoreHttpsErrors: cfg.ignoreHttpsErrors,
+      readBody: true
+    });
+    if (!childRes.status || childRes.status >= 400) continue;
+    const childXml = childRes.bodyText ?? "";
+    for (const url of extractLocs(childXml)) urls.push(url);
+  }
+  return urls;
+}
+
+// src/crawl/seeds.ts
+async function discoverSeeds(cfg) {
+  const warnings = [];
+  const base = new URL(cfg.baseUrl);
+  const seeds = [base.toString()];
+  if (cfg.sitemap) {
+    const sitemapUrl = new URL("/sitemap.xml", base.origin).toString();
+    try {
+      const urls = await fetchSitemapUrls(sitemapUrl, cfg);
+      for (const url of urls) seeds.push(url);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      warnings.push(`Failed to fetch sitemap: ${sitemapUrl} (${msg})`);
+    }
+  }
+  return { seeds, warnings };
+}
+
+// src/extract/seo.ts
+import * as cheerio from "cheerio";
+function cleanText(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function extractSeo(html) {
+  const $ = cheerio.load(html);
+  const rawTitle = $("head > title").first().text();
+  const title = cleanText(rawTitle);
+  const rawDescription = $('meta[name="description"]').attr("content") ?? "";
+  const description = cleanText(rawDescription);
+  const h1s = $("h1");
+  const h1Count = h1s.length;
+  const h1Text = h1Count > 0 ? cleanText(h1s.first().text()) : "";
+  const canonical = cleanText($('link[rel="canonical"]').attr("href") ?? "");
+  const robots = cleanText($('meta[name="robots"]').attr("content") ?? "");
+  const lang = cleanText($("html").attr("lang") ?? "");
+  const out = { h1Count };
+  if (title) out.title = title;
+  if (description) out.description = description;
+  if (h1Text) out.h1Text = h1Text;
+  if (canonical) out.canonical = canonical;
+  if (robots) out.robots = robots;
+  if (lang) out.lang = lang;
+  return out;
+}
+
+// src/report/constants.ts
+var REPORT_SCHEMA_VERSION = "1.0.0";
+
+// src/crawl/url-policy.ts
+function pathKey(u) {
+  return `${u.origin}${u.pathname}`;
+}
+function isLimitedPath(cfg, u) {
+  return cfg.crawl.limitedPathPrefixes.some((p) => u.pathname.startsWith(p));
+}
+function getPaginationValue(cfg, u) {
+  for (const name of cfg.crawl.paginationParamNames) {
+    const v = u.searchParams.get(name);
+    if (!v) continue;
+    const n = Number(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return void 0;
+}
+function hasOnlyAllowedQueryParams(allowed, u) {
+  for (const key of u.searchParams.keys()) {
+    if (!allowed.has(key.toLowerCase())) return false;
+  }
+  return true;
+}
+function createUrlPolicyState() {
+  return {
+    variantsByPath: /* @__PURE__ */ new Map(),
+    warnedPaths: /* @__PURE__ */ new Set()
+  };
+}
+function shouldEnqueueUrl(cfg, state, normalizedUrl) {
+  const u = new URL(normalizedUrl);
+  const paginationValue = getPaginationValue(cfg, u);
+  if (paginationValue !== void 0 && paginationValue > cfg.crawl.paginationLimit) {
+    return { allow: false, reason: "pagination_limit" };
+  }
+  if (isLimitedPath(cfg, u) && u.search) {
+    const allowed = new Set(cfg.crawl.paginationParamNames.map((n) => n.toLowerCase()));
+    if (!hasOnlyAllowedQueryParams(allowed, u)) {
+      return { allow: false, reason: "limited_path" };
+    }
+  }
+  const key = pathKey(u);
+  const variant = u.search;
+  const set = state.variantsByPath.get(key) ?? /* @__PURE__ */ new Set();
+  if (!set.has(variant) && set.size >= cfg.crawl.perPathQueryVariantLimit) {
+    return { allow: false, reason: "query_variant_limit" };
+  }
+  set.add(variant);
+  state.variantsByPath.set(key, set);
+  return { allow: true };
+}
+
+// src/http/host-delay.ts
+var HostDelayLimiter = class {
+  delayMs;
+  tailByOrigin = /* @__PURE__ */ new Map();
+  lastByOrigin = /* @__PURE__ */ new Map();
+  constructor(delayMs) {
+    this.delayMs = Math.max(0, Math.floor(delayMs));
+  }
+  async waitFor(url) {
+    if (this.delayMs <= 0) return;
+    const origin = new URL(url).origin;
+    const prev = this.tailByOrigin.get(origin) ?? Promise.resolve();
+    const next = prev.then(async () => {
+      const now = Date.now();
+      const last = this.lastByOrigin.get(origin) ?? 0;
+      const remaining = this.delayMs - (now - last);
+      if (remaining > 0) {
+        await new Promise((resolve) => setTimeout(resolve, remaining));
+      }
+      this.lastByOrigin.set(origin, Date.now());
+    });
+    this.tailByOrigin.set(
+      origin,
+      next.catch(() => {
+      })
+    );
+    await next;
+  }
+};
+
+// src/crawl/robots.ts
+function normalizeUserAgent(ua) {
+  return ua.trim().toLowerCase();
+}
+function parseRobotsTxt(text) {
+  const lines = text.split(/\r?\n/).map((l) => l.replace(/#.*$/, "").trim()).filter(Boolean);
+  const groups = [];
+  let current = null;
+  for (const line of lines) {
+    const idx = line.indexOf(":");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const value = line.slice(idx + 1).trim();
+    if (key === "user-agent") {
+      if (!current || current.allow.length + current.disallow.length > 0) {
+        current = { userAgents: [], allow: [], disallow: [] };
+        groups.push(current);
+      }
+      current.userAgents.push(normalizeUserAgent(value));
+      continue;
+    }
+    if (!current) continue;
+    if (key === "allow") current.allow.push(value);
+    if (key === "disallow") current.disallow.push(value);
+  }
+  return groups;
+}
+function longestMatch(pathname, rules) {
+  let best = -1;
+  for (const rule of rules) {
+    if (rule === "") continue;
+    if (rule === "/") return Math.max(best, 1);
+    if (pathname.startsWith(rule)) best = Math.max(best, rule.length);
+  }
+  return best;
+}
+function pickGroups(groups, ua) {
+  const uaNorm = normalizeUserAgent(ua);
+  const specific = groups.filter((g) => g.userAgents.some((a) => a !== "*" && uaNorm.includes(a)));
+  if (specific.length) return specific;
+  const star = groups.filter((g) => g.userAgents.includes("*"));
+  return star;
+}
+var RobotsPolicy = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cache = /* @__PURE__ */ new Map();
+  async canFetch(url) {
+    if (!this.cfg.respectRobots) return { allowed: true };
+    const u = new URL(url);
+    const origin = u.origin;
+    const cached = this.cache.get(origin);
+    let parsed = cached;
+    if (!parsed) {
+      const robotsUrl = new URL("/robots.txt", origin).toString();
+      const res = await fetchWithRedirects(robotsUrl, {
+        timeoutMs: this.cfg.timeoutMs,
+        maxRedirects: this.cfg.maxRedirects,
+        headers: this.cfg.headers,
+        userAgent: this.cfg.userAgent,
+        ignoreHttpsErrors: this.cfg.ignoreHttpsErrors,
+        readBody: true
+      });
+      if (!res.status || res.status >= 400) {
+        parsed = "missing";
+      } else {
+        try {
+          const txt = res.bodyText ?? "";
+          parsed = txt ? parseRobotsTxt(txt) : "missing";
+        } catch {
+          parsed = "error";
+        }
+      }
+      this.cache.set(origin, parsed);
+    }
+    if (parsed === "missing" || parsed === "error") return { allowed: true };
+    const groups = pickGroups(parsed, this.cfg.userAgent ?? "qa");
+    if (groups.length === 0) return { allowed: true };
+    const pathname = u.pathname || "/";
+    const allowLen = Math.max(...groups.map((g) => longestMatch(pathname, g.allow)), -1);
+    const disallowLen = Math.max(...groups.map((g) => longestMatch(pathname, g.disallow)), -1);
+    if (disallowLen > allowLen) return { allowed: false, reason: "disallowed" };
+    return { allowed: true };
+  }
+};
+
+// src/crawl/crawler.ts
+function addReferrer(state, targetKey, ref) {
+  const list = state.referrersByKey.get(targetKey) ?? [];
+  if (list.some((r) => r.url === ref.url && r.anchorText === ref.anchorText)) {
+    return;
+  }
+  list.push(ref);
+  state.referrersByKey.set(targetKey, list);
+}
+function uniqByKey(items, keyFn) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of items) {
+    const key = keyFn(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+async function runWithConcurrency(concurrency, tasks) {
+  const results = new Array(tasks.length);
+  let index = 0;
+  async function worker() {
+    while (true) {
+      const current = index;
+      index += 1;
+      if (current >= tasks.length) return;
+      const task = tasks[current];
+      if (!task) return;
+      results[current] = await task();
+    }
+  }
+  const workers = Array.from({ length: Math.max(1, concurrency) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+async function crawlSite(cfg) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const runWarnings = [];
+  const capsReached = {
+    maxPages: false,
+    maxDepth: false,
+    maxRedirects: false,
+    queryVariantLimit: false,
+    paginationLimit: false,
+    externalLinksLimit: false
+  };
+  const allowedOrigins = /* @__PURE__ */ new Set([new URL(cfg.baseUrl).origin]);
+  const patterns = compilePathPatterns(cfg.include, cfg.exclude);
+  const state = {
+    pagesByKey: /* @__PURE__ */ new Map(),
+    referrersByKey: /* @__PURE__ */ new Map()
+  };
+  const urlPolicyState = createUrlPolicyState();
+  const hostDelay = new HostDelayLimiter(cfg.crawl.requestDelayMs);
+  const robots = new RobotsPolicy(cfg);
+  const seedResult = await discoverSeeds(cfg);
+  runWarnings.push(...seedResult.warnings);
+  const normalizedSeeds = uniqByKey(
+    seedResult.seeds.filter((u) => {
+      try {
+        const parsed = new URL(u);
+        if (!isAllowedOrigin(parsed, allowedOrigins)) return false;
+        return isInScopePath(parsed.pathname, patterns);
+      } catch {
+        return false;
+      }
+    }).map((u) => normalizeUrl(u, cfg.url)).filter((n) => {
+      const decision = shouldEnqueueUrl(cfg, urlPolicyState, n.normalizedUrl);
+      if (decision.allow) return true;
+      if (decision.reason === "pagination_limit") capsReached.paginationLimit = true;
+      if (decision.reason === "query_variant_limit") capsReached.queryVariantLimit = true;
+      return false;
+    }),
+    (n) => n.key
+  ).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+  let fetchedCount = 0;
+  let frontier = normalizedSeeds.map((s) => ({
+    url: s.normalizedUrl,
+    key: s.key,
+    depth: 0
+  }));
+  for (let depth = 0; depth <= cfg.maxDepth; depth++) {
+    if (frontier.length === 0) break;
+    const remaining = cfg.maxPages - fetchedCount;
+    if (remaining <= 0) {
+      capsReached.maxPages = true;
+      break;
+    }
+    const batch = frontier.filter((f) => !state.pagesByKey.has(f.key)).slice(0, remaining);
+    if (batch.length < frontier.filter((f) => !state.pagesByKey.has(f.key)).length) {
+      capsReached.maxPages = true;
+    }
+    const tasks = batch.map((item) => async () => {
+      await hostDelay.waitFor(item.url);
+      const robotsDecision = await robots.canFetch(item.url);
+      if (!robotsDecision.allowed) {
+        const page2 = {
+          url: item.url,
+          finalUrl: item.url,
+          redirectChain: [],
+          depth: item.depth,
+          discoveredFrom: [],
+          error: "Disallowed by robots.txt"
+        };
+        return { item, page: page2, discovered: [] };
+      }
+      const res = await fetchWithRedirects(item.url, {
+        timeoutMs: cfg.timeoutMs,
+        maxRedirects: cfg.maxRedirects,
+        headers: cfg.headers,
+        userAgent: cfg.userAgent,
+        ignoreHttpsErrors: cfg.ignoreHttpsErrors
+      });
+      if (res.error === `maxRedirects exceeded (${cfg.maxRedirects})`) {
+        capsReached.maxRedirects = true;
+      }
+      const page = {
+        url: item.url,
+        finalUrl: res.finalUrl,
+        status: res.status,
+        redirectChain: res.redirectChain.map((h) => ({
+          url: h.url,
+          status: h.status,
+          location: h.location
+        })),
+        depth: item.depth,
+        discoveredFrom: [],
+        error: res.error
+      };
+      const discovered = [];
+      const isHtml = res.contentType?.toLowerCase().includes("text/html") === true || res.contentType?.toLowerCase().includes("application/xhtml+xml") === true;
+      if (res.bodyText && isHtml) {
+        const seo = extractSeo(res.bodyText);
+        page.title = seo.title;
+        page.description = seo.description;
+        page.h1Text = seo.h1Text;
+        page.h1Count = seo.h1Count;
+        page.canonical = seo.canonical;
+        page.robots = seo.robots;
+        page.lang = seo.lang;
+        const links = extractAnchorLinks(res.bodyText);
+        const outboundLinks = [];
+        for (const link of links) {
+          const href = link.href;
+          if (!href || isNonHttpLink(href)) continue;
+          try {
+            const abs = new URL(href, res.finalUrl).toString();
+            const absUrl = new URL(abs);
+            const internal = isAllowedOrigin(absUrl, allowedOrigins);
+            outboundLinks.push({
+              url: href,
+              resolvedUrl: abs,
+              internal,
+              anchorText: link.anchorText
+            });
+            if (!internal) continue;
+            if (!isInScopePath(absUrl.pathname, patterns)) continue;
+            discovered.push({ url: abs, anchorText: link.anchorText });
+          } catch {
+          }
+        }
+        page.outboundLinks = outboundLinks;
+      }
+      return { item, page, discovered };
+    });
+    const results = await runWithConcurrency(cfg.concurrency, tasks);
+    const nextKeys = /* @__PURE__ */ new Set();
+    for (const r of results) {
+      fetchedCount += 1;
+      state.pagesByKey.set(r.item.key, r.page);
+      const refs = state.referrersByKey.get(r.item.key) ?? [];
+      r.page.discoveredFrom = refs.slice().sort((a, b) => a.url < b.url ? -1 : a.url > b.url ? 1 : 0);
+      for (const d of r.discovered) {
+        const normalized = normalizeUrl(d.url, cfg.url);
+        const decision = shouldEnqueueUrl(cfg, urlPolicyState, normalized.normalizedUrl);
+        if (!decision.allow) {
+          if (decision.reason === "pagination_limit") {
+            capsReached.paginationLimit = true;
+            const msg = `Pagination limit hit (limit=${cfg.crawl.paginationLimit}) for ${normalized.normalizedUrl}`;
+            if (!runWarnings.includes(msg)) runWarnings.push(msg);
+          } else if (decision.reason === "query_variant_limit") {
+            capsReached.queryVariantLimit = true;
+            const msg = `Query variant limit hit (limit=${cfg.crawl.perPathQueryVariantLimit}) for ${new URL(normalized.normalizedUrl).pathname}`;
+            if (!runWarnings.includes(msg)) runWarnings.push(msg);
+          }
+          continue;
+        }
+        nextKeys.add(normalized.key);
+        addReferrer(state, normalized.key, { url: r.page.finalUrl, anchorText: d.anchorText });
+      }
+    }
+    if (depth === cfg.maxDepth) {
+      if (nextKeys.size > 0) capsReached.maxDepth = true;
+      break;
+    }
+    const nextCandidates = [];
+    for (const key of nextKeys) {
+      if (state.pagesByKey.has(key)) continue;
+      nextCandidates.push({ url: key, key, depth: depth + 1 });
+    }
+    frontier = uniqByKey(nextCandidates, (n) => n.key).sort(
+      (a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0
+    );
+  }
+  const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const pages = Array.from(state.pagesByKey.entries()).map(([, p]) => p).sort((a, b) => {
+    if (a.depth !== b.depth) return a.depth - b.depth;
+    if (a.url < b.url) return -1;
+    if (a.url > b.url) return 1;
+    return 0;
+  });
+  const report = {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    run: {
+      startedAt,
+      endedAt,
+      baseUrl: cfg.baseUrl,
+      config: {
+        mode: cfg.mode,
+        reportFormat: cfg.reportFormat,
+        outputDir: cfg.outputDir,
+        maxPages: cfg.maxPages,
+        maxDepth: cfg.maxDepth,
+        maxRedirects: cfg.maxRedirects,
+        concurrency: cfg.concurrency,
+        timeoutMs: cfg.timeoutMs,
+        sitemap: cfg.sitemap,
+        respectRobots: cfg.respectRobots,
+        externalLinks: cfg.externalLinks,
+        ignoreHttpsErrors: cfg.ignoreHttpsErrors,
+        render: {
+          maxRenderPages: cfg.render.maxRenderPages,
+          screenshotFullPage: cfg.render.screenshotFullPage,
+          breakpoints: cfg.render.breakpoints
+        },
+        crawl: {
+          perPathQueryVariantLimit: cfg.crawl.perPathQueryVariantLimit,
+          paginationParamNames: cfg.crawl.paginationParamNames,
+          paginationLimit: cfg.crawl.paginationLimit,
+          limitedPathPrefixes: cfg.crawl.limitedPathPrefixes,
+          requestDelayMs: cfg.crawl.requestDelayMs
+        },
+        external: {
+          maxExternalLinksChecked: cfg.external.maxExternalLinksChecked
+        },
+        include: cfg.include,
+        exclude: cfg.exclude,
+        userAgent: cfg.userAgent
+      },
+      warnings: runWarnings,
+      capsReached
+    },
+    pages
+  };
+  return { report };
+}
+
+// src/config/defaults.ts
+function defaultConfigForBaseUrl(baseUrl) {
+  const url = new URL(baseUrl);
+  const isLocalhost = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  return {
+    baseUrl,
+    outputDir: "qa-output",
+    mode: "crawl",
+    reportFormat: "both",
+    maxPages: 500,
+    maxDepth: 6,
+    maxRedirects: 10,
+    concurrency: 4,
+    timeoutMs: 15e3,
+    sitemap: true,
+    respectRobots: !isLocalhost,
+    externalLinks: false,
+    ignoreHttpsErrors: false,
+    userAgent: void 0,
+    headers: {},
+    include: [],
+    exclude: [],
+    url: {
+      normalizeTrailingSlash: true,
+      stripTrackingParams: true,
+      trackingParamPrefixes: ["utm_"],
+      trackingParamNames: ["gclid", "fbclid", "msclkid", "ref"],
+      dropQueryParamsExceptAllowlist: false,
+      allowlistedQueryParams: ["page"],
+      ignoredQueryParamPatterns: ["session", "token"]
+    },
+    seo: {
+      titleMin: 10,
+      titleMax: 60,
+      descriptionMin: 50,
+      descriptionMax: 160
+    },
+    render: {
+      maxRenderPages: 50,
+      screenshotFullPage: true,
+      breakpoints: {
+        mobile: { width: 375, height: 812 },
+        tablet: { width: 768, height: 1024 },
+        desktop: { width: 1440, height: 900 }
+      }
+    },
+    crawl: {
+      perPathQueryVariantLimit: 3,
+      paginationParamNames: ["page"],
+      paginationLimit: 5,
+      limitedPathPrefixes: ["/search", "/calendar", "/events"],
+      requestDelayMs: 0
+    },
+    external: {
+      maxExternalLinksChecked: 0
+    }
+  };
+}
+
+// src/config/load-config.ts
+import { readFileSync } from "fs";
+import YAML from "yaml";
+function loadConfigFile(configPath) {
+  const raw = readFileSync(configPath, "utf8");
+  const trimmed = raw.trim();
+  if (configPath.endsWith(".json")) {
+    return JSON.parse(trimmed);
+  }
+  try {
+    const parsed = YAML.parse(trimmed);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  return JSON.parse(trimmed);
+}
+
+// src/config/merge.ts
+function mergeConfig(base, override) {
+  return {
+    ...base,
+    ...override,
+    headers: {
+      ...base.headers,
+      ...override.headers ?? {}
+    },
+    include: override.include ?? base.include,
+    exclude: override.exclude ?? base.exclude,
+    url: {
+      ...base.url,
+      ...override.url ?? {}
+    },
+    seo: {
+      ...base.seo,
+      ...override.seo ?? {}
+    },
+    render: {
+      ...base.render,
+      ...override.render ?? {},
+      breakpoints: {
+        ...base.render.breakpoints,
+        ...override.render?.breakpoints ?? {}
+      }
+    },
+    crawl: {
+      ...base.crawl,
+      ...override.crawl ?? {}
+    },
+    external: {
+      ...base.external,
+      ...override.external ?? {}
+    }
+  };
+}
+
+// src/config/parse-headers.ts
+function parseHeaderPairs(pairs) {
+  if (!pairs || pairs.length === 0) return {};
+  const headers = {};
+  for (const pair of pairs) {
+    const index = pair.indexOf(":");
+    if (index <= 0) continue;
+    const key = pair.slice(0, index).trim();
+    const value = pair.slice(index + 1).trim();
+    if (!key) continue;
+    headers[key] = value;
+  }
+  return headers;
+}
+
+// src/report/write-json.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+function writeJsonReport(outputDir, report) {
+  mkdirSync(outputDir, { recursive: true });
+  const path = join(outputDir, "report.json");
+  writeFileSync(path, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  return path;
+}
+
+// src/checks/generate-issues.ts
+function isLocalBaseUrl(baseUrl) {
+  const u = new URL(baseUrl);
+  return u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+}
+function severityForNoindex(cfg) {
+  return isLocalBaseUrl(cfg.baseUrl) ? "info" : "warning";
+}
+function push(issues, severity, type, message, context) {
+  const issue = { severity, type, message };
+  if (context) issue.context = context;
+  issues.push(issue);
+}
+function hasNoindex(robots) {
+  if (!robots) return false;
+  return robots.toLowerCase().split(",").some((t) => t.trim() === "noindex");
+}
+function generateIssues(cfg, report) {
+  const issues = [];
+  const baseOrigin = new URL(cfg.baseUrl).origin;
+  for (const page of report.pages) {
+    if (page.redirectChain.length >= 2) {
+      push(issues, "warning", "redirect_chain_long", `Redirect chain length ${page.redirectChain.length}`, {
+        url: page.url,
+        finalUrl: page.finalUrl,
+        chain: page.redirectChain,
+        referrers: page.discoveredFrom
+      });
+    } else if (page.redirectChain.length === 1) {
+      push(issues, "info", "redirect", "URL redirects", {
+        url: page.url,
+        finalUrl: page.finalUrl,
+        chain: page.redirectChain,
+        referrers: page.discoveredFrom
+      });
+    }
+    if (page.error) {
+      if (page.error === "Disallowed by robots.txt") {
+        push(issues, "info", "robots_disallowed", "Skipped (disallowed by robots.txt)", {
+          url: page.url,
+          referrers: page.discoveredFrom
+        });
+        continue;
+      }
+      push(issues, "error", "fetch_error", "Failed to fetch page", {
+        url: page.url,
+        error: page.error,
+        referrers: page.discoveredFrom
+      });
+      continue;
+    }
+    if (typeof page.status === "number" && page.status >= 400) {
+      push(issues, "error", "broken_internal_link", `HTTP ${page.status}`, {
+        url: page.url,
+        status: page.status,
+        referrers: page.discoveredFrom
+      });
+      continue;
+    }
+    const isHtml = page.h1Count !== void 0 || page.title !== void 0 || page.description !== void 0;
+    if (!isHtml) continue;
+    if (page.status !== 200) continue;
+    if (!page.title) {
+      push(issues, "error", "missing_title", "Missing <title>", { url: page.finalUrl });
+    } else {
+      if (page.title.length < cfg.seo.titleMin) {
+        push(issues, "warning", "title_too_short", "Title too short", {
+          url: page.finalUrl,
+          length: page.title.length,
+          min: cfg.seo.titleMin
+        });
+      }
+      if (page.title.length > cfg.seo.titleMax) {
+        push(issues, "warning", "title_too_long", "Title too long", {
+          url: page.finalUrl,
+          length: page.title.length,
+          max: cfg.seo.titleMax
+        });
+      }
+    }
+    if (!page.description) {
+      push(issues, "warning", "missing_meta_description", 'Missing meta[name="description"]', {
+        url: page.finalUrl
+      });
+    } else {
+      if (page.description.length < cfg.seo.descriptionMin) {
+        push(issues, "warning", "meta_description_too_short", "Meta description too short", {
+          url: page.finalUrl,
+          length: page.description.length,
+          min: cfg.seo.descriptionMin
+        });
+      }
+      if (page.description.length > cfg.seo.descriptionMax) {
+        push(issues, "warning", "meta_description_too_long", "Meta description too long", {
+          url: page.finalUrl,
+          length: page.description.length,
+          max: cfg.seo.descriptionMax
+        });
+      }
+    }
+    const h1Count = page.h1Count ?? 0;
+    if (h1Count === 0) {
+      push(issues, "warning", "missing_h1", "Missing <h1>", { url: page.finalUrl });
+    } else if (h1Count > 1) {
+      push(issues, "warning", "multiple_h1", "Multiple <h1> elements", {
+        url: page.finalUrl,
+        count: h1Count
+      });
+    }
+    if (!page.canonical) {
+      push(issues, "warning", "missing_canonical", "Missing canonical link", { url: page.finalUrl });
+    } else {
+      try {
+        const canonicalUrl = new URL(page.canonical, page.finalUrl);
+        if (canonicalUrl.origin !== baseOrigin) {
+          push(issues, "warning", "canonical_cross_origin", "Canonical points to different origin", {
+            url: page.finalUrl,
+            canonical: canonicalUrl.toString(),
+            baseOrigin
+          });
+        }
+      } catch {
+        push(issues, "warning", "canonical_invalid", "Canonical is not a valid URL", {
+          url: page.finalUrl,
+          canonical: page.canonical
+        });
+      }
+    }
+    if (hasNoindex(page.robots)) {
+      push(issues, severityForNoindex(cfg), "noindex", "noindex present", {
+        url: page.finalUrl,
+        robots: page.robots
+      });
+    }
+  }
+  function duplicateIssue(type, value, urls) {
+    if (urls.length <= 1) return;
+    push(issues, "warning", type, `Duplicate ${type.replace("duplicate_", "").replaceAll("_", " ")}`, {
+      value,
+      pages: urls.slice().sort(),
+      count: urls.length
+    });
+  }
+  const titles = /* @__PURE__ */ new Map();
+  const descriptions = /* @__PURE__ */ new Map();
+  const h1s = /* @__PURE__ */ new Map();
+  for (const page of report.pages) {
+    if (page.status !== 200) continue;
+    if (page.title) titles.set(page.title, [...titles.get(page.title) ?? [], page.finalUrl]);
+    if (page.description)
+      descriptions.set(page.description, [
+        ...descriptions.get(page.description) ?? [],
+        page.finalUrl
+      ]);
+    if (page.h1Text) h1s.set(page.h1Text, [...h1s.get(page.h1Text) ?? [], page.finalUrl]);
+  }
+  for (const [value, urls] of titles) duplicateIssue("duplicate_title", value, urls);
+  for (const [value, urls] of descriptions) duplicateIssue("duplicate_description", value, urls);
+  for (const [value, urls] of h1s) duplicateIssue("duplicate_h1", value, urls);
+  return issues;
+}
+
+// src/report/write-html.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/report/build-html.ts
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function formatDurationMs(startedAt, endedAt) {
+  const start = Date.parse(startedAt);
+  const end = Date.parse(endedAt);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return void 0;
+  const ms = Math.max(0, end - start);
+  if (ms < 1e3) return `${ms}ms`;
+  const s = Math.round(ms / 100) / 10;
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rs = Math.round((s - m * 60) * 10) / 10;
+  return `${m}m ${rs}s`;
+}
+function issueCountsByType(issues) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const issue of issues) counts.set(issue.type, (counts.get(issue.type) ?? 0) + 1);
+  return [...counts.entries()].map(([type, count]) => ({ type, count })).sort((a, b) => b.count - a.count || a.type.localeCompare(b.type));
+}
+function issueCountsBySeverity(issues) {
+  const out = { error: 0, warning: 0, info: 0 };
+  for (const issue of issues) out[issue.severity] = (out[issue.severity] ?? 0) + 1;
+  return out;
+}
+function getPageIssues(issues, page) {
+  const urls = /* @__PURE__ */ new Set([page.url, page.finalUrl]);
+  return issues.filter((i) => {
+    const u = i.context?.url;
+    return typeof u === "string" && urls.has(u);
+  });
+}
+function safeString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function brokenLinkEntries(issues) {
+  const broken = issues.filter((i) => i.type === "broken_internal_link" || i.type === "fetch_error");
+  const out = [];
+  for (const issue of broken) {
+    const url = safeString(issue.context?.url);
+    if (!url) continue;
+    out.push({ url, issue });
+  }
+  return out.sort((a, b) => a.url.localeCompare(b.url));
+}
+function duplicateClusters(issues) {
+  const types = /* @__PURE__ */ new Set(["duplicate_title", "duplicate_description", "duplicate_h1"]);
+  return issues.filter((i) => types.has(i.type)).sort((a, b) => a.type.localeCompare(b.type));
+}
+function pageTitle(page) {
+  return page.title ?? page.finalUrl;
+}
+function statusBadge(page) {
+  const status = page.status;
+  if (typeof status !== "number") return `<span class="badge badge-muted">unknown</span>`;
+  if (status >= 400) return `<span class="badge badge-error">${status}</span>`;
+  if (status >= 300) return `<span class="badge badge-warn">${status}</span>`;
+  return `<span class="badge badge-ok">${status}</span>`;
+}
+function formatMaybe(value) {
+  return value ? escapeHtml(value) : `<span class="muted">\u2014</span>`;
+}
+function renderReferrers(referrers) {
+  if (!Array.isArray(referrers) || referrers.length === 0) {
+    return `<div class="muted">No referrers captured.</div>`;
+  }
+  const rows = referrers.map((r) => {
+    if (!r || typeof r !== "object") return "";
+    const rec = r;
+    const url = safeString(rec["url"]);
+    const anchorText = safeString(rec["anchorText"]);
+    const urlHtml = url ? `<a href="${escapeHtml(url)}">${escapeHtml(url)}</a>` : `<span class="muted">\u2014</span>`;
+    const anchorHtml = anchorText ? escapeHtml(anchorText) : `<span class="muted">\u2014</span>`;
+    return `<li>${urlHtml}<span class="sep"> \xB7 </span><span class="muted">${anchorHtml}</span></li>`;
+  }).filter(Boolean).join("");
+  return `<ul class="list">${rows}</ul>`;
+}
+function buildHtmlReport(report) {
+  const issues = report.issues ?? [];
+  const bySeverity = issueCountsBySeverity(issues);
+  const byType = issueCountsByType(issues);
+  const duration = formatDurationMs(report.run.startedAt, report.run.endedAt);
+  const caps = report.run.capsReached;
+  const brokenLinks = brokenLinkEntries(issues);
+  const duplicates = duplicateClusters(issues);
+  const pagesHtml = report.pages.map((page) => {
+    const pageIssues = getPageIssues(issues, page);
+    const inboundCount = page.discoveredFrom.length;
+    const outbound = page.outboundLinks ?? [];
+    const outboundInternal = outbound.filter((l) => l.internal).length;
+    const outboundExternal = outbound.filter((l) => !l.internal).length;
+    const renderResults = page.render?.results ?? [];
+    const issueList = pageIssues.length ? `<ul class="list">${pageIssues.map((i) => `<li><span class="sev sev-${i.severity}">${i.severity}</span> <code>${escapeHtml(i.type)}</code> \u2014 ${escapeHtml(i.message)}</li>`).join("")}</ul>` : `<div class="muted">No issues captured for this page.</div>`;
+    const redirectChainHtml = page.redirectChain.length === 0 ? `<span class="muted">\u2014</span>` : `<ol class="list">${page.redirectChain.map(
+      (h) => `<li><code>${escapeHtml(String(h.status))}</code> ${escapeHtml(h.url)}${h.location ? ` <span class="muted">\u2192</span> ${escapeHtml(h.location)}` : ""}</li>`
+    ).join("")}</ol>`;
+    const inboundHtml = inboundCount === 0 ? `<div class="muted">\u2014</div>` : `<ul class="list">${page.discoveredFrom.map((r) => {
+      const a = r.anchorText ? ` <span class="muted">(${escapeHtml(r.anchorText)})</span>` : "";
+      return `<li><a href="${escapeHtml(r.url)}">${escapeHtml(r.url)}</a>${a}</li>`;
+    }).join("")}</ul>`;
+    const renderHtml = renderResults.length === 0 ? `<div class="muted">Not rendered.</div>` : `<div class="grid">${renderResults.map((r) => {
+      const consoleCount = r.consoleErrors.length;
+      const reqFailCount = r.requestFailures.length;
+      const meta = [
+        `viewport ${r.viewport.width}\xD7${r.viewport.height}`,
+        r.fullPage ? "full page" : "viewport only",
+        typeof r.pageStatus === "number" ? `status ${r.pageStatus}` : "status unknown",
+        r.pageError ? "page error" : "ok",
+        consoleCount ? `${consoleCount} console errors` : "0 console errors",
+        reqFailCount ? `${reqFailCount} request failures` : "0 request failures"
+      ].join(" \xB7 ");
+      return `
+                  <div class="card">
+                    <div><strong>${escapeHtml(r.breakpoint)}</strong> <span class="muted">${escapeHtml(meta)}</span></div>
+                    <div style="margin-top:8px">
+                      <a href="${escapeHtml(r.screenshotPath)}" target="_blank" rel="noreferrer">
+                        <img src="${escapeHtml(r.screenshotPath)}" alt="${escapeHtml(page.finalUrl)} ${escapeHtml(r.breakpoint)}" style="width:100%; border-radius:8px; border:1px solid var(--border)" />
+                      </a>
+                    </div>
+                  </div>
+                `.trim();
+    }).join("")}</div>`;
+    return `
+        <details class="card" id="page-${encodeURIComponent(page.finalUrl)}">
+          <summary class="card-summary">
+            ${statusBadge(page)}
+            <span class="page-title">${escapeHtml(pageTitle(page))}</span>
+            <span class="muted">${escapeHtml(page.finalUrl)}</span>
+            ${renderResults.length ? `<span class="badge badge-muted">rendered</span>` : ""}
+          </summary>
+          <div class="grid">
+            <div>
+              <h4>Overview</h4>
+              <table class="table">
+                <tr><th>URL</th><td><code>${escapeHtml(page.url)}</code></td></tr>
+                <tr><th>Final URL</th><td><code>${escapeHtml(page.finalUrl)}</code></td></tr>
+                <tr><th>Status</th><td>${statusBadge(page)}</td></tr>
+                <tr><th>Depth</th><td>${escapeHtml(String(page.depth))}</td></tr>
+                <tr><th>Inbound links</th><td>${escapeHtml(String(inboundCount))}</td></tr>
+                <tr><th>Outbound links</th><td>${escapeHtml(String(outbound.length))} <span class="muted">(internal ${outboundInternal}, external ${outboundExternal})</span></td></tr>
+              </table>
+            </div>
+            <div>
+              <h4>SEO</h4>
+              <table class="table">
+                <tr><th>Title</th><td>${formatMaybe(page.title)}</td></tr>
+                <tr><th>Description</th><td>${formatMaybe(page.description)}</td></tr>
+                <tr><th>H1</th><td>${formatMaybe(page.h1Text)} <span class="muted">(count ${escapeHtml(String(page.h1Count ?? 0))})</span></td></tr>
+                <tr><th>Canonical</th><td>${formatMaybe(page.canonical)}</td></tr>
+                <tr><th>Robots</th><td>${formatMaybe(page.robots)}</td></tr>
+                <tr><th>Lang</th><td>${formatMaybe(page.lang)}</td></tr>
+              </table>
+            </div>
+          </div>
+
+          <div class="grid">
+            <div>
+              <h4>Redirect Chain</h4>
+              ${redirectChainHtml}
+            </div>
+            <div>
+              <h4>Referrers</h4>
+              ${inboundHtml}
+            </div>
+          </div>
+
+          <h4>Render</h4>
+          ${renderHtml}
+
+          <h4>Issues</h4>
+          ${issueList}
+        </details>
+      `.trim();
+  }).join("\n");
+  const brokenLinksHtml = brokenLinks.length === 0 ? `<div class="muted">No broken links found.</div>` : `<div class="stack">${brokenLinks.map(({ url, issue }) => {
+    const statusRaw = issue.context?.["status"];
+    const status = typeof statusRaw === "number" ? String(statusRaw) : typeof statusRaw === "string" ? statusRaw : void 0;
+    const message = issue.type === "fetch_error" ? safeString(issue.context?.error) ?? issue.message : issue.message;
+    return `
+              <details class="card">
+                <summary class="card-summary">
+                  <span class="sev sev-${issue.severity}">${issue.severity}</span>
+                  <span class="page-title">${escapeHtml(url)}</span>
+                  ${status ? `<span class="muted">HTTP ${escapeHtml(status)}</span>` : ""}
+                </summary>
+                <div class="muted">${escapeHtml(message)}</div>
+                <h4>Referrers</h4>
+                ${renderReferrers(issue.context?.referrers)}
+              </details>
+            `.trim();
+  }).join("\n")}</div>`;
+  const duplicatesHtml = duplicates.length === 0 ? `<div class="muted">No duplicates found.</div>` : `<div class="stack">${duplicates.map((issue) => {
+    const value = safeString(issue.context?.value) ?? "";
+    const pages = Array.isArray(issue.context?.pages) ? issue.context?.pages : [];
+    return `
+              <details class="card">
+                <summary class="card-summary">
+                  <span class="sev sev-${issue.severity}">${issue.severity}</span>
+                  <code>${escapeHtml(issue.type)}</code>
+                  <span class="muted">${escapeHtml(String(issue.context?.count ?? pages.length))} pages</span>
+                </summary>
+                <div><strong>Value</strong>: ${value ? `<code>${escapeHtml(value)}</code>` : `<span class="muted">\u2014</span>`}</div>
+                <h4>Pages</h4>
+                <ul class="list">${pages.map((p) => typeof p === "string" ? `<li><a href="${escapeHtml(p)}">${escapeHtml(p)}</a></li>` : "").filter(Boolean).join("")}</ul>
+              </details>
+            `.trim();
+  }).join("\n")}</div>`;
+  const capsHtml = `
+    <ul class="list">
+      <li>maxPages: ${caps.maxPages ? `<span class="badge badge-warn">reached</span>` : `<span class="badge badge-ok">ok</span>`}</li>
+      <li>maxDepth: ${caps.maxDepth ? `<span class="badge badge-warn">reached</span>` : `<span class="badge badge-ok">ok</span>`}</li>
+      <li>maxRedirects: ${caps.maxRedirects ? `<span class="badge badge-warn">reached</span>` : `<span class="badge badge-ok">ok</span>`}</li>
+      <li>queryVariantLimit: ${caps.queryVariantLimit ? `<span class="badge badge-warn">reached</span>` : `<span class="badge badge-ok">ok</span>`}</li>
+      <li>paginationLimit: ${caps.paginationLimit ? `<span class="badge badge-warn">reached</span>` : `<span class="badge badge-ok">ok</span>`}</li>
+      <li>externalLinksLimit: ${caps.externalLinksLimit ? `<span class="badge badge-warn">reached</span>` : `<span class="badge badge-ok">ok</span>`}</li>
+    </ul>
+  `.trim();
+  const issueTypeList = byType.map(({ type, count }) => `<li><code>${escapeHtml(type)}</code> <span class="muted">(${count})</span></li>`).join("");
+  const configJson = escapeHtml(JSON.stringify(report.run.config, null, 2));
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>QA Report \u2014 ${escapeHtml(report.run.baseUrl)}</title>
+  <style>
+    :root { color-scheme: light; --bg:#0b0f14; --panel:#111827; --text:#e5e7eb; --muted:#9ca3af; --ok:#10b981; --warn:#f59e0b; --err:#ef4444; --info:#60a5fa; --border:#1f2937; }
+    body { margin:0; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial; background: var(--bg); color: var(--text); }
+    a { color: #93c5fd; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 0.95em; }
+    .container { max-width: 1100px; margin: 0 auto; padding: 24px; }
+    .header { display:flex; flex-wrap:wrap; gap: 12px; align-items: baseline; }
+    .header h1 { margin: 0; font-size: 20px; }
+    .muted { color: var(--muted); }
+    .grid { display:grid; grid-template-columns: 1fr; gap: 16px; }
+    @media (min-width: 900px) { .grid { grid-template-columns: 1fr 1fr; } }
+    .card { background: rgba(17,24,39,0.9); border: 1px solid var(--border); border-radius: 10px; padding: 12px; }
+    .card-summary { cursor:pointer; display:flex; flex-wrap:wrap; gap: 10px; align-items:center; }
+    .page-title { font-weight: 600; }
+    .table { width:100%; border-collapse: collapse; }
+    .table th { text-align:left; width: 140px; color: var(--muted); font-weight: 500; padding: 6px 0; }
+    .table td { padding: 6px 0; }
+    .list { margin: 8px 0 0; padding-left: 18px; }
+    .sep { color: var(--muted); }
+    .stack { display:flex; flex-direction:column; gap: 12px; }
+    .badge { display:inline-block; border-radius: 999px; padding: 2px 8px; font-size: 12px; border: 1px solid var(--border); }
+    .badge-ok { background: rgba(16,185,129,0.15); border-color: rgba(16,185,129,0.25); }
+    .badge-warn { background: rgba(245,158,11,0.15); border-color: rgba(245,158,11,0.25); }
+    .badge-error { background: rgba(239,68,68,0.15); border-color: rgba(239,68,68,0.25); }
+    .badge-muted { background: rgba(156,163,175,0.12); border-color: rgba(156,163,175,0.25); }
+    .sev { display:inline-block; border-radius: 6px; padding: 2px 6px; font-size: 12px; text-transform: uppercase; letter-spacing: .03em; }
+    .sev-error { background: rgba(239,68,68,0.15); color: var(--text); border: 1px solid rgba(239,68,68,0.25); }
+    .sev-warning { background: rgba(245,158,11,0.15); color: var(--text); border: 1px solid rgba(245,158,11,0.25); }
+    .sev-info { background: rgba(96,165,250,0.15); color: var(--text); border: 1px solid rgba(96,165,250,0.25); }
+    details > summary { list-style: none; }
+    details > summary::-webkit-details-marker { display:none; }
+    .section { margin-top: 18px; }
+    pre { background: #0a0f1a; border: 1px solid var(--border); border-radius: 10px; padding: 12px; overflow:auto; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <h1>QA Report</h1>
+      <span class="muted">${escapeHtml(report.run.baseUrl)}</span>
+    </div>
+
+    <div class="section card">
+      <h3 style="margin-top:0">Run Summary</h3>
+      <div class="grid">
+        <div>
+          <table class="table">
+            <tr><th>Started</th><td><code>${escapeHtml(report.run.startedAt)}</code></td></tr>
+            <tr><th>Ended</th><td><code>${escapeHtml(report.run.endedAt)}</code></td></tr>
+            <tr><th>Duration</th><td>${duration ? `<code>${escapeHtml(duration)}</code>` : `<span class="muted">\u2014</span>`}</td></tr>
+            <tr><th>Pages</th><td><code>${escapeHtml(String(report.pages.length))}</code></td></tr>
+            <tr><th>Issues</th><td><code>${escapeHtml(String(issues.length))}</code> <span class="muted">(error ${bySeverity.error}, warning ${bySeverity.warning}, info ${bySeverity.info})</span></td></tr>
+          </table>
+        </div>
+        <div>
+          <div><strong>Caps reached</strong></div>
+          ${capsHtml}
+          ${report.run.warnings.length ? `<div style="margin-top:10px"><strong>Warnings</strong><ul class="list">${report.run.warnings.map((w) => `<li>${escapeHtml(w)}</li>`).join("")}</ul></div>` : `<div style="margin-top:10px" class="muted">No run warnings.</div>`}
+        </div>
+      </div>
+    </div>
+
+    <div class="section card">
+      <h3 style="margin-top:0">Issue Dashboard</h3>
+      ${issues.length ? `<ul class="list">${issueTypeList}</ul>` : `<div class="muted">No issues found.</div>`}
+    </div>
+
+    <div class="section">
+      <h2>Broken Links</h2>
+      ${brokenLinksHtml}
+    </div>
+
+    <div class="section">
+      <h2>Duplicates</h2>
+      ${duplicatesHtml}
+    </div>
+
+    <div class="section">
+      <h2>Pages</h2>
+      <div class="stack">
+        ${pagesHtml || `<div class="muted">No pages captured.</div>`}
+      </div>
+    </div>
+
+    <div class="section card">
+      <h3 style="margin-top:0">Config</h3>
+      <pre><code>${configJson}</code></pre>
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+// src/report/write-html.ts
+function writeHtmlReport(outputDir, report) {
+  mkdirSync2(outputDir, { recursive: true });
+  const path = join2(outputDir, "report.html");
+  const html = buildHtmlReport(report);
+  writeFileSync2(path, html, "utf8");
+  return path;
+}
+
+// src/report/create.ts
+function createEmptyReport(cfg, startedAt) {
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    run: {
+      startedAt,
+      endedAt: startedAt,
+      baseUrl: cfg.baseUrl,
+      config: {
+        mode: cfg.mode,
+        reportFormat: cfg.reportFormat,
+        outputDir: cfg.outputDir,
+        maxPages: cfg.maxPages,
+        maxDepth: cfg.maxDepth,
+        maxRedirects: cfg.maxRedirects,
+        concurrency: cfg.concurrency,
+        timeoutMs: cfg.timeoutMs,
+        sitemap: cfg.sitemap,
+        respectRobots: cfg.respectRobots,
+        externalLinks: cfg.externalLinks,
+        ignoreHttpsErrors: cfg.ignoreHttpsErrors,
+        render: {
+          maxRenderPages: cfg.render.maxRenderPages,
+          screenshotFullPage: cfg.render.screenshotFullPage,
+          breakpoints: cfg.render.breakpoints
+        },
+        crawl: {
+          perPathQueryVariantLimit: cfg.crawl.perPathQueryVariantLimit,
+          paginationParamNames: cfg.crawl.paginationParamNames,
+          paginationLimit: cfg.crawl.paginationLimit,
+          limitedPathPrefixes: cfg.crawl.limitedPathPrefixes,
+          requestDelayMs: cfg.crawl.requestDelayMs
+        },
+        external: {
+          maxExternalLinksChecked: cfg.external.maxExternalLinksChecked
+        },
+        include: cfg.include,
+        exclude: cfg.exclude,
+        userAgent: cfg.userAgent
+      },
+      warnings: [],
+      capsReached: {
+        maxPages: false,
+        maxDepth: false,
+        maxRedirects: false,
+        queryVariantLimit: false,
+        paginationLimit: false,
+        externalLinksLimit: false
+      }
+    },
+    pages: [],
+    issues: []
+  };
+}
+
+// src/render/select-pages.ts
+function isInternalToBase(baseUrl, candidateUrl) {
+  try {
+    const base = new URL(baseUrl);
+    const u = new URL(candidateUrl);
+    return u.origin === base.origin;
+  } catch {
+    return false;
+  }
+}
+function sortCandidates(candidates) {
+  return candidates.sort(
+    (a, b) => a.group - b.group || a.rank - b.rank || a.url.localeCompare(b.url)
+  );
+}
+async function selectRenderUrlsForFull(cfg, report) {
+  const candidates = [];
+  candidates.push({ url: cfg.baseUrl, group: 0, rank: 0 });
+  const issueUrls = /* @__PURE__ */ new Set();
+  for (const issue of report.issues ?? []) {
+    const u = issue.context?.url;
+    if (typeof u === "string" && isInternalToBase(cfg.baseUrl, u)) issueUrls.add(u);
+  }
+  for (const u of [...issueUrls].sort()) candidates.push({ url: u, group: 1, rank: 0 });
+  const topInbound = report.pages.filter((p) => p.status === 200).slice().sort((a, b) => b.discoveredFrom.length - a.discoveredFrom.length || a.finalUrl.localeCompare(b.finalUrl)).slice(0, 20).map((p) => p.finalUrl);
+  for (const [index, u] of topInbound.entries()) candidates.push({ url: u, group: 2, rank: index });
+  if (cfg.sitemap) {
+    const seedResult = await discoverSeeds(cfg);
+    for (const u of seedResult.seeds) {
+      if (!isInternalToBase(cfg.baseUrl, u)) continue;
+      candidates.push({ url: u, group: 3, rank: 0 });
+    }
+  }
+  const used = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const c of sortCandidates(candidates)) {
+    const normalized = normalizeUrl(c.url, cfg.url).normalizedUrl;
+    if (used.has(normalized)) continue;
+    used.add(normalized);
+    out.push(normalized);
+    if (out.length >= cfg.render.maxRenderPages) break;
+  }
+  return out;
+}
+async function selectRenderUrlsForRenderOnly(cfg) {
+  const seedResult = await discoverSeeds(cfg);
+  const candidates = seedResult.seeds.filter((u) => isInternalToBase(cfg.baseUrl, u)).map((u) => ({ url: u, group: 0, rank: 0 }));
+  const used = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const c of sortCandidates(candidates)) {
+    const normalized = normalizeUrl(c.url, cfg.url).normalizedUrl;
+    if (used.has(normalized)) continue;
+    used.add(normalized);
+    out.push(normalized);
+    if (out.length >= cfg.render.maxRenderPages) break;
+  }
+  return out;
+}
+
+// src/render/screenshot-path.ts
+import { createHash } from "crypto";
+import { mkdirSync as mkdirSync3 } from "fs";
+import { join as join3 } from "path";
+function slugifyPath(pathname) {
+  if (!pathname || pathname === "/") return "home";
+  return pathname.replace(/^\//, "").replace(/\/$/, "").split("/").filter(Boolean).join("-").replace(/[^a-zA-Z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase() || "page";
+}
+function shortHash(value) {
+  return createHash("sha1").update(value).digest("hex").slice(0, 10);
+}
+function getScreenshotRelativePath(input, used) {
+  const u = new URL(input.url);
+  const slug = slugifyPath(u.pathname);
+  const queryHash = u.search ? shortHash(u.search) : "";
+  const baseName = `${slug}${queryHash ? `__${queryHash}` : ""}__${input.breakpoint}.png`;
+  let rel = `screenshots/${input.breakpoint}/${baseName}`;
+  if (!used.has(rel)) {
+    used.add(rel);
+    return rel;
+  }
+  const disambiguator = shortHash(u.toString());
+  rel = `screenshots/${input.breakpoint}/${slug}__${disambiguator}__${input.breakpoint}.png`;
+  used.add(rel);
+  return rel;
+}
+function ensureScreenshotDir(outputDir, breakpoint) {
+  const dir = join3(outputDir, "screenshots", breakpoint);
+  mkdirSync3(dir, { recursive: true });
+  return dir;
+}
+
+// src/render/run.ts
+import { join as join4 } from "path";
+import { chromium } from "playwright";
+function getOrCreatePage(report, url) {
+  const existingIndex = report.pages.findIndex((p) => p.finalUrl === url || p.url === url);
+  if (existingIndex >= 0) return { pageIndex: existingIndex };
+  report.pages.push({
+    url,
+    finalUrl: url,
+    redirectChain: [],
+    depth: 0,
+    discoveredFrom: []
+  });
+  return { pageIndex: report.pages.length - 1 };
+}
+async function renderPages(cfg, report, urls) {
+  const usedScreenshots = /* @__PURE__ */ new Set();
+  const breakpointEntries = Object.entries(cfg.render.breakpoints).sort((a, b) => a[0].localeCompare(b[0]));
+  if (breakpointEntries.length === 0) return;
+  for (const [breakpointName] of breakpointEntries) {
+    ensureScreenshotDir(cfg.outputDir, breakpointName);
+  }
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const contexts = await Promise.all(
+      breakpointEntries.map(async ([name, viewport]) => {
+        const context = await browser.newContext({
+          viewport,
+          ignoreHTTPSErrors: cfg.ignoreHttpsErrors,
+          extraHTTPHeaders: cfg.headers,
+          ...cfg.userAgent ? { userAgent: cfg.userAgent } : {}
+        });
+        return { name, viewport, context };
+      })
+    );
+    try {
+      for (const url of urls) {
+        const { pageIndex } = getOrCreatePage(report, url);
+        const pageRecord = report.pages[pageIndex];
+        const renderResults = [];
+        for (const { name: breakpoint, viewport, context } of contexts) {
+          const consoleErrors = [];
+          const requestFailures = [];
+          let pageError;
+          let pageStatus;
+          const page = await context.newPage();
+          page.on("console", (msg) => {
+            if (msg.type() !== "error") return;
+            const loc = msg.location();
+            const location = {
+              ...loc.url ? { url: loc.url } : {},
+              ...loc.lineNumber ? { lineNumber: loc.lineNumber } : {},
+              ...loc.columnNumber ? { columnNumber: loc.columnNumber } : {}
+            };
+            consoleErrors.push({
+              type: msg.type(),
+              text: msg.text(),
+              location: Object.keys(location).length ? location : void 0
+            });
+          });
+          page.on("pageerror", (err) => {
+            pageError = err instanceof Error ? err.message : String(err);
+          });
+          page.on("requestfailed", (req) => {
+            const failure = req.failure();
+            requestFailures.push({
+              url: req.url(),
+              method: req.method(),
+              resourceType: req.resourceType(),
+              failure: failure?.errorText ?? void 0
+            });
+          });
+          try {
+            const response = await page.goto(url, { waitUntil: "load", timeout: cfg.timeoutMs });
+            pageStatus = response?.status();
+          } catch (error) {
+            pageError = pageError ?? (error instanceof Error ? error.message : String(error));
+          }
+          const rel = getScreenshotRelativePath(
+            { outputDir: cfg.outputDir, url, breakpoint },
+            usedScreenshots
+          );
+          const abs = join4(cfg.outputDir, rel);
+          const dir = join4(cfg.outputDir, "screenshots", breakpoint);
+          try {
+            await page.screenshot({
+              path: abs,
+              fullPage: cfg.render.screenshotFullPage
+            });
+          } catch (error) {
+            pageError = pageError ?? (error instanceof Error ? error.message : String(error));
+          } finally {
+            await page.close();
+          }
+          ensureScreenshotDir(cfg.outputDir, breakpoint);
+          void dir;
+          renderResults.push({
+            breakpoint,
+            viewport,
+            fullPage: cfg.render.screenshotFullPage,
+            screenshotPath: rel,
+            pageStatus,
+            pageError,
+            consoleErrors,
+            requestFailures
+          });
+        }
+        pageRecord.render = { results: renderResults };
+      }
+    } finally {
+      await Promise.all(contexts.map((c) => c.context.close()));
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+// src/checks/generate-render-issues.ts
+function push2(issues, issue) {
+  issues.push(issue);
+}
+function generateRenderIssues(report) {
+  const issues = [];
+  for (const page of report.pages) {
+    const render = page.render;
+    if (!render) continue;
+    for (const r of render.results) {
+      const baseContext = {
+        url: page.finalUrl,
+        breakpoint: r.breakpoint,
+        screenshotPath: r.screenshotPath
+      };
+      if (typeof r.pageStatus === "number" && r.pageStatus >= 400) {
+        push2(issues, {
+          severity: "error",
+          type: "render_http_error",
+          message: `Rendered page returned HTTP ${r.pageStatus}`,
+          context: { ...baseContext, status: r.pageStatus }
+        });
+      }
+      if (r.pageError) {
+        push2(issues, {
+          severity: "error",
+          type: "render_page_error",
+          message: "Page error while rendering",
+          context: { ...baseContext, error: r.pageError }
+        });
+      }
+      if (r.consoleErrors.length > 0) {
+        push2(issues, {
+          severity: "error",
+          type: "render_console_error",
+          message: `${r.consoleErrors.length} console error(s) while rendering`,
+          context: { ...baseContext, count: r.consoleErrors.length, sample: r.consoleErrors.slice(0, 10) }
+        });
+      }
+      if (r.requestFailures.length > 0) {
+        push2(issues, {
+          severity: "warning",
+          type: "render_request_failed",
+          message: `${r.requestFailures.length} failed request(s) while rendering`,
+          context: { ...baseContext, count: r.requestFailures.length, sample: r.requestFailures.slice(0, 10) }
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+// src/output/run-dir.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdirSync as mkdirSync4 } from "fs";
+import { join as join5 } from "path";
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function shortHash2(value) {
+  return createHash2("sha1").update(value).digest("hex").slice(0, 10);
+}
+function formatTimestampForDir(iso) {
+  return iso.replace(/\.\d{3}Z$/, "Z").replace(/:/g, "-");
+}
+function slugifyUrlForDir(baseUrl) {
+  const u = new URL(baseUrl);
+  const host = u.host;
+  const path = u.pathname && u.pathname !== "/" ? u.pathname : "";
+  const raw = `${host}${path}`;
+  const slug = slugify(raw);
+  if (slug.length <= 80) return slug || "site";
+  return `${slug.slice(0, 60)}-${shortHash2(raw)}`;
+}
+function createRunOutputDir(outputRootDir, baseUrl, startedAtIso) {
+  mkdirSync4(outputRootDir, { recursive: true });
+  const dirName = `${formatTimestampForDir(startedAtIso)}__${slugifyUrlForDir(baseUrl)}`;
+  const outDir = join5(outputRootDir, dirName);
+  mkdirSync4(outDir, { recursive: true });
+  return outDir;
+}
+
+// src/report/write-run-metadata.ts
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
+import { join as join6, relative } from "path";
+
+// src/version.ts
+import { readFileSync as readFileSync2 } from "fs";
+function getToolVersion() {
+  try {
+    const raw = readFileSync2(new URL("../package.json", import.meta.url), "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// src/report/write-run-metadata.ts
+function writeRunMetadata(outputDir, report, absoluteFilesWritten) {
+  mkdirSync5(outputDir, { recursive: true });
+  const path = join6(outputDir, "run-metadata.json");
+  const files = absoluteFilesWritten.map((p) => relative(outputDir, p)).filter((p) => !p.startsWith("..")).sort();
+  const metadata = {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    toolVersion: getToolVersion(),
+    outputDir,
+    startedAt: report.run.startedAt,
+    endedAt: report.run.endedAt,
+    baseUrl: report.run.baseUrl,
+    files
+  };
+  writeFileSync3(path, `${JSON.stringify(metadata, null, 2)}
+`, "utf8");
+  return path;
+}
+
+// src/config/validate.ts
+function validateRegexList(patterns, label) {
+  for (const pattern of patterns) {
+    try {
+      new RegExp(pattern);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Invalid ${label} regex: ${pattern} (${msg})`);
+    }
+  }
+}
+
+// src/checks/check-external-links.ts
+function isExternalToBase(cfg, url) {
+  try {
+    const base = new URL(cfg.baseUrl);
+    const u = new URL(url);
+    return u.origin !== base.origin;
+  } catch {
+    return false;
+  }
+}
+function addReferrer2(map, targetUrl, ref) {
+  const entry = map.get(targetUrl) ?? { url: targetUrl, referrers: [] };
+  if (!entry.referrers.some((r) => r.pageUrl === ref.pageUrl && r.url === ref.url && r.anchorText === ref.anchorText)) {
+    entry.referrers.push(ref);
+  }
+  map.set(targetUrl, entry);
+}
+async function runWithConcurrency2(concurrency, tasks) {
+  const results = new Array(tasks.length);
+  let index = 0;
+  async function worker() {
+    while (true) {
+      const current = index;
+      index += 1;
+      if (current >= tasks.length) return;
+      const task = tasks[current];
+      if (!task) return;
+      results[current] = await task();
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+  return results;
+}
+async function checkExternalLinks(cfg, report) {
+  if (!cfg.externalLinks) return [];
+  if (cfg.external.maxExternalLinksChecked <= 0) return [];
+  const urlCfg = { ...cfg.url, dropQueryParamsExceptAllowlist: false };
+  const targets = /* @__PURE__ */ new Map();
+  for (const page of report.pages) {
+    const outbound = page.outboundLinks ?? [];
+    for (const link of outbound) {
+      if (link.internal) continue;
+      const resolved = link.resolvedUrl;
+      if (!isExternalToBase(cfg, resolved)) continue;
+      const normalized = normalizeUrl(resolved, urlCfg).normalizedUrl;
+      addReferrer2(targets, normalized, {
+        pageUrl: page.finalUrl,
+        url: page.finalUrl,
+        anchorText: link.anchorText
+      });
+    }
+  }
+  const unique = [...targets.values()].sort((a, b) => a.url.localeCompare(b.url));
+  const limited = unique.slice(0, cfg.external.maxExternalLinksChecked);
+  if (unique.length > limited.length) {
+    report.run.capsReached.externalLinksLimit = true;
+    report.run.warnings.push(
+      `External link cap reached (maxExternalLinksChecked=${cfg.external.maxExternalLinksChecked}); checked ${limited.length} of ${unique.length}`
+    );
+  }
+  const hostDelay = new HostDelayLimiter(cfg.crawl.requestDelayMs);
+  const tasks = limited.map((t) => async () => {
+    await hostDelay.waitFor(t.url);
+    const res = await fetchWithRedirects(t.url, {
+      timeoutMs: cfg.timeoutMs,
+      maxRedirects: cfg.maxRedirects,
+      headers: cfg.headers,
+      userAgent: cfg.userAgent,
+      ignoreHttpsErrors: cfg.ignoreHttpsErrors
+    });
+    if (res.error) {
+      const issue = {
+        severity: "warning",
+        type: "external_link_fetch_error",
+        message: "Failed to fetch external link",
+        context: {
+          url: t.url,
+          error: res.error,
+          referrers: t.referrers.map((r) => ({ url: r.pageUrl, anchorText: r.anchorText }))
+        }
+      };
+      return issue;
+    }
+    const status = res.status ?? 0;
+    if (status >= 400) {
+      const issue = {
+        severity: "warning",
+        type: "external_link_http_error",
+        message: `HTTP ${status}`,
+        context: {
+          url: t.url,
+          status,
+          referrers: t.referrers.map((r) => ({ url: r.pageUrl, anchorText: r.anchorText }))
+        }
+      };
+      return issue;
+    }
+    return null;
+  });
+  const results = await runWithConcurrency2(cfg.concurrency, tasks);
+  return results.filter((i) => i !== null);
+}
+
+// src/cli/qa-command.ts
+function parseBoolean(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return void 0;
+  const lower = value.toLowerCase().trim();
+  if (lower === "true" || lower === "1" || lower === "yes") return true;
+  if (lower === "false" || lower === "0" || lower === "no") return false;
+  return void 0;
+}
+function parseJsonObject(value) {
+  if (!value) return {};
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--headers must be a JSON object");
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(parsed)) {
+    if (typeof v !== "string") continue;
+    out[k] = v;
+  }
+  return out;
+}
+function failWithHelp(program, io, exitCode2, message) {
+  io.stderr.write(`${message}
+`);
+  program.outputHelp();
+  throw new CommanderError(exitCode2, "qa.usage", message);
+}
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return void 0;
+}
+function resolveMode(value) {
+  if (value === "crawl" || value === "render" || value === "full") return value;
+  return void 0;
+}
+function resolveReportFormat(value) {
+  if (value === "html" || value === "json" || value === "both") return value;
+  return void 0;
+}
+function resolveFailOn(value) {
+  if (value === "none" || value === "info" || value === "warning" || value === "error") return value;
+  return void 0;
+}
+function computeFailExitCode(failOn, issuesCount) {
+  if (failOn === "none") return 0;
+  if (failOn === "error") return issuesCount.error > 0 ? 2 : 0;
+  if (failOn === "warning") return issuesCount.error + issuesCount.warning > 0 ? 2 : 0;
+  return issuesCount.error + issuesCount.warning + issuesCount.info > 0 ? 2 : 0;
+}
+function countIssuesBySeverity(issues) {
+  let error = 0;
+  let warning = 0;
+  let info = 0;
+  for (const i of issues) {
+    if (i.severity === "error") error += 1;
+    else if (i.severity === "warning") warning += 1;
+    else if (i.severity === "info") info += 1;
+  }
+  return { error, warning, info };
+}
+function validateUrlOrFail(program, io, url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    failWithHelp(program, io, 1, `Invalid URL: ${url}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    failWithHelp(program, io, 1, `URL must be http(s): ${url}`);
+  }
+}
+async function runQaCommand(program, io, url, options) {
+  if (!url) {
+    failWithHelp(program, io, 1, "Missing required argument: url");
+  }
+  validateUrlOrFail(program, io, url);
+  const defaults = defaultConfigForBaseUrl(url);
+  const startedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+  let fileConfig = {};
+  if (options.config) {
+    try {
+      fileConfig = loadConfigFile(options.config);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      failWithHelp(program, io, 1, `Failed to load config: ${msg}`);
+    }
+  }
+  const cliHeadersFromJson = (() => {
+    try {
+      return parseJsonObject(options.headers);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      failWithHelp(program, io, 1, msg);
+    }
+  })();
+  const cliHeadersFromPairs = parseHeaderPairs(options.header);
+  const merged = mergeConfig(defaults, fileConfig);
+  const outputRootDir = options.output ?? merged.outputDir;
+  const parsedMode = resolveMode(options.mode);
+  if (options.mode !== void 0 && !parsedMode) {
+    failWithHelp(program, io, 1, `Invalid --mode: ${String(options.mode)} (expected crawl|render|full)`);
+  }
+  const parsedReportFormat = resolveReportFormat(options.reportFormat);
+  if (options.reportFormat !== void 0 && !parsedReportFormat) {
+    failWithHelp(
+      program,
+      io,
+      1,
+      `Invalid --report-format: ${String(options.reportFormat)} (expected html|json|both)`
+    );
+  }
+  const parsedFailOn = resolveFailOn(options.failOn);
+  if (options.failOn !== void 0 && !parsedFailOn) {
+    failWithHelp(program, io, 1, `Invalid --fail-on: ${String(options.failOn)} (expected none|info|warning|error)`);
+  }
+  const cfg = mergeConfig(merged, {
+    outputDir: createRunOutputDir(outputRootDir, url, startedAtIso),
+    mode: parsedMode ?? merged.mode,
+    reportFormat: parsedReportFormat ?? merged.reportFormat,
+    maxPages: toNumber(options.maxPages) ?? merged.maxPages,
+    maxDepth: toNumber(options.maxDepth) ?? merged.maxDepth,
+    render: {
+      maxRenderPages: toNumber(options.maxRenderPages) ?? merged.render.maxRenderPages
+    },
+    maxRedirects: toNumber(options.maxRedirects) ?? merged.maxRedirects,
+    concurrency: toNumber(options.concurrency) ?? merged.concurrency,
+    timeoutMs: toNumber(options.timeout) ?? merged.timeoutMs,
+    respectRobots: parseBoolean(options.respectRobots) ?? merged.respectRobots,
+    sitemap: parseBoolean(options.sitemap) ?? merged.sitemap,
+    externalLinks: parseBoolean(options.externalLinks) ?? merged.externalLinks,
+    external: {
+      maxExternalLinksChecked: toNumber(options.maxExternalLinks) ?? merged.external.maxExternalLinksChecked
+    },
+    ignoreHttpsErrors: parseBoolean(options.ignoreHttpsErrors) ?? merged.ignoreHttpsErrors,
+    userAgent: options.userAgent ?? merged.userAgent,
+    headers: {
+      ...merged.headers,
+      ...cliHeadersFromJson,
+      ...cliHeadersFromPairs
+    },
+    include: options.include ?? merged.include,
+    exclude: options.exclude ?? merged.exclude
+  });
+  if (cfg.maxPages <= 0) failWithHelp(program, io, 1, "--max-pages must be > 0");
+  if (cfg.maxDepth < 0) failWithHelp(program, io, 1, "--max-depth must be >= 0");
+  if (cfg.render.maxRenderPages <= 0) failWithHelp(program, io, 1, "--max-render-pages must be > 0");
+  if (cfg.maxRedirects < 0) failWithHelp(program, io, 1, "--max-redirects must be >= 0");
+  if (cfg.concurrency <= 0) failWithHelp(program, io, 1, "--concurrency must be > 0");
+  if (cfg.timeoutMs <= 0) failWithHelp(program, io, 1, "--timeout must be > 0");
+  if (cfg.crawl.perPathQueryVariantLimit <= 0) failWithHelp(program, io, 1, "crawl.perPathQueryVariantLimit must be > 0");
+  if (cfg.crawl.paginationLimit <= 0) failWithHelp(program, io, 1, "crawl.paginationLimit must be > 0");
+  if (cfg.crawl.requestDelayMs < 0) failWithHelp(program, io, 1, "crawl.requestDelayMs must be >= 0");
+  if (cfg.external.maxExternalLinksChecked < 0) failWithHelp(program, io, 1, "external.maxExternalLinksChecked must be >= 0");
+  try {
+    validateRegexList(cfg.include, "--include");
+    validateRegexList(cfg.exclude, "--exclude");
+    validateRegexList(cfg.url.ignoredQueryParamPatterns, "url.ignoredQueryParamPatterns");
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    failWithHelp(program, io, 1, msg);
+  }
+  cfg.url.allowlistedQueryParams = cfg.url.allowlistedQueryParams.map((s) => s.toLowerCase());
+  cfg.url.trackingParamNames = cfg.url.trackingParamNames.map((s) => s.toLowerCase());
+  cfg.url.trackingParamPrefixes = cfg.url.trackingParamPrefixes.map((s) => s.toLowerCase());
+  cfg.crawl.paginationParamNames = cfg.crawl.paginationParamNames.map((s) => s.toLowerCase());
+  const preWarnings = [];
+  if (cfg.externalLinks) {
+    if (cfg.external.maxExternalLinksChecked <= 0) {
+      preWarnings.push(
+        "External link checking is enabled but maxExternalLinksChecked=0; no external links will be checked."
+      );
+    }
+  }
+  let report = createEmptyReport(cfg, startedAtIso);
+  if (cfg.mode === "crawl") {
+    const crawled = await crawlSite(cfg);
+    report = crawled.report;
+    report.run.warnings.unshift(...preWarnings);
+    report.issues = generateIssues(cfg, report);
+    report.issues = [...report.issues ?? [], ...await checkExternalLinks(cfg, report)];
+  } else if (cfg.mode === "full") {
+    const crawled = await crawlSite(cfg);
+    report = crawled.report;
+    report.run.warnings.unshift(...preWarnings);
+    report.issues = generateIssues(cfg, report);
+    report.issues = [...report.issues ?? [], ...await checkExternalLinks(cfg, report)];
+    const renderUrls = await selectRenderUrlsForFull(cfg, report);
+    await renderPages(cfg, report, renderUrls);
+    report.issues = [...report.issues ?? [], ...generateRenderIssues(report)];
+    report.run.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  } else if (cfg.mode === "render") {
+    report.run.warnings.unshift(...preWarnings);
+    const renderUrls = await selectRenderUrlsForRenderOnly(cfg);
+    await renderPages(cfg, report, renderUrls);
+    report.issues = [...report.issues ?? [], ...generateRenderIssues(report)];
+    report.run.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  const outputs = [];
+  if (cfg.reportFormat === "json" || cfg.reportFormat === "both") {
+    outputs.push(writeJsonReport(cfg.outputDir, report));
+  }
+  if (cfg.reportFormat === "html" || cfg.reportFormat === "both") {
+    outputs.push(writeHtmlReport(cfg.outputDir, report));
+  }
+  outputs.push(writeRunMetadata(cfg.outputDir, report, outputs));
+  for (const out of outputs) io.stdout.write(`Wrote ${out}
+`);
+  const effectiveFailOn = (options.ci ? "error" : void 0) ?? parsedFailOn ?? "none";
+  const counts = countIssuesBySeverity(report.issues ?? []);
+  const exitCode2 = computeFailExitCode(effectiveFailOn, counts);
+  if (exitCode2 !== 0) {
+    io.stderr.write(
+      `qa: failing due to issues (error=${counts.error}, warning=${counts.warning}, info=${counts.info}); output: ${cfg.outputDir}
+`
+    );
+    throw new CommanderError(exitCode2, "qa.failOn", "Issues found");
+  }
+}
+
+// src/cli/program.ts
+function readPackageVersion() {
+  try {
+    const raw = readFileSync3(new URL("../../package.json", import.meta.url), "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function createProgram(io) {
+  const program = new Command();
+  program.name("qa").description("Website QA CLI").version(readPackageVersion()).showHelpAfterError().configureOutput({
+    writeOut: (str) => {
+      io.stdout.write(str);
+    },
+    writeErr: (str) => {
+      io.stderr.write(str);
+    }
+  });
+  program.argument("[url]", "Base URL (e.g. https://example.com)").option("--config <path>", "Path to YAML/JSON config file").option("--output <dir>", "Output root directory", "qa-output").option("--mode <mode>", "crawl|render|full", "crawl").option("--ci", "CI mode (non-zero exit when issues found)").option("--fail-on <severity>", "none|info|warning|error", "none").option("--max-pages <n>", "Hard cap on total pages", (v) => Number(v)).option("--max-depth <n>", "Hard cap on link depth", (v) => Number(v)).option("--max-render-pages <n>", "Hard cap on rendered pages (Phase 4)", (v) => Number(v)).option("--concurrency <n>", "Concurrent requests", (v) => Number(v)).option("--timeout <ms>", "Request timeout in milliseconds", (v) => Number(v)).option("--respect-robots <boolean>", "Respect robots.txt (v1)").option("--sitemap <boolean>", "Seed from /sitemap.xml").option("--external-links <boolean>", "Check external links (v1)").option("--max-external-links <n>", "Hard cap on external links checked (v1)", (v) => Number(v)).option("--ignore-https-errors <boolean>", "Ignore HTTPS certificate errors").option("--user-agent <string>", "Custom user-agent").option("--headers <json>", `Headers JSON object (e.g. '{"K":"V"}')`).option(
+    "--header <pair>",
+    "Header pair (repeatable) (e.g. 'Authorization: Bearer ...')",
+    (value, previous) => {
+      const next = previous ?? [];
+      next.push(value);
+      return next;
+    }
+  ).option(
+    "--include <pattern>",
+    "Include path regex (repeatable)",
+    (value, previous) => {
+      const next = previous ?? [];
+      next.push(value);
+      return next;
+    }
+  ).option(
+    "--exclude <pattern>",
+    "Exclude path regex (repeatable)",
+    (value, previous) => {
+      const next = previous ?? [];
+      next.push(value);
+      return next;
+    }
+  ).option("--report-format <format>", "html|json|both", "both").action(async (url, options) => {
+    await runQaCommand(program, io, url, options);
+  });
+  program.command("hello").description("Smoke-test command").argument("[name]", "Name to greet", "world").action((name) => {
+    io.stdout.write(`Hello, ${name}!
+`);
+  });
+  return program;
+}
+
+// src/cli/run.ts
+async function runCli(argv, io) {
+  const program = createProgram(io);
+  program.exitOverride();
+  try {
+    await program.parseAsync(argv);
+    return 0;
+  } catch (error) {
+    if (error instanceof CommanderError2) {
+      if (error.code === "commander.helpDisplayed") return 0;
+      return typeof error.exitCode === "number" ? error.exitCode : 1;
+    }
+    throw error;
+  }
+}
+
+// src/cli.ts
+var exitCode = await runCli(process.argv, {
+  stdout: process.stdout,
+  stderr: process.stderr
+});
+process.exitCode = exitCode;
+//# sourceMappingURL=cli.js.map