@getfootgun/footgun 0.0.0-stage → 0.2.0

package/lib/scan.mjs

@@ -0,0 +1,333 @@
+// Local scanner core: reads manifests, decides which trap rules apply to which
+// subtree, and runs detect patterns over files. Nothing leaves the machine.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { Worker } from "node:worker_threads";
+import { ruleProblems, globMatch } from "./rules.mjs";
+import { satisfiesNpm, satisfiesPep440 } from "./versions.mjs";
+import { buildManifests, normalizePypi } from "./manifests.mjs";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".next", "dist", "build", "out", ".venv", "__pycache__"]);
+const MAX_FILE = 1024 * 1024;
+const BUDGET_MS = 200;
+const BATCH_FILES = 64;
+const BATCH_BYTES = 8 * 1024 * 1024;
+const SEVERITIES = ["breaks", "will-break", "silent", "cost"];
+const ECOSYSTEMS = ["npm", "pypi", "github-action", "service"];
+
+// ---------- walking ----------
+
+function loadGitignore(root) {
+  let text = "";
+  try { text = readFileSync(join(root, ".gitignore"), "utf8"); } catch { return []; }
+  const out = [];
+  for (const raw of text.split(/\r?\n/)) {
+    let p = raw.trim();
+    if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+    const dirOnly = p.endsWith("/");
+    if (dirOnly) p = p.replace(/\/+$/, "");
+    const anchored = p.includes("/");
+    p = p.replace(/^\//, "");
+    if (p) out.push({ p, dirOnly, anchored });
+  }
+  return out;
+}
+
+function ignored(rules, rel, name, isDir) {
+  return rules.some((r) => (!r.dirOnly || isDir) && globMatch(r.p, r.anchored ? rel : name));
+}
+
+function isSecretEnv(name) {
+  return (name === ".env" || name.startsWith(".env.")) && name !== ".env.example";
+}
+
+// Test and fixture code is skipped by default; a detect whose globs name test code still runs there.
+const TEST_DIRS = new Set(["test", "tests", "__tests__", "spec", "specs", "__mocks__", "__fixtures__", "fixtures", "e2e"]);
+const TEST_FILE = /\.(test|spec|stories)\./;
+
+function isTestPath(rel) {
+  const parts = rel.split("/");
+  return parts.slice(0, -1).some((p) => TEST_DIRS.has(p)) || TEST_FILE.test(parts[parts.length - 1]);
+}
+
+// a glob targets test code when one of its path segments is a test directory name or its file name is a test file
+// pattern; "test" inside another word ("latest", "contest") does not count
+const TEST_SEGMENT = /^(?:__tests__|tests?|specs?|e2e|playwright)$/;
+const TEST_NAME = /[.{,](?:test|spec)[.},]/;
+
+function targetsTests(d) {
+  return d.files.some((g) => {
+    const parts = g.split("/");
+    return parts.some((p) => TEST_SEGMENT.test(p)) || TEST_NAME.test(parts[parts.length - 1]);
+  });
+}
+
+function walk(root) {
+  const rules = loadGitignore(root);
+  const out = [];
+  const visit = (dir) => {
+    let entries;
+    try { entries = readdirSync(join(root, dir), { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      const rel = dir ? `${dir}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !ignored(rules, rel, e.name, true)) visit(rel);
+      } else if (e.isFile() && !isSecretEnv(e.name) && !ignored(rules, rel, e.name, false)) {
+        out.push(rel);
+      }
+    }
+  };
+  visit("");
+  return out;
+}
+
+export function readManifests(root) {
+  return buildManifests(root, walk(root));
+}
+
+function readText(abs) {
+  try {
+    if (statSync(abs).size > MAX_FILE) return null;
+    const buf = readFileSync(abs);
+    if (buf.subarray(0, 8192).includes(0)) return null;
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+// ---------- rules ----------
+
+function shapeProblem(rule) {
+  if (!rule || typeof rule !== "object" || Array.isArray(rule)) return "rule must be an object";
+  if (typeof rule.id !== "string" || !rule.id) return "id must be a non-empty string";
+  for (const k of ["title", "provider", "fix"]) if (typeof rule[k] !== "string") return `${k} must be a string`;
+  if (!SEVERITIES.includes(rule.severity)) return "severity is not recognised";
+  for (const k of ["deadline", "url"]) {
+    if (rule[k] != null && typeof rule[k] !== "string") return `${k} must be a string or null`;
+  }
+  if (typeof rule.checkManually !== "boolean") return "checkManually must be a boolean";
+  if (!Array.isArray(rule.packages) || !rule.packages.every((p) =>
+    p && ECOSYSTEMS.includes(p.ecosystem) && typeof p.name === "string" && typeof p.range === "string")) {
+    return "packages must be a list of package refs";
+  }
+  if (!Array.isArray(rule.detect)) return "detect must be a list";
+  const problems = rule.detect.flatMap((d) => ruleProblems(d));
+  return problems.length ? [...new Set(problems)].join("; ") : null;
+}
+
+const BROAD = new Set(["*", "", "x", "X"]);
+
+// "any version": a literal wildcard, or a range that both the lowest and a very high version satisfy (">=0", "^0 || >=1")
+function isBroad(range, check) {
+  return BROAD.has(range.trim()) || (check("0.0.0", range) === true && check("999999.0.0", range) === true);
+}
+
+/**
+ * null when m satisfies none of the rule's npm, pypi or github-action refs (a rule with none of those,
+ * such as one with only service refs, never applies to a local scan); else the satisfied ref as
+ * { pkg: { ecosystem, name, version }, broad }, preferring one whose range is narrower than "any version".
+ */
+function applies(rule, m) {
+  const gating = rule.packages.filter((p) => p.ecosystem !== "service");
+  let found = null;
+  for (const p of gating) {
+    const table = p.ecosystem === "npm" ? m.npm : p.ecosystem === "pypi" ? m.pypi : m.actions;
+    const name = p.ecosystem === "pypi" ? normalizePypi(p.name) : p.name;
+    if (!Object.hasOwn(table, name)) continue;
+    const check = p.ecosystem === "pypi" ? satisfiesPep440 : satisfiesNpm;
+    if (check(table[name], p.range) !== true) continue;
+    const broad = isBroad(p.range, check);
+    if (!found || (found.broad && !broad)) found = { pkg: { ecosystem: p.ecosystem, name, version: table[name] }, broad };
+    if (!broad) break;
+  }
+  return found;
+}
+
+// ---------- matching in a worker ----------
+
+function matcherError(cause) {
+  const why = cause instanceof Error ? cause.message : String(cause);
+  return new Error(`Footgun scanner could not start its matcher: ${why}`, { cause });
+}
+
+async function startWorker(detects, progress) {
+  let worker;
+  try {
+    worker = new Worker(new URL("./scan-worker.mjs", import.meta.url), { workerData: { detects, progress } });
+  } catch (err) {
+    throw matcherError(err);
+  }
+  return new Promise((resolve, reject) => {
+    const fail = (err) => { worker.off("message", ready); reject(matcherError(err)); };
+    const exited = (code) => fail(`the matcher exited with code ${code}`);
+    const ready = () => { worker.off("error", fail); worker.off("exit", exited); resolve(worker); };
+    worker.once("message", ready);
+    worker.once("error", fail);
+    worker.once("exit", exited);
+  });
+}
+
+/** Resolves with the hits, plus the detect index that stalled or crashed (if any) and the files not finished. */
+function runBatch(worker, batch, progress) {
+  return new Promise((resolve) => {
+    const done = new Set();
+    const hits = [];
+    // The stall clock starts only once the worker reports its first (file, detect) pair.
+    Atomics.store(progress, 1, -1);
+    let seen = Atomics.load(progress, 0);
+    let seenAt = null;
+    const finish = (stuck, why) => {
+      clearInterval(timer);
+      worker.off("message", onMessage);
+      worker.off("error", onFail);
+      worker.off("exit", onFail);
+      resolve({ hits, stuck, why, rest: batch.filter((_, i) => !done.has(i)) });
+    };
+    const onMessage = ({ i, hits: found }) => {
+      done.add(i);
+      for (const [d, lines] of found) for (const line of lines) hits.push({ rel: batch[i].rel, d, line });
+      if (done.size === batch.length) finish();
+    };
+    const onFail = () => finish(Atomics.load(progress, 1), "rule failed");
+    const timer = setInterval(() => {
+      const now = Atomics.load(progress, 0);
+      if (now !== seen) { seen = now; seenAt = Date.now(); }
+      else if (seenAt !== null && Date.now() - seenAt > BUDGET_MS) finish(Atomics.load(progress, 1), "rule timed out");
+    }, 20);
+    worker.on("message", onMessage);
+    worker.on("error", onFail);
+    worker.on("exit", onFail);
+    worker.postMessage(batch.map(({ rel, text, ds }) => ({ rel, text, ds })));
+  });
+}
+
+/** Runs jobs ({ rel, ds }) and returns hits ({ rel, d, line }). Calls onSkip(ruleIndex, why) for a rule that stalls. */
+async function runDetects(root, jobs, detects, onSkip) {
+  const banned = new Set();
+  const hits = [];
+  const queue = jobs.slice();
+  const nextBatch = () => {
+    const batch = [];
+    let bytes = 0;
+    while (queue.length && batch.length < BATCH_FILES && bytes < BATCH_BYTES) {
+      const job = queue.shift();
+      const ds = job.ds.filter((d) => !banned.has(detects[d].ri));
+      if (!ds.length) continue;
+      const text = job.text ?? readText(join(root, job.rel));
+      if (text === null) continue;
+      batch.push({ rel: job.rel, text, ds });
+      bytes += text.length;
+    }
+    return batch;
+  };
+  const payload = detects.map(({ files, pattern, unless }) => ({ files, pattern, unless }));
+  let batch = nextBatch();
+  while (batch.length) {
+    const progress = new Int32Array(new SharedArrayBuffer(8));
+    const worker = await startWorker(payload, progress.buffer);
+    try {
+      while (batch.length) {
+        const res = await runBatch(worker, batch, progress);
+        hits.push(...res.hits);
+        if (res.stuck === -1) throw matcherError("the matcher stopped before checking any file");
+        if (res.stuck !== undefined) {
+          const ri = detects[res.stuck].ri;
+          banned.add(ri);
+          onSkip(ri, res.why);
+          queue.unshift(...res.rest);
+          batch = nextBatch();
+          break;
+        }
+        batch = nextBatch();
+      }
+    } finally {
+      await worker.terminate();
+    }
+  }
+  return hits.filter((h) => !banned.has(detects[h.d].ri));
+}
+
+// ---------- scan ----------
+
+function finding(rule, file, line, manual) {
+  return {
+    trapId: rule.id,
+    title: rule.title,
+    provider: rule.provider,
+    severity: rule.severity,
+    deadline: rule.deadline ?? null,
+    file,
+    line,
+    fix: rule.fix,
+    url: rule.url ?? null,
+    private: rule.private === true,
+    manual,
+  };
+}
+
+export async function scanProject(root, rules) {
+  const skippedRules = [];
+  const good = [];
+  for (const rule of Array.isArray(rules) ? rules : []) {
+    let why;
+    try { why = shapeProblem(rule); } catch { why = "rule could not be read"; }
+    if (why) skippedRules.push({ id: typeof rule?.id === "string" && rule.id ? rule.id : "(unknown)", why });
+    else good.push(rule);
+  }
+
+  const files = walk(root);
+  const manifests = buildManifests(root, files);
+  const matches = manifests.map((m) => good.map((r) => applies(r, m)));
+  const byDepth = manifests.map((m, i) => ({ dir: m.dir, i })).sort((a, b) => b.dir.length - a.dir.length);
+  const owner = (rel) => byDepth.find(({ dir }) => dir === "" || rel.startsWith(`${dir}/`)).i;
+
+  const detects = good.flatMap((r, ri) => r.detect.map((d) => ({ ri, ...d })));
+  const jobs = [];
+  for (const rel of files) {
+    const ok = matches[owner(rel)];
+    const ds = [];
+    const inTests = isTestPath(rel);
+    detects.forEach((d, k) => { if (ok[d.ri] && (!inTests || targetsTests(d)) && d.files.some((g) => globMatch(g, rel))) ds.push(k); });
+    if (ds.length) jobs.push({ rel, ds });
+  }
+
+  const skipped = new Set();
+  const hits = jobs.length
+    ? await runDetects(root, jobs, detects, (ri, why) => {
+        skipped.add(ri);
+        skippedRules.push({ id: good[ri].id, why });
+      })
+    : [];
+
+  const findings = [];
+  const seen = new Set();
+  const hitRules = new Set();
+  for (const { rel, d, line } of hits) {
+    const ri = detects[d].ri;
+    const key = `${ri}\0${rel}\0${line}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    hitRules.add(ri);
+    findings.push(finding(good[ri], rel, line, false));
+  }
+  findings.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+  // a manual finding and the applicable list both need a ref narrower than "any version": a broad ref
+  // only shows the package is present, which is enough to run detect rules but not to say the trap applies
+  const narrow = (ri) => matches.findIndex((row) => row[ri] && !row[ri].broad);
+  good.forEach((r, ri) => {
+    if (r.checkManually && !skipped.has(ri) && !hitRules.has(ri) && narrow(ri) !== -1) {
+      findings.push(finding(r, null, null, true));
+    }
+  });
+  // rules a manifest satisfies through a ref narrower than "any version", hit or not (the first such
+  // manifest); a rule the matcher skipped is left out, as it is from findings
+  const applicable = [];
+  good.forEach((r, ri) => {
+    const mi = narrow(ri);
+    if (mi !== -1 && !skipped.has(ri)) applicable.push({ trapId: r.id, package: matches[mi][ri].pkg, dir: manifests[mi].dir });
+  });
+  return { findings, skippedRules, applicable };
+}

package/lib/scrub.mjs

@@ -0,0 +1,22 @@
+// Copy of SECRET_PATTERNS in lib/sanitize.ts (this package cannot import from the app).
+// tests/cli.test.ts fails if the two lists drift apart.
+export const SECRET_PATTERNS = [
+  ["anthropic key", /sk-ant-[a-z0-9-]{20,}/i],
+  ["openai key", /(?<![A-Za-z0-9])sk-(?!ant-)(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{32,}/],
+  ["aws access key", /AKIA[0-9A-Z]{16}/],
+  ["github token", /gh[pousr]_[A-Za-z0-9]{30,}/],
+  ["github fine-grained token", /github_pat_[A-Za-z0-9_]{50,}/],
+  ["slack token", /xox[baprs]-[A-Za-z0-9-]{10,}/],
+  ["stripe key", /[sr]k_(live|test)_[A-Za-z0-9]{16,}/],
+  ["google api key", /AIza[0-9A-Za-z_-]{35}/],
+  ["private key block", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+];
+
+// Replaces anything shaped like a known secret before the text leaves this machine.
+export function scrub(text) {
+  let t = String(text ?? "");
+  for (const [name, re] of SECRET_PATTERNS) {
+    t = t.replace(new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`), `<${name} redacted>`);
+  }
+  return t;
+}

package/lib/versions.d.ts

@@ -0,0 +1,7 @@
+import type { PackageRef } from "./rules.mjs";
+
+/** true/false when decidable, null when the version or range is not understood. */
+export function satisfiesNpm(version: string, range: string): boolean | null;
+export function satisfiesPep440(version: string, spec: string): boolean | null;
+/** True when satisfiesX can decide this range, so the rule gate may accept it. */
+export function rangeSupported(ecosystem: PackageRef["ecosystem"], range: string): boolean;

package/lib/versions.mjs

@@ -0,0 +1,265 @@
+// Dependency-free npm semver and PEP 440 range matching.
+// Anything not understood yields null ("unknown, do not match").
+
+const NUM = "0|[1-9]\\d*";
+const PARTIAL = new RegExp(
+  `^[v=]*(${NUM}|[xX*])(?:\\.(${NUM}|[xX*])(?:\\.(${NUM}|[xX*])(?:-([0-9A-Za-z.-]+))?(?:\\+[0-9A-Za-z.-]+)?)?)?$`,
+);
+
+// ---------- npm ----------
+
+function wild(s) {
+  return s === undefined || s === "x" || s === "X" || s === "*";
+}
+
+/** Full version -> [maj, min, pat, pre[]] or null. */
+function parseNpmVersion(v) {
+  const m = PARTIAL.exec(String(v).trim());
+  if (!m || wild(m[1]) || wild(m[2]) || wild(m[3])) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] ? m[4].split(".") : []];
+}
+
+function cmpPre(a, b) {
+  if (!a.length && !b.length) return 0;
+  if (!a.length) return 1;
+  if (!b.length) return -1;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === undefined) return -1;
+    if (b[i] === undefined) return 1;
+    const an = /^\d+$/.test(a[i]);
+    const bn = /^\d+$/.test(b[i]);
+    if (an && bn) {
+      const d = Number(a[i]) - Number(b[i]);
+      if (d) return d < 0 ? -1 : 1;
+    } else if (an !== bn) return an ? -1 : 1;
+    else if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+function cmpNpm(a, b) {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  return cmpPre(a[3], b[3]);
+}
+
+/** Partial -> { n: [maj, min, pat] numbers or null for wildcard, pre, count: specified parts } or null. */
+function parsePartial(s) {
+  const m = PARTIAL.exec(s);
+  if (!m) return null;
+  const parts = [m[1], m[2], m[3]];
+  let count = 0;
+  while (count < 3 && !wild(parts[count])) count++;
+  for (let i = count; i < 3; i++) if (!wild(parts[i])) return null;
+  if (m[4] && count < 3) return null;
+  return { n: parts.map((p, i) => (i < count ? Number(p) : 0)), count, pre: m[4] ? m[4].split(".") : [] };
+}
+
+const lo = (p) => [p.n[0], p.n[1], p.n[2], p.pre];
+const bump = (p, at) => {
+  const n = [p.n[0], p.n[1], p.n[2]];
+  n[at]++;
+  for (let i = at + 1; i < 3; i++) n[i] = 0;
+  return [...n, []];
+};
+const ge = (v) => ({ op: ">=", v });
+const gt = (v) => ({ op: ">", v });
+const lt = (v) => ({ op: "<", v });
+const le = (v) => ({ op: "<=", v });
+
+/** One token (operator + partial) -> comparator list, or null. */
+function npmToken(tok) {
+  const m = /^(\^|~>?|>=|<=|>|<|=)?(.*)$/.exec(tok);
+  const op = m[1] === "~>" ? "~" : m[1] || "";
+  const p = parsePartial(m[2]);
+  if (!p) return null;
+  const { count } = p;
+  if (count === 0) return op === "" || op === "=" || op === ">=" || op === "<=" || op === "^" || op === "~" ? [] : null;
+  const at = Math.min(count, 3) - 1; // index of the last specified part
+  switch (op) {
+    case "":
+    case "=":
+      return count === 3 ? [ge(lo(p)), le(lo(p))] : [ge(lo(p)), lt(bump(p, at))];
+    case "^": {
+      // bump the left-most non-zero specified part
+      let i = 0;
+      while (i < at && p.n[i] === 0) i++;
+      return [ge(lo(p)), lt(bump(p, i))];
+    }
+    case "~":
+      return [ge(lo(p)), lt(bump(p, count === 1 ? 0 : 1))];
+    case ">=":
+      return [ge(lo(p))];
+    case ">":
+      return [count === 3 ? gt(lo(p)) : ge(bump(p, at))];
+    case "<":
+      return [lt(lo(p))];
+    case "<=":
+      return [count === 3 ? le(lo(p)) : lt(bump(p, at))];
+  }
+  return null;
+}
+
+/** Comparator set (AND) from a space-separated string, or null. */
+function npmSet(text) {
+  let s = text.trim();
+  if (s === "") return [];
+  const hy = /^(\S+)\s+-\s+(\S+)$/.exec(s);
+  if (hy) {
+    const a = parsePartial(hy[1].replace(/^v/, ""));
+    const b = parsePartial(hy[2].replace(/^v/, ""));
+    if (!a || !b) return null;
+    const out = [];
+    if (a.count) out.push(ge(lo(a)));
+    if (b.count === 3) out.push(le(lo(b)));
+    else if (b.count) out.push(lt(bump(b, b.count - 1)));
+    return out;
+  }
+  s = s.replace(/(\^|~>?|>=|<=|>|<|=)\s+/g, "$1");
+  const out = [];
+  for (const tok of s.split(/\s+/)) {
+    const c = npmToken(tok);
+    if (!c) return null;
+    out.push(...c);
+  }
+  return out;
+}
+
+function parseNpmRange(range) {
+  if (typeof range !== "string") return null;
+  const sets = [];
+  for (const part of range.split("||")) {
+    const set = npmSet(part);
+    if (!set) return null;
+    sets.push(set);
+  }
+  return sets;
+}
+
+function holds(c, v) {
+  const d = cmpNpm(v, c.v);
+  return c.op === ">=" ? d >= 0 : c.op === ">" ? d > 0 : c.op === "<" ? d < 0 : d <= 0;
+}
+
+export function satisfiesNpm(version, range) {
+  const v = parseNpmVersion(version);
+  const sets = parseNpmRange(range);
+  if (!v || !sets) return null;
+  return sets.some((set) => {
+    if (!set.every((c) => holds(c, v))) return false;
+    if (!v[3].length) return true;
+    // a prerelease only matches a set that names a prerelease of the same major.minor.patch
+    return set.some((c) => c.v[3].length && c.v[0] === v[0] && c.v[1] === v[1] && c.v[2] === v[2]);
+  });
+}
+
+// ---------- PEP 440 ----------
+
+const PEP_VERSION =
+  /^v?(?:\d+!)?(\d+(?:\.\d+)*)(?:[-_.]?(a|alpha|b|beta|c|rc|pre|preview)[-_.]?(\d*))?(?:(?:-(\d+))|(?:[-_.]?(?:post|rev|r)[-_.]?(\d*)))?(?:[-_.]?dev[-_.]?(\d*))?(?:\+[a-z0-9]+(?:[-_.][a-z0-9]+)*)?$/i;
+
+function parsePep(v) {
+  const m = PEP_VERSION.exec(String(v).trim());
+  if (!m) return null;
+  const tag = m[2] && m[2].toLowerCase();
+  const kind = !tag ? null : tag === "a" || tag === "alpha" ? 0 : tag === "b" || tag === "beta" ? 1 : 2;
+  const hasPost = m[4] !== undefined || /post|rev|r/i.test(m[0].slice(m[1].length)) && m[5] !== undefined;
+  return {
+    rel: m[1].split(".").map(Number),
+    pre: kind === null ? null : [kind, Number(m[3] || 0)],
+    post: m[4] !== undefined ? Number(m[4]) : m[5] !== undefined && hasPost ? Number(m[5] || 0) : null,
+    dev: m[6] !== undefined ? Number(m[6] || 0) : null,
+  };
+}
+
+function cmpRel(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function cmpPep(a, b) {
+  const r = cmpRel(a.rel, b.rel);
+  if (r) return r;
+  const preKey = (v) => (v.pre ? v.pre : v.post === null && v.dev !== null ? [-1, 0] : [Infinity, 0]);
+  const pa = preKey(a);
+  const pb = preKey(b);
+  if (pa[0] !== pb[0]) return pa[0] < pb[0] ? -1 : 1;
+  if (pa[1] !== pb[1]) return pa[1] < pb[1] ? -1 : 1;
+  const sa = a.post === null ? -1 : a.post;
+  const sb = b.post === null ? -1 : b.post;
+  if (sa !== sb) return sa < sb ? -1 : 1;
+  const da = a.dev === null ? Infinity : a.dev;
+  const db = b.dev === null ? Infinity : b.dev;
+  return da === db ? 0 : da < db ? -1 : 1;
+}
+
+/** Clause -> predicate over a parsed version, or null. */
+function pepClause(text) {
+  const m = /^(~=|==|!=|>=|<=|>|<)\s*(\S+)$/.exec(text.trim());
+  if (!m) return null;
+  const [, op, raw] = m;
+  const prefix = /^(.*)\.\*$/.exec(raw);
+  if (prefix) {
+    if (op !== "==" && op !== "!=") return null;
+    const p = parsePep(prefix[1]);
+    if (!p || p.pre || p.post !== null || p.dev !== null) return null;
+    const hit = (v) => p.rel.every((n, i) => (v.rel[i] ?? 0) === n);
+    return op === "==" ? hit : (v) => !hit(v);
+  }
+  const t = parsePep(raw);
+  if (!t) return null;
+  switch (op) {
+    case "==":
+      return (v) => cmpPep(v, t) === 0;
+    case "!=":
+      return (v) => cmpPep(v, t) !== 0;
+    case ">=":
+      return (v) => cmpPep(v, t) >= 0;
+    case "<=":
+      return (v) => cmpPep(v, t) <= 0;
+    case ">":
+      return (v) => cmpPep(v, t) > 0;
+    case "<": {
+      // <V never matches a prerelease of V itself
+      const plain = !t.pre && t.dev === null && t.post === null;
+      return (v) => cmpPep(v, t) < 0 && !(plain && (v.pre || v.dev !== null) && cmpRel(v.rel, t.rel) === 0);
+    }
+    case "~=": {
+      if (t.rel.length < 2) return null;
+      const head = t.rel.slice(0, -1);
+      return (v) => cmpPep(v, t) >= 0 && head.every((n, i) => (v.rel[i] ?? 0) === n);
+    }
+  }
+  return null;
+}
+
+function parsePepSpec(spec) {
+  if (typeof spec !== "string" || spec.trim() === "") return null;
+  const preds = [];
+  for (const part of spec.split(",")) {
+    const p = pepClause(part);
+    if (!p) return null;
+    preds.push(p);
+  }
+  return preds;
+}
+
+export function satisfiesPep440(version, spec) {
+  const v = parsePep(version);
+  const preds = parsePepSpec(spec);
+  if (!v || !preds) return null;
+  return preds.every((p) => p(v));
+}
+
+// ---------- rule gate ----------
+
+export function rangeSupported(ecosystem, range) {
+  const r = typeof range === "string" ? range.trim() : "";
+  if (ecosystem === "service") return r === "" || r === "*";
+  if (ecosystem === "pypi") return parsePepSpec(r) !== null;
+  if (ecosystem === "npm" || ecosystem === "github-action") return parseNpmRange(r) !== null;
+  return false;
+}

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@getfootgun/footgun",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{ "name": "@getfootgun/footgun", "version": "0.2.0", "description": "Ask Footgun why a third-party API, platform, or AI tool just broke.", "bin": { "footgun": "bin/footgun.mjs" }, "scripts": { "prepublishOnly": "node ../scripts/check-publish.mjs" }, "type": "module", "license": "MIT", "files": ["bin", "lib", "README.md"], "engines": { "node": ">=20" } }