@getfootgun/footgun 0.2.1 → 0.2.3

package/README.md

@@ -14,6 +14,8 @@ npx @getfootgun/footgun scan [path] [--json] [--fail-on breaks|will-break] [--ke
 - `--fail-on breaks` exits 1 when something breaks now. `--fail-on will-break` also exits 1 for anything with a known break date or version. Use either in CI.
 - Exit code 2 means the rules could not be downloaded and there is no cached copy. Exit code 3 means the scan could not run.
 
+After a scan, `scan` prints a Markdown badge for your README, dated the day it ran. It reads "no known API traps" only when the scan found nothing at all, and "scanned" otherwise. `--json` puts the same Markdown in a `badge` field.
+
 Requires Node 20 or later.
 
 `scan` sends one anonymous usage count (that it ran, and how many traps matched at each severity, never paths, package names or code). Set `FOOTGUN_SHARE=false` to turn it off.

package/bin/footgun.mjs

@@ -7,6 +7,7 @@ import { loadPack, NoRulesError, pingCounts, sendPing } from "../lib/pack.mjs";
 import { scanProject } from "../lib/scan.mjs";
 import { runContext } from "../lib/context.mjs";
 import { textReport, jsonReport, failed, FAIL_ON } from "../lib/report.mjs";
+import { badgeMarkdown } from "../lib/badge.mjs";
 const BASE = process.env.FOOTGUN_URL ?? "https://getfootgun.com";
 const KEY = process.env.FOOTGUN_API_KEY;
 const [a, ...rest] = process.argv.slice(2);
@@ -77,11 +78,13 @@ async function scan(args) {
   // a matcher that cannot start rejects here and exits 3 in main, so no clean report is printed
   const result = await scanProject(resolve(o.path), pack.rules);
   const skippedRules = [...pack.skippedRules, ...result.skippedRules];
+  const badge = badgeMarkdown(result.findings, { base: BASE, date: new Date().toISOString().slice(0, 10) });
   if (o.json) {
-    console.log(jsonReport({ findings: result.findings, skippedRules, fromCache, version: pack.version }));
+    console.log(jsonReport({ findings: result.findings, skippedRules, fromCache, version: pack.version, badge }));
   } else {
     for (const s of skippedRules) console.error(clean(`Skipped rule ${s.id}: ${s.why}`));
     console.log(textReport(result.findings));
+    console.log(`\nREADME badge for this scan:\n${badge}`);
   }
   if (failed(result.findings, o.failOn)) process.exitCode = 1;
   await sendPing({ url: BASE, kind: "scan", counts: pingCounts(uniqueTraps(result.findings)) });

package/lib/badge.mjs

@@ -0,0 +1,13 @@
+// The README badge `footgun scan` suggests. It claims only what this scan showed, on the day it ran:
+// "no known API traps" when nothing at all was found (check-yourself items included), otherwise just "scanned".
+
+/** "clean" only when the scan found nothing, not even a check-yourself item. */
+export function badgeStatus(findings) {
+  return findings.length === 0 ? "clean" : "scanned";
+}
+
+export function badgeMarkdown(findings, { base, date }) {
+  const status = badgeStatus(findings);
+  const alt = status === "clean" ? `No known API traps on ${date} · Footgun` : `Scanned by Footgun on ${date}`;
+  return `[![${alt}](${base}/badge.svg?s=${status}&d=${date})](${base}/scan)`;
+}

package/lib/report.mjs

@@ -44,6 +44,6 @@ export function textReport(findings) {
   return out.join("\n");
 }
 
-export function jsonReport({ findings, skippedRules, fromCache, version }) {
-  return JSON.stringify({ version, fromCache, findings, skippedRules }, null, 2);
+export function jsonReport({ findings, skippedRules, fromCache, version, badge }) {
+  return JSON.stringify({ version, fromCache, findings, skippedRules, badge }, null, 2);
 }

package/lib/rules.mjs

@@ -128,6 +128,13 @@ function isSafe(rule) {
   return v;
 }
 
+// A line whose trimmed start is a comment marker is not matched (`#!` shebangs fall under `#`).
+// Block comments are not parsed: only lines starting with `/*` or `*` are skipped.
+const COMMENT_START = /^(?:\/\/|#|\/\*|\*|<!--|--)/;
+// A rule whose pattern itself targets comment syntax (contains `<!--`, or starts with a comment marker) is not subject to the skip.
+// For ordinary rules, `#[attr]`, `#include` and Markdown `*` bullets are skipped like any other comment-looking line.
+const COMMENT_RULE = /<!--|^\^?(?:\\s\*|\(\?:|\()*(?:--|#|\/\/|\/\\\*|\\\*)/;
+
 export function matchRule(rule, relPath, text) {
   if (!isSafe(rule)) return [];
   if (!rule.files.some((g) => globMatch(g, relPath))) return [];
@@ -139,10 +146,12 @@ export function matchRule(rule, relPath, text) {
     return [];
   }
   if (unless && unless.test(text)) return [];
+  const skipComments = !COMMENT_RULE.test(rule.pattern);
   const hits = [];
   const lines = text.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     if (lines[i].length > MAX_LINE) continue;
+    if (skipComments && COMMENT_START.test(lines[i].trimStart())) continue;
     if (re.test(lines[i])) hits.push(i + 1);
   }
   return hits;

package/lib/scan.mjs

@@ -303,16 +303,16 @@ export async function scanProject(root, rules) {
     : [];
 
   const findings = [];
-  const seen = new Set();
+  // one finding per trap per file, at its lowest matching line
+  const first = new Map();
   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);
+    const key = `${ri}\0${rel}`;
     hitRules.add(ri);
-    findings.push(finding(good[ri], rel, line, false));
+    if (!first.has(key) || line < first.get(key).line) first.set(key, { ri, rel, line });
   }
+  for (const { ri, rel, line } of first.values()) 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

package/package.json

@@ -1 +1 @@
-{ "name": "@getfootgun/footgun", "version": "0.2.1", "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" } }
+{ "name": "@getfootgun/footgun", "version": "0.2.3", "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" } }