riskdiff-cli 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 zeitgeistz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,527 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # 🎯 riskdiff
4
+
5
+ **Know which part of a diff to review first.**
6
+
7
+ riskdiff reads a `git diff`, scores every hunk for risk, and sorts the hunks riskiest first.
8
+ It's built for the moment an AI agent hands you 14 changed files and you have five minutes to review them.
9
+
10
+ [![CI](https://github.com/zeitgeistz/riskdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/zeitgeistz/riskdiff/actions/workflows/ci.yml)
11
+ [![Release](https://img.shields.io/github/v/release/zeitgeistz/riskdiff?color=blue)](https://github.com/zeitgeistz/riskdiff/releases)
12
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
13
+ ![Node](https://img.shields.io/badge/node-%E2%89%A518.11-339933?logo=node.js&logoColor=white)
14
+ ![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
15
+
16
+ [Quick start](#-quick-start) · [What it catches](#-what-it-catches) · [Integrations](#-integrations) · [How scoring works](#-how-scoring-works) · [FAQ](#-faq)
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ```text
23
+ $ riskdiff
24
+ riskdiff · 5 files, 5 hunks · 1 high · 2 medium · 1 low
25
+
26
+ ⚠ Tests weakened: 1 test skipped or focused, 1 hunk removed assertions
27
+
28
+ HIGH 50 src/routes/admin.js:2
29
+ +0 −1
30
+ • Removes an authentication or permission check [auth-check-removed +50]
31
+
32
+ MEDIUM 40 test/users.test.js:1
33
+ +1 −2
34
+ • Skips or focuses tests [test-skipped +20]
35
+ • Removes test assertions [assertion-removed +20]
36
+
37
+ MEDIUM 25 src/db/users.js:2
38
+ +1 −1
39
+ • SQL built from string concatenation or interpolation [sql-injection +25]
40
+
41
+ LOW 15 package.json:3
42
+ +2 −1
43
+ • Adds or changes a dependency [new-dependency +15]
44
+ ```
45
+
46
+ In this diff the agent removed `requireAuth`, skipped a failing test instead of fixing it, swapped a parameterized query for string interpolation, and added a package called `react-codeshift`, a name AI models are known to invent. The harmless formatting change in `src/format.js` scored 0 and is hidden.
47
+
48
+ ## 🤔 Why
49
+
50
+ AI writes a growing share of code, but reviewing it hasn't gotten faster:
51
+
52
+ - **96%** of developers don't fully trust AI-generated code, and surveys describe review as the new bottleneck ([Sonar, 2026](https://www.sonarsource.com/blog/state-of-code-developer-survey-report-the-current-reality-of-ai-coding/)).
53
+ - The top frustration is code that is **"almost right, but not quite"** ([Stack Overflow survey via VentureBeat](https://venturebeat.com/technology/stack-overflow-data-reveals-the-hidden-productivity-tax-of-almost-right-ai-code)).
54
+ - Agents skip tests, weaken assertions, and add packages instead of using the ones you already have.
55
+
56
+ A big diff gets read top to bottom, and attention runs out before the dangerous line. riskdiff doesn't replace review. It tells you **where to spend it**.
57
+
58
+ ## ✨ Features
59
+
60
+ - 🧭 **Ranks hunks, not files.** Points you at `file:line`, not "somewhere in this 400-line file".
61
+ - 🔍 **27 built-in rules** for security, data, tests, dependencies, and infrastructure.
62
+ - 📦 **Package check.** Catches dependencies that don't exist, were published last week, look like a popular package, or duplicate a library you already use.
63
+ - 🧠 **Ignores moved code and comments.** Removal rules only fire when something actually disappears, and `// don't use eval()` isn't a call to `eval`.
64
+ - 🧪 **Test tamper warning.** One line tells you when a diff skipped tests, removed assertions, or deleted test files.
65
+ - ⚙️ **Configurable.** Ignore paths, turn rules off, change weights, and add your own rules in `.riskdiff.json`, or silence one hunk with `riskdiff-ignore`.
66
+ - 📦 **Zero dependencies.** Only Node.js and git.
67
+ - 🖥️ **Four output formats:** colored terminal, JSON for tools and agents, Markdown for PR comments, SARIF for code scanning.
68
+ - ⚙️ **GitHub Action:** `uses: zeitgeistz/riskdiff@v1` comments a risk table on every PR and fails the check on high risk.
69
+ - 🚦 **CI gate:** `--fail-on high` exits with code 1.
70
+ - 🤖 **Claude Code plugin:** a hook warns Claude right after it makes a risky edit, an MCP tool lets it scan any range, and a skill walks you through the review.
71
+ - ✦ **Optional AI second opinion** (`--ai`): Claude marks each flagged hunk as likely real or a likely false positive, with one sentence of why. Off by default.
72
+
73
+ ## 🚀 Quick start
74
+
75
+ Requires **Node.js 18.11+** and **git**.
76
+
77
+ ```bash
78
+ # Run without installing
79
+ npx -y github:zeitgeistz/riskdiff
80
+
81
+ # Or install globally
82
+ npm install -g github:zeitgeistz/riskdiff
83
+ riskdiff
84
+ ```
85
+
86
+ ## 📖 Usage
87
+
88
+ ```bash
89
+ riskdiff # working tree + staged + untracked changes vs HEAD
90
+ riskdiff --staged # staged changes only (what you're about to commit)
91
+ riskdiff main...HEAD # everything on this branch since it left main
92
+ riskdiff HEAD~3 # any range git diff accepts
93
+ git diff main | riskdiff # read a diff from stdin
94
+ riskdiff - < change.patch # or from a file
95
+ riskdiff hook # Claude Code PostToolUse hook (see Integrations)
96
+ riskdiff mcp # MCP server over stdio (see Integrations)
97
+ ```
98
+
99
+ | Option | Description |
100
+ |---|---|
101
+ | `--json` | Machine-readable output (see [JSON output](#-json-output)) |
102
+ | `--md` | Markdown table, ready for a PR comment |
103
+ | `--sarif` | SARIF 2.1.0 for GitHub code scanning (see [GitHub Action](#%EF%B8%8F-github-action)) |
104
+ | `-o`, `--output <file>` | Write the report to a file instead of stdout |
105
+ | `--check-packages` | Look new npm and PyPI dependencies up in their registries (see [Package check](#-package-check)) |
106
+ | `--ai` | Ask Claude for a second opinion on the riskiest hunks (see [AI second opinion](#-ai-second-opinion)) |
107
+ | `--code` | Print the changed lines under each hunk |
108
+ | `--fail-on <level>` | Exit with code `1` if any hunk is at or above `low`, `medium`, or `high` |
109
+ | `--config <path>` | Use this config file instead of `.riskdiff.json` in the repo root |
110
+ | `--no-untracked` | Leave out untracked files (included by default when no range is given) |
111
+ | `--no-color` | Disable colors (also respects `NO_COLOR`) |
112
+ | `-h`, `--help` | Show help |
113
+ | `-v`, `--version` | Show version |
114
+
115
+ **Exit codes:** `0` OK · `1` `--fail-on` threshold reached · `2` usage, config, or git error.
116
+
117
+ Untracked files that aren't in `.gitignore` are included as new files. Binary files and files over 1 MB are skipped.
118
+
119
+ ## ⚙️ Configuration
120
+
121
+ Put a `.riskdiff.json` in your repo root. Every key is optional.
122
+
123
+ ```json
124
+ {
125
+ "$schema": "https://raw.githubusercontent.com/zeitgeistz/riskdiff/main/schema/riskdiff.schema.json",
126
+ "ignore": ["dist/**", "*.min.js", "**/__snapshots__/**"],
127
+ "rules": {
128
+ "todo-added": false,
129
+ "new-dependency": 25
130
+ },
131
+ "customRules": [
132
+ {
133
+ "id": "no-console",
134
+ "weight": 5,
135
+ "reason": "Adds console.log",
136
+ "added": ["console\\.log\\("]
137
+ }
138
+ ],
139
+ "failOn": "high"
140
+ }
141
+ ```
142
+
143
+ | Key | What it does |
144
+ |---|---|
145
+ | `checkPackages` | `true` runs the [registry check](#-package-check) on every run. |
146
+ | `ignore` | Globs for files to skip. `**` matches any folders, `*` anything except `/`. A pattern with no `/` matches the file name anywhere, like `.gitignore`. |
147
+ | `rules` | `false` turns a rule off. A number sets its weight. |
148
+ | `customRules` | Your own rules. Each needs `id`, `weight`, `reason`, and exactly one of `path` (regex string), `added`, or `removed` (arrays of regex strings). Optional: `flags` (e.g. `"i"`) and `raw: true` to also match inside comments. |
149
+ | `failOn` | Default for `--fail-on`. The flag wins when both are set. |
150
+
151
+ riskdiff exits with code `2` and a clear message if the config has an unknown key, a bad regex, or a rule id that doesn't exist.
152
+
153
+ ## 🙈 Ignoring a finding
154
+
155
+ Add `riskdiff-ignore` in a comment on any added line of the hunk:
156
+
157
+ ```js
158
+ // riskdiff-ignore auth-check-removed: auth now runs in the gateway middleware
159
+ router.get('/users', listUsers);
160
+ ```
161
+
162
+ - `riskdiff-ignore rule-a, rule-b` silences those rules for that hunk.
163
+ - `riskdiff-ignore` on its own silences every rule for that hunk.
164
+ - Anything after the rule ids is free text, so you can leave the reason for reviewers.
165
+
166
+ Comments are otherwise ignored: `// don't call eval()` doesn't count as calling `eval`, and deleting a commented-out `requireAuth` doesn't count as removing an auth check. Two rules still read comments on purpose: `hardcoded-secret` (a key in a comment still leaks) and `todo-added`.
167
+
168
+ ## 🔍 What it catches
169
+
170
+ ### Code that was added
171
+
172
+ | Rule | Weight | Catches |
173
+ |---|---:|---|
174
+ | `hardcoded-secret` | 50 | `apiKey = "..."`, AWS `AKIA…`, `sk-…`, `ghp_…`, Slack tokens, private keys |
175
+ | `destructive-sql` | 35 | `DROP TABLE`, `TRUNCATE`, `DELETE FROM` without `WHERE` |
176
+ | `dangerous-exec` | 30 | `eval`, `new Function`, `child_process`, `os.system`, `shell=True` |
177
+ | `security-disabled` | 30 | `verify=False`, `rejectUnauthorized: false`, CORS `*`, CSRF exemptions |
178
+ | `sql-injection` | 25 | SQL built with `+`, `${}`, f-strings, or `%` formatting |
179
+ | `test-skipped` | 20 | `it.skip`, `.only`, `xit`, `@pytest.mark.skip`, `@Disabled`, `t.Skip()` |
180
+ | `swallowed-error` | 15 | `catch (e) {}`, `except: pass`, `.catch(() => {})` |
181
+ | `new-dependency` | 15 | New or changed entries in `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, and more |
182
+ | `package-lookalike` | 30 | A new npm/PyPI dependency one or two letters away from a popular package (`reqeusts`, `expresss`) |
183
+ | `duplicate-dependency` | 15 | A new library that does the same job as one you already have (`axios` next to `node-fetch`, `moment` next to `dayjs`) |
184
+ | `todo-added` | 5 | New `TODO`, `FIXME`, `HACK`, `XXX` |
185
+
186
+ ### Code that was removed
187
+
188
+ | Rule | Weight | Catches |
189
+ |---|---:|---|
190
+ | `auth-check-removed` | 50 | `requireAuth`, `isAuthenticated`, `authorize…`, `@login_required`, `@PreAuthorize`, `@UseGuards` |
191
+ | `test-file-deleted` | 25 | A whole test file deleted |
192
+ | `error-handling-removed` | 20 | `try`/`catch`/`except`/`throw`/`raise`, Go `if err != nil` |
193
+ | `validation-removed` | 20 | `validate…()`, `sanitize…()`, `escape…()`, schema `.parse()`, zod, Joi |
194
+ | `assertion-removed` | 20 | `expect(`, `assert…`, `self.assert…` in test files |
195
+
196
+ ### Sensitive places
197
+
198
+ | Rule | Weight | Path matches |
199
+ |---|---:|---|
200
+ | `env-file` | 30 | `.env`, `.env.production` (not `.env.example`) |
201
+ | `auth-code` | 25 | `auth`, `login`, `session`, `password`, `permission`, `oauth`, `jwt`, `rbac` |
202
+ | `payment-code` | 25 | `payment`, `billing`, `checkout`, `invoice`, `stripe`, `subscription` |
203
+ | `crypto-code` | 20 | `crypto`, `encrypt`, `cipher`, `hash`, `signature` |
204
+ | `migration` | 20 | `migrations/`, `*.sql`, `schema.prisma` |
205
+ | `ci-infra` | 20 | `.github/workflows/`, `Dockerfile`, `docker-compose`, `*.tf`, `k8s/`, `helm/` |
206
+ | `lockfile` | 3 | `package-lock.json`, `yarn.lock`, `poetry.lock`, `go.sum`, … |
207
+ | `large-change` | 0–10 | +1 for every 25 changed lines in the hunk (not for lockfiles) |
208
+
209
+ ## 📦 Package check
210
+
211
+ AI models invent package names, and attackers register those names on npm and PyPI to catch anyone who installs them ("slopsquatting"). Agents also add a new library instead of using the one already in the project.
212
+
213
+ Two checks always run, offline:
214
+
215
+ - **`package-lookalike`**: the name is one or two edits away from a popular package.
216
+ - **`duplicate-dependency`**: the new library does the same job as one already in the manifest (HTTP clients, date libraries, test runners, validators, loggers, ORMs, and more).
217
+
218
+ Add `--check-packages` (or `"checkPackages": true` in the config) to also look each new npm and PyPI dependency up in its registry:
219
+
220
+ | Rule | Weight | Flags a dependency that… |
221
+ |---|---:|---|
222
+ | `package-not-found` | 50 | doesn't exist in the registry (hallucinated, or a private package) |
223
+ | `package-new` | 30 | was first published in the last 30 days |
224
+ | `package-low-downloads` | 15 | had fewer than 500 npm downloads last week |
225
+ | `package-deprecated` | 15 | is deprecated on npm or yanked on PyPI |
226
+
227
+ ```text
228
+ HIGH 110 requirements.txt:1
229
+ • reqeusts does not exist on PyPI; possibly a hallucinated name [package-not-found +50]
230
+ • reqeusts looks like requests; check it is the package you meant [package-lookalike +30]
231
+ • Adds or changes a dependency [new-dependency +15]
232
+ • Adds requests and httpx, which do the same job (HTTP client) [duplicate-dependency +15]
233
+ ```
234
+
235
+ The check only sends package **names** to `registry.npmjs.org`, `api.npmjs.org`, and `pypi.org`. No code leaves your machine. If a registry can't be reached, riskdiff prints a warning on stderr and scores the rest as usual.
236
+
237
+ For a private package that riskdiff reports as not found, turn the rule off in `.riskdiff.json` or add a `"//": "riskdiff-ignore package-not-found"` line next to it.
238
+
239
+ ## ✦ AI second opinion
240
+
241
+ Regex rules are fast, but they can't tell `eval(trustedConstant)` from `eval(req.body.code)`. `--ai` sends the riskiest hunks (up to 15, at most 40 lines each, with their findings) to Claude and asks for one verdict per hunk:
242
+
243
+ ```text
244
+ HIGH 55 src/run.js:12
245
+ • Runs dynamic code or shell commands [dangerous-exec +30]
246
+ • SQL built from string concatenation or interpolation [sql-injection +25]
247
+ AI: likely real — the query interpolates req.query.id straight into SQL.
248
+
249
+ MEDIUM 30 scripts/build.js:3
250
+ • Runs dynamic code or shell commands [dangerous-exec +30]
251
+ AI: likely false positive — execSync runs a fixed "npm run build" string.
252
+ ```
253
+
254
+ ```bash
255
+ export ANTHROPIC_API_KEY=sk-ant-...
256
+ riskdiff --ai
257
+ RISKDIFF_AI_MODEL=claude-haiku-5-5 riskdiff --ai # pick another model
258
+ ```
259
+
260
+ - **Off unless you pass `--ai`.** Without it nothing leaves your machine.
261
+ - **Scores and `--fail-on` don't change.** The verdict is an annotation (`ai` in JSON, a 🤖 line in Markdown), so CI gates stay deterministic.
262
+ - Uses `claude-opus-5-5` at low effort by default. Any API problem (no key, rate limit, network) prints a warning and the report still comes out.
263
+
264
+ ## 🧮 How scoring works
265
+
266
+ 1. The diff is split into **hunks** (the `@@ … @@` blocks).
267
+ 2. Each rule is checked against the hunk's file path, added lines, and removed lines. A rule counts **once per hunk**.
268
+ 3. The hunk's **score** is the sum of the weights that matched, plus the size bonus.
269
+ 4. The score maps to a **level**:
270
+
271
+ | Level | Score |
272
+ |---|---|
273
+ | 🔴 **High** | 50+ |
274
+ | 🟠 **Medium** | 25–49 |
275
+ | 🔵 **Low** | 1–24 |
276
+ | ⚪ None | 0 (hidden) |
277
+
278
+ Rules stack. One removed auth check is already **high**. A new SQL string (`25`) in `src/auth/login.js` (`+25`) is also **high**, because the same mistake matters more in auth code.
279
+
280
+ Removal rules compare counts: if a hunk removes one `try` and adds one back, nothing was removed. Deleted files are handled by `test-file-deleted` only, so deleting dead code doesn't set off every removal rule.
281
+
282
+ ## 🔌 Integrations
283
+
284
+ ### 🤖 Claude Code plugin
285
+
286
+ This repo is a Claude Code plugin marketplace. Install it once:
287
+
288
+ ```text
289
+ /plugin marketplace add zeitgeistz/riskdiff
290
+ /plugin install riskdiff@riskdiff
291
+ ```
292
+
293
+ On Claude Code 2.1.275 or later, one line does both: `/plugin install riskdiff --marketplace zeitgeistz/riskdiff`.
294
+
295
+ You get three things:
296
+
297
+ | Part | What it does |
298
+ |---|---|
299
+ | **Hook** | After every `Edit` or `Write`, scans that file's uncommitted changes. If a hunk is medium or high risk, Claude sees the findings right away and either fixes them or explains why they're safe. Safe edits add nothing to the conversation. It never blocks an edit. |
300
+ | **MCP tool** `riskdiff_scan` | Claude can scan any range on demand (`range`, `staged`, `checkPackages`, `minLevel`, `cwd`) and gets JSON back. |
301
+ | **Skill** `/zeit-riskdiff` | Runs a full review: riskiest hunks first, with Claude explaining each one. |
302
+
303
+ Everything runs locally with the plugin's own copy of riskdiff, so only Node.js is needed.
304
+
305
+ <details>
306
+ <summary><b>Without the plugin</b></summary>
307
+
308
+ Use the hook on its own by adding this to `.claude/settings.json` (riskdiff installed globally):
309
+
310
+ ```json
311
+ {
312
+ "hooks": {
313
+ "PostToolUse": [
314
+ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "riskdiff hook", "timeout": 30 }] }
315
+ ]
316
+ }
317
+ }
318
+ ```
319
+
320
+ Add the MCP server to any MCP client:
321
+
322
+ ```bash
323
+ claude mcp add riskdiff -- npx -y github:zeitgeistz/riskdiff#v2.0.0 mcp
324
+ ```
325
+
326
+ Or copy just the skill:
327
+
328
+ ```bash
329
+ # macOS / Linux
330
+ cp -r skills/zeit-riskdiff ~/.claude/skills/
331
+
332
+ # Windows (PowerShell)
333
+ Copy-Item -Recurse skills\zeit-riskdiff $HOME\.claude\skills\
334
+ ```
335
+
336
+ Then type `/zeit-riskdiff` in Claude Code, or ask *"what's risky in this change?"*.
337
+
338
+ </details>
339
+
340
+ ### 🪝 Git pre-commit hook
341
+
342
+ Block commits that contain high-risk changes:
343
+
344
+ ```bash
345
+ cat > .git/hooks/pre-commit <<'EOF'
346
+ #!/bin/sh
347
+ npx -y github:zeitgeistz/riskdiff#v2.0.0 --staged --fail-on high
348
+ EOF
349
+ chmod +x .git/hooks/pre-commit
350
+ ```
351
+
352
+ Use `git commit --no-verify` to bypass it when you've reviewed the change.
353
+
354
+ ### ⚙️ GitHub Action
355
+
356
+ Comments a risk table on every pull request (and keeps updating the same comment), writes it to the job summary, and fails the check on high-risk changes:
357
+
358
+ ```yaml
359
+ name: riskdiff
360
+ on: pull_request
361
+
362
+ permissions:
363
+ contents: read
364
+ pull-requests: write
365
+
366
+ jobs:
367
+ riskdiff:
368
+ runs-on: ubuntu-latest
369
+ steps:
370
+ - uses: actions/checkout@v4
371
+ with:
372
+ fetch-depth: 0
373
+ - uses: actions/setup-node@v4
374
+ with:
375
+ node-version: 22
376
+ - uses: zeitgeistz/riskdiff@v1
377
+ with:
378
+ fail-on: high
379
+ check-packages: true
380
+ ```
381
+
382
+ | Input | Default | Description |
383
+ |---|---|---|
384
+ | `base` | PR base branch | Ref to compare against. On `push` events the default is the previous commit. |
385
+ | `fail-on` | `high` | Fail if any hunk is at or above `low`, `medium`, or `high`. `''` never fails. |
386
+ | `comment` | `true` | Post or update a PR comment. Skipped quietly on fork PRs with read-only tokens. |
387
+ | `check-packages` | `false` | Run the [registry check](#-package-check). |
388
+ | `sarif` | `false` | Also write a SARIF file (see below). |
389
+ | `github-token` | `github.token` | Token for the PR comment. |
390
+
391
+ Outputs: `high`, `medium`, `low` (counts), `report` (Markdown path), and `sarif-file`.
392
+
393
+ #### Code scanning (SARIF)
394
+
395
+ Show findings as annotations on the PR diff and in the repo's **Security → Code scanning** tab:
396
+
397
+ ```yaml
398
+ permissions:
399
+ contents: read
400
+ pull-requests: write
401
+ security-events: write
402
+ steps:
403
+ # ...checkout and setup-node as above
404
+ - id: riskdiff
405
+ uses: zeitgeistz/riskdiff@v1
406
+ with:
407
+ sarif: true
408
+ - uses: github/codeql-action/upload-sarif@v3
409
+ if: always()
410
+ with:
411
+ sarif_file: ${{ steps.riskdiff.outputs.sarif-file }}
412
+ ```
413
+
414
+ Locally, `riskdiff --sarif -o riskdiff.sarif` writes the same file.
415
+
416
+ ## 🧾 JSON output
417
+
418
+ `riskdiff --json` prints a summary plus every hunk, riskiest first:
419
+
420
+ ```json
421
+ {
422
+ "summary": { "files": 5, "hunks": 5, "high": 1, "medium": 2, "low": 1, "none": 1 },
423
+ "hunks": [
424
+ {
425
+ "file": "src/routes/admin.js",
426
+ "status": "modified",
427
+ "line": 2,
428
+ "context": "",
429
+ "added": 0,
430
+ "removed": 1,
431
+ "score": 50,
432
+ "level": "high",
433
+ "findings": [
434
+ { "id": "auth-check-removed", "weight": 50, "reason": "Removes an authentication or permission check" }
435
+ ]
436
+ }
437
+ ]
438
+ }
439
+ ```
440
+
441
+ `status` is `modified`, `added`, `deleted`, or `renamed`. `line` is the first changed line in the new file. `context` is the function name git prints in the hunk header, when there is one. With `--ai`, reviewed hunks also carry `"ai": { "verdict": "real" | "false-positive" | "unsure", "note": "..." }`.
442
+
443
+ ## ❓ FAQ
444
+
445
+ <details>
446
+ <summary><b>Is this a security scanner?</b></summary>
447
+
448
+ No. It's a **triage** tool built on fast regex heuristics. It will miss things and flag some false positives. Use it to decide what to read first, and keep using real tools (Semgrep, CodeQL, Snyk, secret scanners) for security.
449
+ </details>
450
+
451
+ <details>
452
+ <summary><b>Does it send my code anywhere?</b></summary>
453
+
454
+ Not by default. It runs locally and the scoring uses no AI model. There are two opt-in network calls: `--check-packages` sends package names (never code) to npm and PyPI, and `--ai` sends the changed lines of up to 15 flagged hunks to the Anthropic API. The Claude Code hook and MCP tool never use `--ai`.
455
+ </details>
456
+
457
+ <details>
458
+ <summary><b>Which languages does it support?</b></summary>
459
+
460
+ Rules are text-based, so any language works. Patterns are tuned for JavaScript/TypeScript, Python, Go, Java/Kotlin, Ruby, PHP, and SQL.
461
+ </details>
462
+
463
+ <details>
464
+ <summary><b>Why is a hunk scored 0 even though it's important?</b></summary>
465
+
466
+ No rule matched it. riskdiff only knows the patterns in the tables above, so "no findings" never means "safe". If a pattern keeps biting you, open an issue or a PR with a rule and a test.
467
+ </details>
468
+
469
+ <details>
470
+ <summary><b>Can I add my own rules or change weights?</b></summary>
471
+
472
+ Yes. Use `rules` and `customRules` in [`.riskdiff.json`](#%EF%B8%8F-configuration). Built-in rules live in [`src/rules.js`](src/rules.js) if you want to contribute one.
473
+ </details>
474
+
475
+ ## 🛠️ Development
476
+
477
+ ```bash
478
+ git clone https://github.com/zeitgeistz/riskdiff.git
479
+ cd riskdiff
480
+ npm test # node --test, no install needed
481
+ node bin/riskdiff.js --help
482
+ ```
483
+
484
+ ```text
485
+ bin/riskdiff.js CLI: argument parsing, output, exit codes
486
+ src/analyze.js The pipeline: config → git diff → parse → score
487
+ src/git.js Reading diffs, untracked files, and new file contents from git
488
+ src/diff.js Unified diff parser → files and hunks
489
+ src/source.js Comment stripping and riskdiff-ignore directives
490
+ src/deps.js Finds the dependencies a manifest hunk adds
491
+ src/packages.js Look-alike, duplicate, and registry checks for new dependencies
492
+ src/popular.js Popular package names and libraries that do the same job
493
+ src/rules.js Built-in risk rules and weights
494
+ src/config.js .riskdiff.json loading, validation, globs
495
+ src/score.js Scores and sorts hunks, maps scores to levels
496
+ src/report.js Text, Markdown, JSON, and SARIF output
497
+ src/hook.js Claude Code PostToolUse hook
498
+ src/mcp.js MCP server (stdio JSON-RPC)
499
+ src/ai.js Optional --ai second opinion (Anthropic API, plain fetch)
500
+ schema/ JSON schema for .riskdiff.json
501
+ .claude-plugin/ Plugin and marketplace manifests
502
+ hooks/ Plugin hook config
503
+ skills/ Claude Code skill
504
+ test/ Tests (node:test)
505
+ ```
506
+
507
+ ### Adding a rule
508
+
509
+ 1. Add an object to `rules` in `src/rules.js` with `id`, `weight`, `reason`, and one of `path`, `added`, `removed`, or `match`.
510
+ 2. Add a test in `test/riskdiff.test.js` that proves it fires, plus one that proves it doesn't fire on a similar safe line.
511
+ 3. Add it to the tables in this README.
512
+
513
+ ## 🗺️ Roadmap
514
+
515
+ - [x] **Package check:** missing, brand-new, look-alike, and duplicate dependencies (v1.2)
516
+ - [x] Config file for custom rules, weights, and ignored paths (v1.1)
517
+ - [x] Include untracked files (v1.1)
518
+ - [x] Ignore comments, and `riskdiff-ignore` directives (v1.1)
519
+ - [x] GitHub Action with PR comments, job summary, and a gate (v1.3)
520
+ - [x] SARIF output for code scanning (v1.3)
521
+ - [x] Claude Code plugin: hook, MCP server, skill (v2.0)
522
+ - [x] Optional AI second opinion with `--ai` (v2.0)
523
+ - [ ] Published to npm as `riskdiff-cli` (the release workflow is ready; it publishes once an `NPM_TOKEN` secret is added)
524
+
525
+ ## 📄 License
526
+
527
+ [MIT](LICENSE)