@goflag/cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+import {
+  Logger,
+  exitCode,
+  renderSummaryTerminal,
+  renderTerminal,
+  runAudit,
+  summarize
+} from "./chunk-75OFMTOC.js";
+
+// src/report/diff.ts
+function collectFindings(report) {
+  const out = [];
+  for (const link of report.brokenLinks) {
+    out.push({
+      id: link.id,
+      kind: "brokenLink",
+      severity: "error",
+      summary: `${link.verdict} link \u2192 ${link.href}`,
+      pageUrl: link.pageUrl
+    });
+  }
+  for (const page of report.unreachablePages) {
+    out.push({
+      id: page.id,
+      kind: "unreachablePage",
+      severity: "error",
+      summary: `${page.status || "network error"} on ${page.url}`,
+      pageUrl: page.url
+    });
+  }
+  for (const hole of report.missingTranslations.holes) {
+    out.push({
+      id: hole.id,
+      kind: "translationHole",
+      severity: "warning",
+      summary: `${hole.route} missing ${hole.missingLocales.join(", ")}`
+    });
+  }
+  for (const issue of report.missingTranslations.reciprocity) {
+    out.push({
+      id: issue.id,
+      kind: "reciprocity",
+      severity: "warning",
+      summary: `${issue.code} on ${issue.url}`,
+      pageUrl: issue.url
+    });
+  }
+  for (const issue of report.seoIssues) {
+    out.push({
+      id: issue.id,
+      kind: "seo",
+      severity: issue.severity,
+      summary: `${issue.ruleId} on ${issue.pageUrl}`,
+      pageUrl: issue.pageUrl
+    });
+  }
+  for (const issue of report.siteIssues) {
+    out.push({
+      id: issue.id,
+      kind: "site",
+      severity: issue.severity,
+      summary: `${issue.ruleId} on ${issue.pageUrl}`,
+      pageUrl: issue.pageUrl
+    });
+  }
+  return out;
+}
+var SEVERITY_RANK = { error: 0, warning: 1, info: 2 };
+function sortEntries(entries) {
+  return [...entries].sort(
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.kind.localeCompare(b.kind) || a.summary.localeCompare(b.summary)
+  );
+}
+function totalFindings(report) {
+  return collectFindings(report).length;
+}
+function diffReports(baseline, current) {
+  const before = new Map(collectFindings(baseline).map((e) => [e.id, e]));
+  const now = new Map(collectFindings(current).map((e) => [e.id, e]));
+  const added = [];
+  let unchanged = 0;
+  for (const [id, entry] of now) {
+    if (before.has(id)) unchanged += 1;
+    else added.push(entry);
+  }
+  const resolved = [];
+  for (const [id, entry] of before) {
+    if (!now.has(id)) resolved.push(entry);
+  }
+  return {
+    baseline: { url: baseline.url, finishedAt: baseline.finishedAt },
+    added: sortEntries(added),
+    resolved: sortEntries(resolved),
+    unchanged
+  };
+}
+function diffExitCode(diff, failOn, debt) {
+  if (debt?.max !== void 0 && debt.total > debt.max) return 1;
+  if (failOn === "never") return 0;
+  const threshold = failOn === "error" ? 0 : 1;
+  const blocking = diff.added.filter((e) => SEVERITY_RANK[e.severity] <= threshold);
+  return blocking.length > 0 ? 1 : 0;
+}
+
+// src/report/render-diff.ts
+var ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m"
+};
+function paint(enabled) {
+  return (code, text) => enabled ? `${code}${text}${ANSI.reset}` : text;
+}
+function severityTag(c, severity) {
+  if (severity === "error") return c(ANSI.red, "error");
+  if (severity === "warning") return c(ANSI.yellow, "warn ");
+  return c(ANSI.dim, "info ");
+}
+var LIST_LIMIT = 20;
+function listEntries(entries, marker, markerColor, c) {
+  const lines = [];
+  for (const entry of entries.slice(0, LIST_LIMIT)) {
+    const where = entry.pageUrl && !entry.summary.includes(entry.pageUrl) ? c(ANSI.dim, `  on ${entry.pageUrl}`) : "";
+    lines.push(
+      `  ${c(markerColor, marker)} ${severityTag(c, entry.severity)} ${c(ANSI.dim, entry.kind)}  ${entry.summary}${where}`
+    );
+  }
+  if (entries.length > LIST_LIMIT) {
+    lines.push(`  ${c(ANSI.dim, `\u2026 +${entries.length - LIST_LIMIT} more`)}`);
+  }
+  return lines;
+}
+function baselineAgeDays(finishedAt, now) {
+  const taken = Date.parse(finishedAt);
+  if (Number.isNaN(taken)) return null;
+  return Math.max(0, Math.floor((now - taken) / 864e5));
+}
+function renderDiffTerminal(diff, options = {}) {
+  const c = paint(options.color ?? false);
+  const lines = [];
+  const debt = diff.unchanged;
+  const verdict = diff.added.length > 0 ? c(ANSI.red, "REGRESSION") : debt > 0 ? c(ANSI.yellow, "REGRESSION GATE") : c(ANSI.green, "CLEAN");
+  const age = baselineAgeDays(diff.baseline.finishedAt, options.now ?? Date.now());
+  lines.push("");
+  lines.push(`${c(ANSI.bold, "goflag")} ${c(ANSI.dim, "--regressions-only")}`);
+  lines.push(
+    `${verdict}  ${diff.added.length} new \xB7 ` + (debt > 0 ? c(ANSI.bold, `${debt} known findings NOT gating this build`) : c(ANSI.dim, "no known findings")) + (diff.resolved.length > 0 ? c(ANSI.dim, ` \xB7 ${diff.resolved.length} resolved`) : "")
+  );
+  lines.push(
+    c(
+      ANSI.dim,
+      `baseline ${diff.baseline.url} \u2014 taken ${diff.baseline.finishedAt}` + (age === null ? "" : age === 0 ? " (today)" : ` (${age} day${age === 1 ? "" : "s"} ago)`)
+    )
+  );
+  lines.push("");
+  if (diff.added.length > 0) {
+    lines.push(c(ANSI.bold, "New findings"));
+    lines.push(...listEntries(diff.added, "+", ANSI.red, c));
+    lines.push("");
+  }
+  if (diff.resolved.length > 0) {
+    lines.push(c(ANSI.bold, "Resolved"));
+    lines.push(...listEntries(diff.resolved, "-", ANSI.green, c));
+    lines.push("");
+  }
+  if (diff.added.length === 0 && diff.resolved.length === 0) {
+    lines.push(
+      c(
+        ANSI.dim,
+        debt > 0 ? `Nothing moved since the baseline \u2014 ${debt} findings still open. Run without --regressions-only to see them.` : "Nothing moved since the baseline."
+      )
+    );
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/lib/runner/dev-server.ts
+import { spawn } from "child_process";
+async function answers(url, allowInsecureTls) {
+  const previous = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+  if (allowInsecureTls) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+  try {
+    await fetch(url, { redirect: "manual" });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (allowInsecureTls) {
+      if (previous === void 0) delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+      else process.env.NODE_TLS_REJECT_UNAUTHORIZED = previous;
+    }
+  }
+}
+function terminate(child) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve();
+      return;
+    }
+    const killGroup = (signal) => {
+      try {
+        if (child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch {
+      }
+    };
+    const force = setTimeout(() => killGroup("SIGKILL"), 5e3);
+    child.once("exit", () => {
+      clearTimeout(force);
+      resolve();
+    });
+    killGroup("SIGTERM");
+  });
+}
+async function startServer(options) {
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  const intervalMs = options.intervalMs ?? 250;
+  const allowInsecureTls = options.allowInsecureTls === true;
+  const cwd = options.cwd ?? process.cwd();
+  const child = spawn(options.command, {
+    cwd,
+    shell: true,
+    // Own process group, so `terminate` can take the whole tree down.
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let exited;
+  child.once("exit", (code, signal) => {
+    exited = { code, signal };
+  });
+  const tail = [];
+  const record = (chunk) => {
+    const text = chunk.toString();
+    options.onOutput?.(text);
+    tail.push(text);
+    if (tail.length > 40) tail.shift();
+  };
+  child.stdout?.on("data", record);
+  child.stderr?.on("data", record);
+  const server = { stop: () => terminate(child) };
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (exited) {
+      await server.stop();
+      const why = exited.signal ? `signal ${exited.signal}` : `exit code ${exited.code}`;
+      throw new Error(
+        `--start command exited before ${options.url} answered (${why}).
+  command: ${options.command}
+  in:      ${cwd}
+${tail.join("").trimEnd()}`
+      );
+    }
+    if (await answers(options.url, allowInsecureTls)) return server;
+    if (Date.now() >= deadline) {
+      await server.stop();
+      throw new Error(
+        `--start command did not serve ${options.url} within ${timeoutMs}ms.
+  command: ${options.command}
+  in:      ${cwd}
+Raise --start-timeout, check the command listens on that URL, or point --start-cwd at the directory it should run in.`
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// src/cli-args.ts
+var HELP = `goflag \u2014 audit a site for broken links, missing translations, and SEO metadata
+
+Usage:
+  goflag <url> [options]
+
+Options:
+  --json                 Print the JSON report to stdout (nothing else).
+  --summary, -s          Roll findings up (dedup by link/rule/code). Pairs
+                         with --json for a compact, agent-friendly payload.
+  --report <file>        Write the (full) JSON report to <file>.
+  --depth <n>            Crawl depth (0 = entry page only). Default: 2.
+  --max-pages <n>        Hard cap on pages crawled. Default: 200.
+  --include <glob>       Only crawl paths matching <glob> (repeatable).
+  --exclude <glob>       Skip paths matching <glob> (repeatable).
+  --locales <list>       Comma-separated locales the site serves, e.g.
+                         "fr,en,pt-br". Authoritative: overrides what the
+                         sitemap and crawl suggest, and makes a locale the
+                         site does not serve yet show up as missing.
+  --ignore-holes <glob>  Route (locale-free) that is deliberately not
+                         translated everywhere, so its gaps are not reported
+                         as missing translations (repeatable).
+  --no-sitemap           Do not discover the sitemap; crawl from <url> only.
+                         Discovery is on by default because link-only crawling
+                         cannot find locales a site never links to.
+  --fail-on <level>      Exit 1 at or above this severity: warning (default),
+                         error, or never.
+  --regressions-only     Weaken the gate: fail only on findings that are NEW
+                         relative to --baseline. Known findings stop blocking
+                         the build \u2014 a green run no longer means a clean site.
+                         Requires --baseline.
+  --baseline <file>      Stored report to compare against. Use with
+                         --regressions-only.
+  --max-debt <n>         Fail when the site carries more than <n> findings in
+                         total, whether new or known. Lower it as you fix, to
+                         stop a baseline from fossilising.
+  --start <cmd>          Boot <cmd>, wait for <url> to answer, audit, then
+                         stop it. Use to gate a merge on the built app before
+                         it ships.
+  --start-cwd <dir>      Directory to run --start in. Defaults to the current
+                         one; set it when auditing a monorepo package from the
+                         repository root.
+  --start-timeout <ms>   How long to wait for --start to answer. Default: 60000.
+  --no-external          Do not probe off-origin (external) links.
+  --static               Static HTML only; never launch headless Chromium.
+  --allow-insecure-tls   Accept self-signed / invalid TLS (localhost, tunnels).
+  --timeout <ms>         Per-request timeout in ms. Default: 8000.
+  --verbose, -V          Log every page as it is analyzed.
+  --quiet, -q            Suppress the live progress output.
+  --no-color             Disable coloured output.
+  -h, --help             Show this help.
+  -v, --version          Show the version.
+
+Exit codes: 0 clean, 1 findings found, 2 fatal error.`;
+var FAIL_ON_LEVELS = ["warning", "error", "never"];
+function parseArgs(argv) {
+  const parsed = {
+    json: false,
+    summary: false,
+    color: process.stdout.isTTY === true && !process.env.NO_COLOR,
+    help: false,
+    version: false,
+    logMode: "compact",
+    failOn: "warning",
+    regressionsOnly: false,
+    startTimeoutMs: 6e4,
+    options: { include: [], exclude: [] }
+  };
+  const next = (i, flag) => {
+    const value = argv[i + 1];
+    if (value === void 0) throw new Error(`${flag} requires a value`);
+    return value;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "-h":
+      case "--help":
+        parsed.help = true;
+        break;
+      case "-v":
+      case "--version":
+        parsed.version = true;
+        break;
+      case "--json":
+        parsed.json = true;
+        break;
+      case "-s":
+      case "--summary":
+        parsed.summary = true;
+        break;
+      case "--no-color":
+        parsed.color = false;
+        break;
+      case "-V":
+      case "--verbose":
+        parsed.logMode = "verbose";
+        break;
+      case "-q":
+      case "--quiet":
+        parsed.logMode = "quiet";
+        break;
+      case "--static":
+        parsed.options.static = true;
+        break;
+      case "--allow-insecure-tls":
+        parsed.options.allowInsecureTls = true;
+        break;
+      case "--no-external":
+        parsed.options.checkExternal = false;
+        break;
+      case "--no-sitemap":
+        parsed.options.noSitemap = true;
+        break;
+      case "--ignore-holes":
+        parsed.options.ignoreHoles = [...parsed.options.ignoreHoles ?? [], next(i, arg)];
+        i++;
+        break;
+      case "--locales": {
+        const value = next(i, arg);
+        const tags = value.split(",").map((t) => t.trim()).filter(Boolean);
+        if (tags.length === 0) throw new Error(`${arg} expects at least one locale`);
+        parsed.options.locales = [...parsed.options.locales ?? [], ...tags];
+        i++;
+        break;
+      }
+      case "--fail-on": {
+        const value = next(i, arg);
+        if (!FAIL_ON_LEVELS.includes(value)) {
+          throw new Error(`${arg} expects one of: ${FAIL_ON_LEVELS.join(", ")}`);
+        }
+        parsed.failOn = value;
+        i++;
+        break;
+      }
+      case "--start":
+        parsed.start = next(i, arg);
+        i++;
+        break;
+      case "--start-timeout":
+        parsed.startTimeoutMs = toInt(next(i, arg), arg);
+        i++;
+        break;
+      case "--start-cwd":
+        parsed.startCwd = next(i, arg);
+        i++;
+        break;
+      case "--report":
+        parsed.report = next(i, arg);
+        i++;
+        break;
+      case "--baseline":
+        parsed.baseline = next(i, arg);
+        i++;
+        break;
+      case "--regressions-only":
+        parsed.regressionsOnly = true;
+        break;
+      case "--max-debt":
+        parsed.maxDebt = toInt(next(i, arg), arg);
+        i++;
+        break;
+      case "--depth":
+        parsed.options.depth = toInt(next(i, arg), arg);
+        i++;
+        break;
+      case "--max-pages":
+        parsed.options.maxPages = toInt(next(i, arg), arg);
+        i++;
+        break;
+      case "--timeout":
+        parsed.options.timeoutMs = toInt(next(i, arg), arg);
+        i++;
+        break;
+      case "--include":
+        parsed.options.include.push(next(i, arg));
+        i++;
+        break;
+      case "--exclude":
+        parsed.options.exclude.push(next(i, arg));
+        i++;
+        break;
+      default:
+        if (arg && arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+        if (arg && !parsed.url) parsed.url = arg;
+        else if (arg) throw new Error(`unexpected argument: ${arg}`);
+    }
+  }
+  if (parsed.baseline && !parsed.regressionsOnly) {
+    throw new Error(
+      "--baseline weakens the gate, so it must be requested explicitly: add --regressions-only"
+    );
+  }
+  if (parsed.regressionsOnly && !parsed.baseline) {
+    throw new Error("--regressions-only needs a --baseline <file> to compare against");
+  }
+  return parsed;
+}
+function toInt(value, flag) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`${flag} expects a non-negative integer`);
+  return n;
+}
+
+// src/cli.ts
+async function readVersion() {
+  try {
+    const { readFileSync } = await import("fs");
+    const { fileURLToPath } = await import("url");
+    const { dirname, join } = await import("path");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`goflag: ${err.message}
+
+${HELP}
+`);
+    return 2;
+  }
+  if (args.help) {
+    process.stdout.write(`${HELP}
+`);
+    return 0;
+  }
+  if (args.version) {
+    process.stdout.write(`${await readVersion()}
+`);
+    return 0;
+  }
+  if (!args.url) {
+    process.stderr.write(`goflag: missing <url>
+
+${HELP}
+`);
+    return 2;
+  }
+  const logger = new Logger({
+    stream: process.stderr,
+    mode: args.logMode,
+    color: process.stderr.isTTY === true && !process.env.NO_COLOR
+  });
+  let server;
+  let report;
+  try {
+    if (args.start) {
+      logger.note(`goflag: starting \`${args.start}\` \u2026`);
+      server = await startServer({
+        command: args.start,
+        cwd: args.startCwd,
+        url: args.url,
+        timeoutMs: args.startTimeoutMs,
+        allowInsecureTls: args.options.allowInsecureTls,
+        onOutput: args.logMode === "verbose" ? (chunk) => process.stderr.write(chunk) : void 0
+      });
+    }
+    logger.note(`goflag: auditing ${args.url} \u2026`);
+    report = await runAudit(args.url, { ...args.options, onProgress: logger.onProgress });
+    logger.stop();
+  } catch (err) {
+    logger.stop();
+    process.stderr.write(`goflag: ${err.message}
+`);
+    return 2;
+  } finally {
+    await server?.stop();
+  }
+  if (args.baseline) {
+    try {
+      const { readFileSync } = await import("fs");
+      const baseline = JSON.parse(readFileSync(args.baseline, "utf8"));
+      report.diff = diffReports(baseline, report);
+    } catch (err) {
+      process.stderr.write(
+        `goflag: could not read baseline ${args.baseline}: ${err.message}
+`
+      );
+      return 2;
+    }
+  }
+  if (args.report) {
+    const { writeFileSync } = await import("fs");
+    writeFileSync(args.report, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+    process.stderr.write(`goflag: report written to ${args.report}
+`);
+  }
+  if (report.diff && !args.json) {
+    process.stdout.write(`${renderDiffTerminal(report.diff, { color: args.color })}
+`);
+    const total2 = totalFindings(report);
+    if (args.maxDebt !== void 0 && total2 > args.maxDebt) {
+      process.stderr.write(
+        `goflag: ${total2} findings exceeds the --max-debt budget of ${args.maxDebt}.
+`
+      );
+    }
+    return diffExitCode(report.diff, args.failOn, { total: total2, max: args.maxDebt });
+  }
+  if (args.summary) {
+    const summary = summarize(report);
+    process.stdout.write(
+      args.json ? `${JSON.stringify(summary, null, 2)}
+` : `${renderSummaryTerminal(summary, { color: args.color })}
+`
+    );
+  } else {
+    process.stdout.write(
+      args.json ? `${JSON.stringify(report, null, 2)}
+` : `${renderTerminal(report, { color: args.color })}
+`
+    );
+  }
+  const total = totalFindings(report);
+  if (args.maxDebt !== void 0 && total > args.maxDebt) {
+    process.stderr.write(
+      `goflag: ${total} findings exceeds the --max-debt budget of ${args.maxDebt}.
+`
+    );
+    return 1;
+  }
+  if (report.diff) {
+    return diffExitCode(report.diff, args.failOn, { total, max: args.maxDebt });
+  }
+  return exitCode(report, args.failOn);
+}
+main().then((code) => process.exit(code)).catch((err) => {
+  process.stderr.write(`goflag: unexpected error: ${err.stack ?? err}
+`);
+  process.exit(2);
+});
+//# sourceMappingURL=cli.js.map