@alimaandev/ripple 0.7.0 → 0.7.2
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/README.md +114 -51
- package/dist/bin.d.ts +1 -1
- package/dist/bin.js +390 -189
- package/dist/bin.js.map +1 -1
- package/dist/{chunk-CFH4UW2E.js → chunk-VSLCAPAH.js} +3 -3
- package/dist/chunk-VSLCAPAH.js.map +1 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -1
- package/package.json +12 -3
- package/ripple.schema.json +2 -2
- package/dist/chunk-CFH4UW2E.js.map +0 -1
package/README.md
CHANGED
|
@@ -4,21 +4,34 @@
|
|
|
4
4
|
|
|
5
5
|
# Ripple
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**The CI gate that knows the blast radius.**
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Your AI agent's PR passed tests and still broke 37 routes. Ripple scores every
|
|
10
|
+
changed file by what depends on it, then blocks the merge before that blast
|
|
11
|
+
radius ships.
|
|
10
12
|
|
|
11
13
|
<p align="center">
|
|
12
14
|
<a href="https://www.npmjs.com/package/@alimaandev/ripple"><img alt="npm version" src="https://img.shields.io/npm/v/@alimaandev/ripple?logo=npm&logoColor=white&label=npm&style=for-the-badge"/></a>
|
|
13
15
|
<a href="https://www.npmjs.com/package/@alimaandev/ripple"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@alimaandev/ripple?label=downloads&style=for-the-badge"/></a>
|
|
16
|
+
<a href="https://github.com/marketplace?query=ripple"><img alt="GitHub Action" src="https://img.shields.io/badge/GitHub%20Actions-ripple--action-2088FF?logo=githubactions&logoColor=white&style=for-the-badge"/></a>
|
|
14
17
|
<a href="https://github.com/alimaandev/ripple/actions/workflows/ci.yml"><img alt="CI build" src="https://img.shields.io/github/actions/workflow/status/alimaandev/ripple/ci.yml?branch=main&logo=githubactions&logoColor=white&label=CI%20build&style=for-the-badge"/></a>
|
|
15
18
|
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/alimaandev/ripple?label=License&style=for-the-badge"/></a>
|
|
16
19
|
<a href="package.json"><img alt="Node.js >= 22" src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=nodedotjs&logoColor=white&style=for-the-badge"/></a>
|
|
17
20
|
</p>
|
|
18
21
|
|
|
19
|
-
<
|
|
22
|
+
<p align="center">
|
|
23
|
+
<a href="https://github.com/alimaandev/ripple-action"><strong>Add the gate to your pull requests →</strong></a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<pre><code># .github/workflows/ripple.yml
|
|
27
|
+
- uses: actions/checkout@v5
|
|
28
|
+
with:
|
|
29
|
+
fetch-depth: 0
|
|
30
|
+
- uses: alimaandev/ripple-action@v1</code></pre>
|
|
31
|
+
|
|
32
|
+
<p align="center"><sub>No token. No config. Fails the job when a changed file crosses your gate.</sub></p>
|
|
20
33
|
|
|
21
|
-
|
|
34
|
+
<pre><code># or run it locally
|
|
22
35
|
npx @alimaandev/ripple analyze src/your-file.ts</code></pre>
|
|
23
36
|
|
|
24
37
|
<img src="https://raw.githubusercontent.com/alimaandev/ripple/main/assets/hero-animated.svg" alt="Animated terminal demo of `ripple analyze` — command types in, then the report builds up: risk score with gauge, affected files, routes, components, tests, and confidence" title="ripple analyze" width="100%" />
|
|
@@ -27,6 +40,13 @@ npx @alimaandev/ripple analyze src/your-file.ts</code></pre>
|
|
|
27
40
|
|
|
28
41
|
## Why Ripple
|
|
29
42
|
|
|
43
|
+
### AI writes PRs faster than you can review them
|
|
44
|
+
|
|
45
|
+
AI agents produce plausible code at machine speed. Tests can still pass while a
|
|
46
|
+
change quietly reaches dozens of routes, shared utilities and tests. Ripple
|
|
47
|
+
makes that blast radius explicit before the merge, so you review the risk — not
|
|
48
|
+
just the diff.
|
|
49
|
+
|
|
30
50
|
### The question your tooling doesn't answer
|
|
31
51
|
|
|
32
52
|
In any non-trivial codebase, there is a deceptively simple question:
|
|
@@ -100,7 +120,7 @@ Everything below is real output against a shipped example project in `tests/fixt
|
|
|
100
120
|
```bash
|
|
101
121
|
npm install -g @alimaandev/ripple
|
|
102
122
|
|
|
103
|
-
ripple version # → 0.7.
|
|
123
|
+
ripple version # → 0.7.2
|
|
104
124
|
```
|
|
105
125
|
|
|
106
126
|
Or install from source:
|
|
@@ -132,7 +152,7 @@ ripple analyze src/authentication/login.ts
|
|
|
132
152
|
Expected output:
|
|
133
153
|
|
|
134
154
|
```text
|
|
135
|
-
ripple · impact analysis · v0.7.
|
|
155
|
+
ripple · impact analysis · v0.7.2
|
|
136
156
|
|
|
137
157
|
File src/authentication/login.ts
|
|
138
158
|
Risk MEDIUM · 34.7/100 ███░░░░░░░
|
|
@@ -165,7 +185,7 @@ ripple graph
|
|
|
165
185
|
```
|
|
166
186
|
|
|
167
187
|
```text
|
|
168
|
-
ripple · dependency graph · v0.7.
|
|
188
|
+
ripple · dependency graph · v0.7.2
|
|
169
189
|
|
|
170
190
|
Files 25
|
|
171
191
|
Edges 28
|
|
@@ -216,30 +236,30 @@ ripple <command> [options]
|
|
|
216
236
|
|
|
217
237
|
### Options
|
|
218
238
|
|
|
219
|
-
| Command | Flag | Description
|
|
220
|
-
| --------- | --------------------- |
|
|
221
|
-
| `analyze` | `-j, --json` | Emit the JSON report instead of the terminal report
|
|
222
|
-
| `analyze` | `--sarif` | Emit a SARIF 2.1.0 report for code scanning
|
|
223
|
-
| `analyze` | `-v, --verbose` | Include the risk-factor point breakdown
|
|
224
|
-
| `analyze` | `-d, --depth <n>` | Cap the reverse traversal at `n` levels
|
|
225
|
-
| `analyze` | `-c, --config <path>` | Use a specific config file
|
|
226
|
-
| `analyze` | `--no-color` | Disable ANSI colors
|
|
227
|
-
| `graph` | `-j, --json` | Emit the JSON report
|
|
228
|
-
| `graph` | `-r, --reverse` | Show dependents (what imports this file) instead of dependencies
|
|
229
|
-
| `graph` | `-d, --depth <n>` | Cap tree depth
|
|
230
|
-
| `graph` | `-c, --config <path>` | Use a specific config file
|
|
231
|
-
| `graph` | `--no-color` | Disable ANSI colors
|
|
232
|
-
| `doctor` | `-c, --config <path>` | Use a specific config file
|
|
233
|
-
| `doctor` | `-v, --verbose` | Verbose output
|
|
234
|
-
| `doctor` | `--no-color` | Disable ANSI colors
|
|
235
|
-
| `init` | `-f, --force` | Overwrite an existing config
|
|
236
|
-
| `diff` | `-j, --json` | Emit the JSON report instead of the terminal report
|
|
237
|
-
| `diff` | `-b, --base <ref>` | Git ref to diff against (default: `origin/main`, `main`, `
|
|
238
|
-
| `diff` | `-g, --gate <level>` | Blocking level: `medium`, `high`, or `critical` (default: `high`, or `diff.gate` from config)
|
|
239
|
-
| `diff` | `-f, --format <fmt>` | Output: `terminal`, `json`, `github` (workflow annotations), or `sarif`
|
|
240
|
-
| `diff` | `-d, --depth <n>` | Cap reverse traversal per file
|
|
241
|
-
| `diff` | `-c, --config <path>` | Use a specific config file
|
|
242
|
-
| `diff` | `--no-color` | Disable ANSI colors
|
|
239
|
+
| Command | Flag | Description |
|
|
240
|
+
| --------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `analyze` | `-j, --json` | Emit the JSON report instead of the terminal report |
|
|
242
|
+
| `analyze` | `--sarif` | Emit a SARIF 2.1.0 report for code scanning |
|
|
243
|
+
| `analyze` | `-v, --verbose` | Include the risk-factor point breakdown |
|
|
244
|
+
| `analyze` | `-d, --depth <n>` | Cap the reverse traversal at `n` levels |
|
|
245
|
+
| `analyze` | `-c, --config <path>` | Use a specific config file |
|
|
246
|
+
| `analyze` | `--no-color` | Disable ANSI colors |
|
|
247
|
+
| `graph` | `-j, --json` | Emit the JSON report |
|
|
248
|
+
| `graph` | `-r, --reverse` | Show dependents (what imports this file) instead of dependencies |
|
|
249
|
+
| `graph` | `-d, --depth <n>` | Cap tree depth |
|
|
250
|
+
| `graph` | `-c, --config <path>` | Use a specific config file |
|
|
251
|
+
| `graph` | `--no-color` | Disable ANSI colors |
|
|
252
|
+
| `doctor` | `-c, --config <path>` | Use a specific config file |
|
|
253
|
+
| `doctor` | `-v, --verbose` | Verbose output |
|
|
254
|
+
| `doctor` | `--no-color` | Disable ANSI colors |
|
|
255
|
+
| `init` | `-f, --force` | Overwrite an existing config |
|
|
256
|
+
| `diff` | `-j, --json` | Emit the JSON report instead of the terminal report |
|
|
257
|
+
| `diff` | `-b, --base <ref>` | Git ref to diff against (default: GitHub PR base, `origin/HEAD`, `origin/main`, `origin/master`, `main`, `master`, or `diff.base`) |
|
|
258
|
+
| `diff` | `-g, --gate <level>` | Blocking level: `medium`, `high`, or `critical` (default: `high`, or `diff.gate` from config) |
|
|
259
|
+
| `diff` | `-f, --format <fmt>` | Output: `terminal`, `json`, `github` (workflow annotations), or `sarif` |
|
|
260
|
+
| `diff` | `-d, --depth <n>` | Cap reverse traversal per file |
|
|
261
|
+
| `diff` | `-c, --config <path>` | Use a specific config file |
|
|
262
|
+
| `diff` | `--no-color` | Disable ANSI colors |
|
|
243
263
|
|
|
244
264
|
### `ripple mcp`
|
|
245
265
|
|
|
@@ -292,7 +312,7 @@ files are included; deleted files and non-source changes are skipped.
|
|
|
292
312
|
|
|
293
313
|
```bash
|
|
294
314
|
cd my-project
|
|
295
|
-
ripple diff # vs
|
|
315
|
+
ripple diff # vs the PR base or origin/main
|
|
296
316
|
ripple diff --base HEAD~1 --json # machine-readable gate report
|
|
297
317
|
ripple diff --gate critical # only CRITICAL blocks the merge
|
|
298
318
|
ripple diff --allow "src/legacy/**" # legacy files never block the gate
|
|
@@ -398,8 +418,8 @@ defaults — every field is optional.
|
|
|
398
418
|
|
|
399
419
|
```json
|
|
400
420
|
{
|
|
401
|
-
"$schema": "
|
|
402
|
-
"include": ["**/*.{ts,tsx,js,jsx}"],
|
|
421
|
+
"$schema": "https://raw.githubusercontent.com/alimaandev/ripple/main/ripple.schema.json",
|
|
422
|
+
"include": ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"],
|
|
403
423
|
"ignore": ["node_modules", "dist", "build", "coverage", ".next", "out"],
|
|
404
424
|
"aliases": { "@": "./src" },
|
|
405
425
|
"tsconfigPath": "tsconfig.json",
|
|
@@ -425,19 +445,20 @@ defaults — every field is optional.
|
|
|
425
445
|
|
|
426
446
|
> [!TIP]
|
|
427
447
|
> The `$schema` line powers editor autocomplete and validation for
|
|
428
|
-
> `ripple.config.json`
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
|
432
|
-
|
|
|
433
|
-
| `
|
|
434
|
-
| `
|
|
435
|
-
| `
|
|
436
|
-
| `
|
|
437
|
-
| `risk.
|
|
438
|
-
| `
|
|
439
|
-
| `diff.
|
|
440
|
-
| `diff.
|
|
448
|
+
> `ripple.config.json`. `ripple init` writes the hosted schema URL; the
|
|
449
|
+
> package also ships `ripple.schema.json` if you prefer a local path.
|
|
450
|
+
|
|
451
|
+
| Field | Default | Purpose |
|
|
452
|
+
| ----------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
|
|
453
|
+
| `include` | `**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}` | Source globs to analyze |
|
|
454
|
+
| `ignore` | `node_modules`, `dist`, `build`, `coverage`, `.next`, `out` | Exclusions |
|
|
455
|
+
| `aliases` | `{}` | Path aliases, merged with tsconfig `paths` (user wins) |
|
|
456
|
+
| `tsconfigPath` | `tsconfig.json` | tsconfig to read for `paths` |
|
|
457
|
+
| `risk.weights` | see example | Risk signal weights |
|
|
458
|
+
| `risk.thresholds` | 30 / 55 / 80 | Score thresholds for MEDIUM / HIGH / CRITICAL |
|
|
459
|
+
| `diff.base` | GitHub PR base → `origin/HEAD` → `origin/main` → `origin/master` → `main` → `master` | Git ref to diff against when `--base` is not given |
|
|
460
|
+
| `diff.allow` | `[]` | Project-relative globs of files that never block the gate |
|
|
461
|
+
| `diff.gate` | `high` | Blocking level when `--gate` is not given |
|
|
441
462
|
|
|
442
463
|
`node_modules` is always excluded, regardless of config.
|
|
443
464
|
|
|
@@ -550,7 +571,7 @@ verdict:
|
|
|
550
571
|
```json
|
|
551
572
|
{
|
|
552
573
|
"tool": "ripple",
|
|
553
|
-
"version": "0.
|
|
574
|
+
"version": "0.7.2",
|
|
554
575
|
"command": "diff",
|
|
555
576
|
"base": "origin/main",
|
|
556
577
|
"changedFiles": 2,
|
|
@@ -560,22 +581,53 @@ verdict:
|
|
|
560
581
|
"analyzed": true,
|
|
561
582
|
"risk": { "score": 88.2, "level": "CRITICAL", "factors": [] },
|
|
562
583
|
"affectedFiles": 14,
|
|
563
|
-
"targetInCycle": false
|
|
584
|
+
"targetInCycle": false,
|
|
585
|
+
"allowed": false
|
|
564
586
|
},
|
|
565
587
|
{ "file": "src/api/legacy.js", "analyzed": false }
|
|
566
588
|
],
|
|
567
589
|
"gate": {
|
|
568
590
|
"level": "high",
|
|
569
591
|
"blocked": true,
|
|
570
|
-
"counts": { "low": 0, "medium": 0, "high": 0, "critical": 1 }
|
|
592
|
+
"counts": { "low": 0, "medium": 0, "high": 0, "critical": 1 },
|
|
593
|
+
"allowed": 0
|
|
571
594
|
},
|
|
572
595
|
"durationMs": 118
|
|
573
596
|
}
|
|
574
597
|
```
|
|
575
598
|
|
|
576
599
|
`blocked` tells CI everything: exit code `1` if `true`, `0` otherwise.
|
|
600
|
+
`files[].file` is project-relative (relative to the directory containing your
|
|
601
|
+
Ripple config); SARIF and GitHub annotations use repository-relative paths so
|
|
602
|
+
Code Scanning and PR annotations land on the right file in a monorepo.
|
|
603
|
+
|
|
604
|
+
### GitHub Action
|
|
605
|
+
|
|
606
|
+
The one-line gate for pull requests:
|
|
577
607
|
|
|
578
|
-
|
|
608
|
+
```yaml
|
|
609
|
+
name: Ripple
|
|
610
|
+
on: pull_request
|
|
611
|
+
|
|
612
|
+
jobs:
|
|
613
|
+
ripple:
|
|
614
|
+
runs-on: ubuntu-latest
|
|
615
|
+
permissions:
|
|
616
|
+
contents: read
|
|
617
|
+
steps:
|
|
618
|
+
- uses: actions/checkout@v5
|
|
619
|
+
with:
|
|
620
|
+
fetch-depth: 0
|
|
621
|
+
- uses: alimaandev/ripple-action@v1
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
It fails the job when a changed file crosses the gate, annotates the PR Files
|
|
625
|
+
tab, writes a job summary, and emits `ripple.sarif` for Code Scanning. Use
|
|
626
|
+
`working-directory: packages/app` in a monorepo, and `gate: critical` to tune
|
|
627
|
+
the threshold. See the [action docs](https://github.com/alimaandev/ripple-action)
|
|
628
|
+
for inputs, outputs and the SARIF upload step.
|
|
629
|
+
|
|
630
|
+
### Raw JSON in any CI
|
|
579
631
|
|
|
580
632
|
```bash
|
|
581
633
|
ripple analyze src/authentication/login.ts --json | jq -r .risk.level
|
|
@@ -667,6 +719,17 @@ and Windows, and a dogfood job — Ripple gates its own PRs with
|
|
|
667
719
|
|
|
668
720
|
## Get started
|
|
669
721
|
|
|
722
|
+
Gate your next pull request:
|
|
723
|
+
|
|
724
|
+
```yaml
|
|
725
|
+
- uses: actions/checkout@v5
|
|
726
|
+
with:
|
|
727
|
+
fetch-depth: 0
|
|
728
|
+
- uses: alimaandev/ripple-action@v1
|
|
729
|
+
```
|
|
730
|
+
|
|
731
|
+
Or run it locally:
|
|
732
|
+
|
|
670
733
|
```bash
|
|
671
734
|
npm install -g @alimaandev/ripple
|
|
672
735
|
ripple analyze src/your-file.ts --json | jq -r .risk.level # MEDIUM, HIGH, ...
|
package/dist/bin.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
|
|
2
|
-
export {
|
|
2
|
+
export { };
|