shipready 1.4.0 → 1.5.1

package/README.md

@@ -4,6 +4,7 @@
 
 [![CI](https://github.com/formalness/shipready/actions/workflows/ci.yml/badge.svg)](https://github.com/formalness/shipready/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/shipready.svg)](https://www.npmjs.com/package/shipready)
+[![tests](https://img.shields.io/badge/tests-179%20passing-brightgreen.svg)](https://github.com/formalness/shipready/tree/main/tests)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 
@@ -37,9 +38,10 @@ shipready check
 ## Usage
 
 ```bash
-shipready check [path]   # scan a project (current dir by default)
-shipready init  [path]   # generate AI-agent instruction files
-shipready fix   [path]   # apply safe automatic fixes
+shipready check  [path]   # scan a project (current dir by default)
+shipready staged [path]   # fast secrets-only scan of staged files (pre-commit)
+shipready init   [path]   # generate AI-agent instruction files
+shipready fix    [path]   # apply safe automatic fixes (--dry-run to preview)
 ```
 
 ## Commands
@@ -52,6 +54,7 @@ Scans the project and prints a report with a 0-100 score.
 | --- | --- |
 | `-v, --verbose` | show file and line locations for every finding |
 | `--json` | output the raw structured report as JSON (great for CI) |
+| `--sarif` | output SARIF 2.1.0 for **GitHub code scanning** — findings become native PR alerts |
 | `--fix` | apply safe fixes, re-scan, and show the score before/after |
 | `--history` | also scan the **full git history** (all branches) for secrets that were committed and later removed |
 | `--verify` | check detected keys against provider APIs to see if they are **live right now** |
@@ -74,6 +77,27 @@ For 12+ providers (OpenAI, Anthropic, GitHub, GitLab, Stripe, SendGrid, Google,
 
 Verification requests contain only the key itself, go directly to the provider's official API host, and never mutate remote state. Nothing is ever sent to any third party.
 
+### `shipready staged [path]`
+
+Fast, secrets-only scan of the files **staged for commit** — built for pre-commit hooks. It reads content from the git index (`git show :file`), so partially staged files are checked exactly as they would be committed, not as they sit on disk.
+
+- High-confidence secrets **block the commit** (exit code 1)
+- Medium-confidence findings warn but do not block
+- TODO/console.log are deliberately not checked — hooks must be fast and only stop real dangers
+
+Hook setup with [husky](https://typicode.github.io/husky/):
+
+```bash
+npx husky init
+echo "npx shipready staged" > .husky/pre-commit
+```
+
+Or plain git:
+
+```bash
+echo 'npx shipready staged' > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+```
+
 ### `shipready init [path]`
 
 Generates AI-agent instruction files based on your detected framework, package manager, and scripts:
@@ -94,6 +118,21 @@ Applies safe automatic fixes:
 
 It never deletes user code and never overwrites files without `--force`. A summary of changed files is printed at the end.
 
+Pass `--dry-run` to preview exactly what would change — nothing is written to disk:
+
+```txt
+shipready fix --dry-run
+
++ would create .env.example
+    | # Environment variables used by this project.
+    | API_URL=
++ would create .gitignore
+    | .env
+    | node_modules
+
+2 files would change. Run without --dry-run to apply.
+```
+
 ## Example output
 
 ```txt
@@ -194,7 +233,14 @@ If shipready flags a line you know is safe (a demo value, an already-revoked key
 const DEMO_TOKEN = "ghp_thisIsADocumentationExample000000"; // shipready-ignore
 ```
 
-The scanner skips any line containing `shipready-ignore`. For project-wide exceptions, prefer `secretAllowlist` in the config (see below) so the suppression is reviewable in one place.
+The marker works for **all checks** — secrets, `console.log`, `TODO`/`FIXME`, and `debugger` alike:
+
+```js
+console.log("startup banner"); // shipready-ignore
+// TODO: legacy, tracked in JIRA-123 - shipready-ignore
+```
+
+For project-wide exceptions, prefer `secretAllowlist` in the config (see below) so the suppression is reviewable in one place.
 
 ## Configuration
 
@@ -251,6 +297,33 @@ Example with options:
           version: "1.0.3"
 ```
 
+### GitHub code scanning (SARIF)
+
+Turn shipready findings into **native code scanning alerts** on pull requests:
+
+```yaml
+# .github/workflows/shipready-sarif.yml
+name: shipready code scanning
+on: [push, pull_request]
+permissions:
+  security-events: write
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx shipready check --sarif > shipready.sarif || true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: shipready.sarif
+```
+
+Findings appear in the repository's **Security → Code scanning** tab and as inline PR annotations, with stable fingerprints so alerts track across pushes.
+
+### Pre-commit hook
+
+Catch secrets **before** they enter history at all — see [`shipready staged`](#shipready-staged-path) above.
+
 ### Manual setup
 
 `shipready check` exits with code `1` when errors are found, so it works in any CI:
@@ -259,7 +332,7 @@ Example with options:
       - run: npx shipready check --verbose
 ```
 
-Use `--json` to feed the report into other tooling.
+Use `--json` to feed the report into other tooling, or `--sarif` for anything that speaks SARIF.
 
 ## Scoring
 
@@ -290,12 +363,28 @@ pnpm dev      # run the CLI from source (tsx)
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for project structure and how to add new checks or secret patterns.
 
+## How does it compare to gitleaks?
+
+Measured head-to-head on a corpus of 7 real-format leaks and 10 false-positive baits (gitleaks v8.24.3):
+
+| | shipready | gitleaks |
+| --- | --- | --- |
+| Real leaks caught | **7 / 7** | 4 / 7 |
+| Error-level false positives | **0** | 1 |
+| Newer key formats (`sk-proj-`, `sk-ant-`) | ✓ | missed |
+| Committed `.env.backup` | ✓ | partial |
+
+gitleaks remains more battle-tested for deep git-history forensics with hundreds of rules. shipready covers the leaks that actually happen in modern AI-assisted projects — plus README, env hygiene, and code hygiene that gitleaks doesn't check at all. Full methodology, fairness notes, and reproduction steps: [BENCHMARK.md](./BENCHMARK.md).
+
 ## Roadmap
 
+- [x] `shipready staged` for pre-commit hooks
+- [x] SARIF report output for GitHub code scanning
+- [x] Git history scanning (`--history`)
+- [x] Live key verification (`--verify`)
+- [x] Benchmark against gitleaks with published numbers ([BENCHMARK.md](./BENCHMARK.md))
+- [ ] Framework-aware scoring (Next.js vs Vite vs Python have different needs)
 - [ ] Optional AI-powered fix suggestions (bring your own key)
-- [ ] `shipready check --staged` for pre-commit hooks
-- [ ] Markdown/SARIF report output for GitHub code scanning
-- [ ] More frameworks and secret providers
 
 ## License
 

package/dist/checks/secrets.js

@@ -232,6 +232,17 @@ const PATTERNS = [
         group: 1,
         minEntropy: 3.8,
     },
+    {
+        // Unquoted dotenv-style assignment (KEY=value at line start). Catches
+        // committed .env backups where values carry no quotes - a gap found by
+        // benchmarking against gitleaks. Anchored to line start so ordinary
+        // code assignments (always quoted) don't double-match.
+        kind: "Hardcoded credential",
+        re: /^[A-Z0-9_]*(?:API_?KEY|SECRET(?:_KEY)?|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)[A-Z0-9_]*=([A-Za-z0-9+/_.=-]{16,})\s*$/,
+        confidence: "medium",
+        group: 1,
+        minEntropy: 3.8,
+    },
 ];
 /** Words and shapes that indicate a placeholder, not a real secret. */
 const PLACEHOLDER_VALUE_RE = /your[-_ ]?|example|sample|placeholder|change[-_ ]?me|dummy|fake|insert|replace|redacted|deadbeef|lorem|goes[-_ ]?here|test[-_ ]?key|x{4,}|\*{3,}|\.\.\.|123456|abcdef/i;

package/dist/checks/staged.js

@@ -0,0 +1,55 @@
+import { execFileSync } from "node:child_process";
+import { scanContentForSecrets } from "./secrets.js";
+/**
+ * Pre-commit mode: scans only the files staged in the git index.
+ * Reads content via `git show :<file>` so partially staged files are
+ * checked exactly as they would be committed, not as they sit on disk.
+ * Secrets-only by design - a pre-commit hook must be fast and only
+ * block on real dangers, not TODO comments.
+ */
+/** Extensions and paths we skip in staged mode (binary/vendor noise). */
+const STAGED_SKIP_RE = /(^|\/)(node_modules|vendor|dist|build|\.next|out|coverage)(\/|$)|\.(lock|min\.js|min\.css|map|png|jpg|jpeg|gif|webp|svg|ico|pdf|zip|gz|woff2?|ttf|eot|mp3|mp4)$|(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/i;
+/** Lists files staged for commit (added/copied/modified/renamed). */
+export function listStagedFiles(root) {
+    try {
+        const out = execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR", "-z"], { cwd: root, encoding: "utf8" });
+        return out.split("\0").filter((f) => f.length > 0 && !STAGED_SKIP_RE.test(f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Reads a file's staged (index) content, not the working-tree version. */
+export function readStagedContent(root, file) {
+    try {
+        const buf = execFileSync("git", ["show", `:${file}`], {
+            cwd: root,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        // Binary sniff: NUL byte in the first 512 bytes.
+        const head = buf.subarray(0, 512);
+        for (const byte of head) {
+            if (byte === 0)
+                return null;
+        }
+        return buf.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Scans all staged files for secrets. */
+export function scanStaged(root, allowlist = []) {
+    const files = listStagedFiles(root);
+    const secrets = [];
+    for (const file of files) {
+        // .env files are expected to hold real values; committing one at all is
+        // the problem, and the gitignore check covers that. But since it IS
+        // being committed here, flag everything inside it too.
+        const content = readStagedContent(root, file);
+        if (content === null)
+            continue;
+        secrets.push(...scanContentForSecrets(content, file, allowlist));
+    }
+    return { files, secrets };
+}

package/dist/checks/todos.js

@@ -13,6 +13,10 @@ export function scanContentForTodos(content, file) {
     const lines = content.split("\n");
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        // Same suppression marker the secret scanner honors - one convention
+        // for all checks, so intentional console.log/TODO lines stay quiet.
+        if (line.includes("shipready-ignore"))
+            continue;
         const marker = line.match(MARKER_RE);
         if (marker) {
             found.push({ kind: "marker", label: marker[1], file, line: i + 1 });

package/dist/cli.js

@@ -9,17 +9,27 @@ import { fixAgentFiles } from "./fixers/agentFiles.js";
 import { fixEnvExample } from "./fixers/envExample.js";
 import { fixGitignore } from "./fixers/gitignore.js";
 import { renderReport } from "./utils/report.js";
-function printFixResults(results) {
+import { toSarif } from "./utils/sarif.js";
+import { scanStaged } from "./checks/staged.js";
+import { isGitRepo } from "./checks/history.js";
+function printFixResults(results, showPreview = false) {
     for (const r of results) {
+        const verb = (v) => (r.dryRun ? `would ${v.replace(/ed$/, "e")}` : v);
         if (r.action === "created") {
-            console.log(`${pc.green("+")} created ${pc.bold(r.file)}`);
+            console.log(`${pc.green("+")} ${verb("created")} ${pc.bold(r.file)}`);
         }
         else if (r.action === "updated") {
-            console.log(`${pc.yellow("~")} updated ${pc.bold(r.file)}`);
+            console.log(`${pc.yellow("~")} ${verb("updated")} ${pc.bold(r.file)}`);
         }
         else {
             console.log(`${pc.dim("-")} skipped ${r.file}${r.reason ? pc.dim(` (${r.reason})`) : ""}`);
         }
+        if (showPreview && r.preview && r.action !== "skipped") {
+            const lines = r.preview.trimEnd().split("\n");
+            for (const l of lines) {
+                console.log(pc.dim("    | ") + pc.green(l));
+            }
+        }
     }
 }
 /** Resolves and validates the target directory argument. */
@@ -34,14 +44,14 @@ function resolveRoot(dir) {
     return root;
 }
 /** Applies all safe fixes for the given root; returns the results. */
-async function applyFixes(root, force) {
+async function applyFixes(root, force, dryRun = false) {
     const config = loadConfig(root);
     const project = await detectProject(root, config);
     const { envUsages } = scanFiles(root, project.sourceFiles, config.secretAllowlist);
     return [
-        fixEnvExample(root, envUsages, force),
-        fixGitignore(root),
-        ...fixAgentFiles(root, project, force),
+        fixEnvExample(root, envUsages, force, dryRun),
+        fixGitignore(root, dryRun),
+        ...fixAgentFiles(root, project, force, dryRun),
     ];
 }
 /** Reads the CLI's own version from its package.json (works from dist/ at runtime). */
@@ -68,14 +78,16 @@ export function buildProgram() {
         .argument("[path]", "project directory to scan (defaults to current directory)")
         .option("-v, --verbose", "show file locations for every finding")
         .option("--json", "output the raw report as JSON")
+        .option("--sarif", "output the report as SARIF 2.1.0 for GitHub code scanning")
         .option("--fix", "apply safe fixes, then re-scan and show the improved report")
         .option("--history", "also scan the full git history for leaked secrets")
         .option("--verify", "check detected keys against provider APIs to see if they are live")
         .action(async (dir, opts) => {
         try {
             const root = resolveRoot(dir);
+            const machineOutput = Boolean(opts.json || opts.sarif);
             const scanOpts = { history: opts.history, verify: opts.verify };
-            if (opts.verify && !opts.json) {
+            if (opts.verify && !machineOutput) {
                 console.log(pc.dim("\n  Verifying detected keys against provider APIs..."));
             }
             let report = await runScan(root, scanOpts);
@@ -83,7 +95,7 @@ export function buildProgram() {
                 const before = report.score;
                 const results = await applyFixes(root, false);
                 report = await runScan(root, scanOpts);
-                if (!opts.json) {
+                if (!machineOutput) {
                     console.log("");
                     console.log(pc.bold(pc.magenta("shipready check --fix")));
                     console.log("");
@@ -94,7 +106,10 @@ export function buildProgram() {
                         (delta > 0 ? pc.green(` (+${delta})`) : pc.dim(" (no change)")));
                 }
             }
-            if (opts.json) {
+            if (opts.sarif) {
+                console.log(toSarif(report, ownVersion()));
+            }
+            else if (opts.json) {
                 console.log(JSON.stringify(report, null, 2));
             }
             else {
@@ -140,19 +155,28 @@ export function buildProgram() {
         .description("Apply safe automatic fixes (.env.example, .gitignore, agent files)")
         .argument("[path]", "project directory (defaults to current directory)")
         .option("-f, --force", "overwrite existing files")
+        .option("--dry-run", "show what would change without writing anything")
         .action(async (dir, opts) => {
         try {
             const root = resolveRoot(dir);
+            const dryRun = opts.dryRun ?? false;
             console.log("");
-            console.log(pc.bold(pc.magenta("shipready fix")));
+            console.log(pc.bold(pc.magenta(`shipready fix${dryRun ? " --dry-run" : ""}`)));
             console.log("");
-            const results = await applyFixes(root, opts.force ?? false);
-            printFixResults(results);
+            const results = await applyFixes(root, opts.force ?? false, dryRun);
+            printFixResults(results, dryRun);
             const changed = results.filter((r) => r.action !== "skipped").length;
             console.log("");
-            console.log(changed > 0
-                ? pc.green(`${changed} file${changed > 1 ? "s" : ""} changed.`)
-                : pc.dim("Nothing to fix - everything already in place."));
+            if (dryRun) {
+                console.log(changed > 0
+                    ? pc.yellow(`${changed} file${changed > 1 ? "s" : ""} would change. Run without --dry-run to apply.`)
+                    : pc.dim("Nothing to fix - everything already in place."));
+            }
+            else {
+                console.log(changed > 0
+                    ? pc.green(`${changed} file${changed > 1 ? "s" : ""} changed.`)
+                    : pc.dim("Nothing to fix - everything already in place."));
+            }
             console.log("");
         }
         catch (err) {
@@ -160,6 +184,54 @@ export function buildProgram() {
             process.exitCode = 1;
         }
     });
+    program
+        .command("staged")
+        .description("Fast secrets-only scan of files staged for commit (pre-commit hook)")
+        .argument("[path]", "project directory (defaults to current directory)")
+        .action(async (dir) => {
+        try {
+            const root = resolveRoot(dir);
+            if (!isGitRepo(root)) {
+                console.error(pc.red("shipready staged: not a git repository"));
+                process.exitCode = 1;
+                return;
+            }
+            const config = loadConfig(root);
+            const { files, secrets } = scanStaged(root, config.secretAllowlist);
+            if (files.length === 0) {
+                console.log(pc.dim("shipready staged: no staged files to scan."));
+                return;
+            }
+            const high = secrets.filter((s) => s.confidence !== "medium");
+            const medium = secrets.filter((s) => s.confidence === "medium");
+            if (secrets.length === 0) {
+                console.log(pc.green("✓") +
+                    ` shipready staged: ${files.length} file${files.length > 1 ? "s" : ""} clean.`);
+                return;
+            }
+            console.log("");
+            for (const s of high) {
+                console.log(`${pc.red("✗")} ${s.kind}: ${s.masked} ${pc.dim(`${s.file}:${s.line}`)}`);
+            }
+            for (const s of medium) {
+                console.log(`${pc.yellow("⚠")} ${s.kind}: ${s.masked} ${pc.dim(`${s.file}:${s.line}`)} ${pc.dim("(low confidence)")}`);
+            }
+            console.log("");
+            if (high.length > 0) {
+                console.log(pc.red(`Blocked: ${high.length} secret${high.length > 1 ? "s" : ""} in staged files. ` +
+                    `Remove them (or add // shipready-ignore for intentional values) and retry.`));
+                // Only high-confidence findings block the commit; medium is a warning.
+                process.exitCode = 1;
+            }
+            else {
+                console.log(pc.yellow("Warning only - commit not blocked."));
+            }
+        }
+        catch (err) {
+            console.error(pc.red(`shipready staged failed: ${err.message}`));
+            process.exitCode = 1;
+        }
+    });
     return program;
 }
 /** CLI entry: parses argv and runs the matching command. */

package/dist/fixers/agentFiles.js

@@ -8,7 +8,7 @@ const TARGETS = [
     { file: ".cursor/rules/shipready.md", generate: generateCursorRules },
 ];
 /** Generates all agent instruction files, honoring --force. */
-export function fixAgentFiles(root, project, force) {
+export function fixAgentFiles(root, project, force, dryRun = false) {
     const results = [];
     for (const { file, generate } of TARGETS) {
         if (fileExists(root, file) && !force) {
@@ -16,8 +16,11 @@ export function fixAgentFiles(root, project, force) {
             continue;
         }
         const existed = fileExists(root, file);
-        writeTextFile(root, file, generate(project));
-        results.push({ file, action: existed ? "updated" : "created" });
+        if (!dryRun) {
+            writeTextFile(root, file, generate(project));
+        }
+        // Agent files are long; the dry-run preview stays terse on purpose.
+        results.push({ file, action: existed ? "updated" : "created", dryRun });
     }
     return results;
 }

package/dist/fixers/envExample.js

@@ -12,7 +12,7 @@ export function buildEnvExample(usages) {
     return lines.join("\n");
 }
 /** Creates .env.example if missing (or with force). */
-export function fixEnvExample(root, usages, force) {
+export function fixEnvExample(root, usages, force, dryRun = false) {
     const file = ".env.example";
     const names = [...new Set(usages.map((u) => u.name))];
     if (names.length === 0) {
@@ -22,6 +22,14 @@ export function fixEnvExample(root, usages, force) {
         return { file, action: "skipped", reason: "already exists (use --force)" };
     }
     const existed = fileExists(root, file);
-    writeTextFile(root, file, buildEnvExample(usages));
-    return { file, action: existed ? "updated" : "created" };
+    const content = buildEnvExample(usages);
+    if (!dryRun) {
+        writeTextFile(root, file, content);
+    }
+    return {
+        file,
+        action: existed ? "updated" : "created",
+        dryRun,
+        preview: content,
+    };
 }

package/dist/fixers/gitignore.js

@@ -1,7 +1,7 @@
 import { missingIgnoreEntries } from "../checks/gitignore.js";
 import { readTextFile, writeTextFile } from "../utils/files.js";
 /** Adds missing important entries to .gitignore (creates it if absent). */
-export function fixGitignore(root) {
+export function fixGitignore(root, dryRun = false) {
     const file = ".gitignore";
     const existing = readTextFile(root, file);
     if (existing === null) {
@@ -15,8 +15,10 @@ export function fixGitignore(root) {
             ".next",
             "",
         ].join("\n");
-        writeTextFile(root, file, content);
-        return { file, action: "created" };
+        if (!dryRun) {
+            writeTextFile(root, file, content);
+        }
+        return { file, action: "created", dryRun, preview: content };
     }
     const missing = missingIgnoreEntries(existing);
     if (missing.length === 0) {
@@ -24,6 +26,9 @@ export function fixGitignore(root) {
     }
     const suffix = existing.endsWith("\n") ? "" : "\n";
     const addition = `${suffix}\n# Added by shipready\n${missing.join("\n")}\n`;
-    writeTextFile(root, file, existing + addition);
-    return { file, action: "updated" };
+    if (!dryRun) {
+        writeTextFile(root, file, existing + addition);
+    }
+    // Preview shows only what gets appended, not the whole file.
+    return { file, action: "updated", dryRun, preview: addition.trimStart() };
 }

package/dist/scanner.js

@@ -42,11 +42,18 @@ export function scanFiles(root, files, secretAllowlist = []) {
      * an example is just as dangerous - but hygiene noise is skipped.
      */
     const HYGIENE_EXEMPT_RE = /(?:^|\/)(?:examples?|demos?|benchmarks?|scripts?|playground)\//;
+    /**
+     * Standard env file names that legitimately hold real values and are
+     * expected to be gitignored - the env check owns those. Anything else
+     * that merely starts with ".env" (.env.backup, .env.old, .env.prod)
+     * is a copy someone made and MUST be scanned: benchmark testing showed
+     * gitleaks catches committed .env backups while we used to skip them.
+     */
+    const STANDARD_ENV_RE = /^\.env(?:\.(?:local|development|production|test|staging))?(?:\.local)?$/;
     for (const file of files) {
         const base = path.basename(file);
-        // Never flag .env files themselves for secrets/todos; they are expected
-        // to contain real values and are handled by the env check.
-        const isEnvFile = base.startsWith(".env");
+        const isStandardEnv = STANDARD_ENV_RE.test(base);
+        const isEnvTemplate = base === ".env.example" || base === ".env.sample" || base === ".env.template";
         const ext = path.extname(file).toLowerCase();
         const isCode = CODE_ONLY.has(ext);
         if (isProbablyBinary(root, file))
@@ -60,7 +67,7 @@ export function scanFiles(root, files, secretAllowlist = []) {
                 todos.push(...scanContentForTodos(content, file));
             }
         }
-        if (!isEnvFile && base !== ".env.example" && base !== ".env.sample") {
+        if (!isStandardEnv && !isEnvTemplate) {
             secrets.push(...scanContentForSecrets(content, file, secretAllowlist));
         }
     }

package/dist/utils/sarif.js

@@ -0,0 +1,85 @@
+/** Maps shipready severity to a SARIF level. */
+function toLevel(severity) {
+    if (severity === "error")
+        return "error";
+    if (severity === "warning")
+        return "warning";
+    return "note";
+}
+/** Human-friendly rule names derived from rule ids ("secrets.detected-item" -> "SecretsDetectedItem"). */
+function ruleName(ruleId) {
+    return ruleId
+        .split(/[.-]/)
+        .filter(Boolean)
+        .map((p) => p[0].toUpperCase() + p.slice(1))
+        .join("");
+}
+/** Simple stable fingerprint so GitHub tracks alerts across pushes. */
+function fingerprint(f) {
+    const raw = `${f.rule}|${f.file ?? ""}|${f.message}`;
+    let hash = 0;
+    for (let i = 0; i < raw.length; i++) {
+        hash = (hash * 31 + raw.charCodeAt(i)) | 0;
+    }
+    return (hash >>> 0).toString(16);
+}
+/** Converts a shipready report to a SARIF 2.1.0 log string. */
+export function toSarif(report, version) {
+    const rules = new Map();
+    const results = [];
+    for (const check of report.results) {
+        for (const f of check.findings) {
+            // Success/info summary rows aren't actionable alerts.
+            if (f.severity === "success")
+                continue;
+            if (f.severity === "info" && !f.file)
+                continue;
+            if (!rules.has(f.rule)) {
+                rules.set(f.rule, {
+                    id: f.rule,
+                    name: ruleName(f.rule),
+                    shortDescription: { text: f.rule },
+                    defaultConfiguration: { level: toLevel(f.severity) },
+                    helpUri: "https://github.com/formalness/shipready#readme",
+                });
+            }
+            results.push({
+                ruleId: f.rule,
+                level: toLevel(f.severity),
+                message: { text: f.message },
+                locations: [
+                    {
+                        physicalLocation: {
+                            artifactLocation: {
+                                // SARIF requires a location; findings without a file anchor
+                                // to the repo root via package.json-ish convention.
+                                uri: f.file ?? ".",
+                                uriBaseId: "%SRCROOT%",
+                            },
+                            ...(f.line && f.line > 0 ? { region: { startLine: f.line } } : {}),
+                        },
+                    },
+                ],
+                partialFingerprints: { shipready: fingerprint(f) },
+            });
+        }
+    }
+    const log = {
+        $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "shipready",
+                        version,
+                        informationUri: "https://github.com/formalness/shipready",
+                        rules: [...rules.values()],
+                    },
+                },
+                results,
+            },
+        ],
+    };
+    return JSON.stringify(log, null, 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipready",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Pre-flight check for your repo before shipping. Scans AI-coded projects for secrets, env issues, debug leftovers, and generates AI-agent instruction files.",
   "type": "module",
   "license": "MIT",