@alimaandev/ripple 0.6.0 → 0.7.1
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 +109 -46
- package/dist/bin.d.ts +1 -1
- package/dist/bin.js +1184 -151
- 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 +3 -2
- package/ripple.schema.json +2 -2
- package/dist/chunk-CFH4UW2E.js.map +0 -1
package/README.md
CHANGED
|
@@ -21,7 +21,7 @@ Change less. Break less. Know the blast radius of any file before you touch it.
|
|
|
21
21
|
# or try it without installing anything:
|
|
22
22
|
npx @alimaandev/ripple analyze src/your-file.ts</code></pre>
|
|
23
23
|
|
|
24
|
-
<img src="https://raw.githubusercontent.com/alimaandev/ripple/main/assets/hero.svg" alt="
|
|
24
|
+
<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%" />
|
|
25
25
|
|
|
26
26
|
</div>
|
|
27
27
|
|
|
@@ -100,7 +100,7 @@ Everything below is real output against a shipped example project in `tests/fixt
|
|
|
100
100
|
```bash
|
|
101
101
|
npm install -g @alimaandev/ripple
|
|
102
102
|
|
|
103
|
-
ripple version # → 0.
|
|
103
|
+
ripple version # → 0.7.1
|
|
104
104
|
```
|
|
105
105
|
|
|
106
106
|
Or install from source:
|
|
@@ -132,7 +132,7 @@ ripple analyze src/authentication/login.ts
|
|
|
132
132
|
Expected output:
|
|
133
133
|
|
|
134
134
|
```text
|
|
135
|
-
ripple · impact analysis · v0.
|
|
135
|
+
ripple · impact analysis · v0.7.1
|
|
136
136
|
|
|
137
137
|
File src/authentication/login.ts
|
|
138
138
|
Risk MEDIUM · 34.7/100 ███░░░░░░░
|
|
@@ -165,7 +165,7 @@ ripple graph
|
|
|
165
165
|
```
|
|
166
166
|
|
|
167
167
|
```text
|
|
168
|
-
ripple · dependency graph · v0.
|
|
168
|
+
ripple · dependency graph · v0.7.1
|
|
169
169
|
|
|
170
170
|
Files 25
|
|
171
171
|
Edges 28
|
|
@@ -216,29 +216,35 @@ ripple <command> [options]
|
|
|
216
216
|
|
|
217
217
|
### Options
|
|
218
218
|
|
|
219
|
-
| Command | Flag | Description
|
|
220
|
-
| --------- | --------------------- |
|
|
221
|
-
| `analyze` | `-j, --json` | Emit the JSON report instead of the terminal report
|
|
222
|
-
| `analyze` |
|
|
223
|
-
| `analyze` | `-
|
|
224
|
-
| `analyze` | `-
|
|
225
|
-
| `analyze` |
|
|
226
|
-
| `
|
|
227
|
-
| `graph` | `-
|
|
228
|
-
| `graph` | `-
|
|
229
|
-
| `graph` | `-
|
|
230
|
-
| `graph` |
|
|
231
|
-
| `
|
|
232
|
-
| `doctor` | `-
|
|
233
|
-
| `doctor` |
|
|
234
|
-
| `
|
|
235
|
-
| `
|
|
236
|
-
| `diff` | `-
|
|
237
|
-
| `diff` | `-
|
|
238
|
-
| `diff` | `-
|
|
239
|
-
| `diff` | `-
|
|
240
|
-
| `diff` | `-
|
|
241
|
-
| `diff` |
|
|
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: GitHub PR base, `origin/HEAD`, `origin/main`, `origin/master`, `main`, `master`, or `diff.base`) |
|
|
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 |
|
|
243
|
+
|
|
244
|
+
### `ripple mcp`
|
|
245
|
+
|
|
246
|
+
Serve Ripple's analysis tools over the Model Context Protocol (see
|
|
247
|
+
[the MCP section](#ripple-mcp-1) below).
|
|
242
248
|
|
|
243
249
|
### `ripple doctor`
|
|
244
250
|
|
|
@@ -286,7 +292,7 @@ files are included; deleted files and non-source changes are skipped.
|
|
|
286
292
|
|
|
287
293
|
```bash
|
|
288
294
|
cd my-project
|
|
289
|
-
ripple diff # vs
|
|
295
|
+
ripple diff # vs the PR base or origin/main
|
|
290
296
|
ripple diff --base HEAD~1 --json # machine-readable gate report
|
|
291
297
|
ripple diff --gate critical # only CRITICAL blocks the merge
|
|
292
298
|
ripple diff --allow "src/legacy/**" # legacy files never block the gate
|
|
@@ -333,6 +339,57 @@ verdict, so the job fails when the gate blocks:
|
|
|
333
339
|
(`--json` is shorthand for `--format json`; the format flag also accepts
|
|
334
340
|
`terminal`, the default.)
|
|
335
341
|
|
|
342
|
+
`--format sarif` emits SARIF 2.1.0, the format GitHub Code Scanning speaks:
|
|
343
|
+
|
|
344
|
+
```bash
|
|
345
|
+
ripple diff --format sarif > ripple.sarif
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Each analyzed change becomes a finding on the file — `error` when it is
|
|
349
|
+
CRITICAL/HIGH, `warning` for MEDIUM, `note` for LOW — with a stable
|
|
350
|
+
`primaryLocationLineHash` fingerprint so results deduplicate across runs.
|
|
351
|
+
Allowlisted files are emitted as `note` with an in-source suppression, so
|
|
352
|
+
they show as exempted rather than failing. Upload the report straight into
|
|
353
|
+
Code Scanning alerts:
|
|
354
|
+
|
|
355
|
+
```yaml
|
|
356
|
+
- uses: actions/upload-sarif@v3
|
|
357
|
+
with:
|
|
358
|
+
sarif_file: ripple.sarif
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
The exit code still carries the gate verdict regardless of format.
|
|
362
|
+
|
|
363
|
+
### `ripple mcp`
|
|
364
|
+
|
|
365
|
+
`ripple mcp` exposes Ripple's analysis to AI coding agents as a Model
|
|
366
|
+
Context Protocol server over stdio. Point any MCP client at the command and
|
|
367
|
+
the agent can check a file's blast radius before touching it:
|
|
368
|
+
|
|
369
|
+
```json
|
|
370
|
+
{
|
|
371
|
+
"mcpServers": {
|
|
372
|
+
"ripple": { "command": "npx", "args": ["@alimaandev/ripple", "mcp"] }
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Four tools are served:
|
|
378
|
+
|
|
379
|
+
| Tool | Inputs | Returns |
|
|
380
|
+
| ------------- | ------------------- | ----------------------------------------------------------------------- |
|
|
381
|
+
| `impact` | `file`, `maxDepth?` | Blast radius: affected files, routes, tests, components, risk level |
|
|
382
|
+
| `dependents` | `file`, `depth?` | Who imports the file, up to a depth (default 1, direct) |
|
|
383
|
+
| `risk` | `file` | Risk score with the factor breakdown behind it |
|
|
384
|
+
| `gate_status` | `base?`, `gate?` | Current change set vs the merge gate: files, levels, pass/block verdict |
|
|
385
|
+
|
|
386
|
+
A typical agent loop: `impact src/auth/session.ts` before refactoring,
|
|
387
|
+
`dependents` to see who breaks, then `gate_status` after editing to confirm
|
|
388
|
+
the gate still passes. Tool results are JSON text; failures return
|
|
389
|
+
`isError` results instead of crashing the session.
|
|
390
|
+
|
|
391
|
+
<img src="https://raw.githubusercontent.com/alimaandev/ripple/main/assets/mcp-demo.svg" alt="Flow diagram — an AI agent calls impact on src/auth/session.ts through ripple mcp and gets the blast radius back: 7 affected files, 4 routes, MEDIUM risk" title="ripple mcp flow" width="100%" />
|
|
392
|
+
|
|
336
393
|
## Configuration
|
|
337
394
|
|
|
338
395
|
Ripple discovers `ripple.config.ts`, `.js`, `.cjs`, `.mjs`, or `.json` in the
|
|
@@ -341,8 +398,8 @@ defaults — every field is optional.
|
|
|
341
398
|
|
|
342
399
|
```json
|
|
343
400
|
{
|
|
344
|
-
"$schema": "
|
|
345
|
-
"include": ["**/*.{ts,tsx,js,jsx}"],
|
|
401
|
+
"$schema": "https://raw.githubusercontent.com/alimaandev/ripple/main/ripple.schema.json",
|
|
402
|
+
"include": ["**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}"],
|
|
346
403
|
"ignore": ["node_modules", "dist", "build", "coverage", ".next", "out"],
|
|
347
404
|
"aliases": { "@": "./src" },
|
|
348
405
|
"tsconfigPath": "tsconfig.json",
|
|
@@ -368,19 +425,20 @@ defaults — every field is optional.
|
|
|
368
425
|
|
|
369
426
|
> [!TIP]
|
|
370
427
|
> The `$schema` line powers editor autocomplete and validation for
|
|
371
|
-
> `ripple.config.json`
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
|
375
|
-
|
|
|
376
|
-
| `
|
|
377
|
-
| `
|
|
378
|
-
| `
|
|
379
|
-
| `
|
|
380
|
-
| `risk.
|
|
381
|
-
| `
|
|
382
|
-
| `diff.
|
|
383
|
-
| `diff.
|
|
428
|
+
> `ripple.config.json`. `ripple init` writes the hosted schema URL; the
|
|
429
|
+
> package also ships `ripple.schema.json` if you prefer a local path.
|
|
430
|
+
|
|
431
|
+
| Field | Default | Purpose |
|
|
432
|
+
| ----------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
|
|
433
|
+
| `include` | `**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}` | Source globs to analyze |
|
|
434
|
+
| `ignore` | `node_modules`, `dist`, `build`, `coverage`, `.next`, `out` | Exclusions |
|
|
435
|
+
| `aliases` | `{}` | Path aliases, merged with tsconfig `paths` (user wins) |
|
|
436
|
+
| `tsconfigPath` | `tsconfig.json` | tsconfig to read for `paths` |
|
|
437
|
+
| `risk.weights` | see example | Risk signal weights |
|
|
438
|
+
| `risk.thresholds` | 30 / 55 / 80 | Score thresholds for MEDIUM / HIGH / CRITICAL |
|
|
439
|
+
| `diff.base` | GitHub PR base → `origin/HEAD` → `origin/main` → `origin/master` → `main` → `master` | Git ref to diff against when `--base` is not given |
|
|
440
|
+
| `diff.allow` | `[]` | Project-relative globs of files that never block the gate |
|
|
441
|
+
| `diff.gate` | `high` | Blocking level when `--gate` is not given |
|
|
384
442
|
|
|
385
443
|
`node_modules` is always excluded, regardless of config.
|
|
386
444
|
|
|
@@ -493,7 +551,7 @@ verdict:
|
|
|
493
551
|
```json
|
|
494
552
|
{
|
|
495
553
|
"tool": "ripple",
|
|
496
|
-
"version": "0.
|
|
554
|
+
"version": "0.7.1",
|
|
497
555
|
"command": "diff",
|
|
498
556
|
"base": "origin/main",
|
|
499
557
|
"changedFiles": 2,
|
|
@@ -503,20 +561,25 @@ verdict:
|
|
|
503
561
|
"analyzed": true,
|
|
504
562
|
"risk": { "score": 88.2, "level": "CRITICAL", "factors": [] },
|
|
505
563
|
"affectedFiles": 14,
|
|
506
|
-
"targetInCycle": false
|
|
564
|
+
"targetInCycle": false,
|
|
565
|
+
"allowed": false
|
|
507
566
|
},
|
|
508
567
|
{ "file": "src/api/legacy.js", "analyzed": false }
|
|
509
568
|
],
|
|
510
569
|
"gate": {
|
|
511
570
|
"level": "high",
|
|
512
571
|
"blocked": true,
|
|
513
|
-
"counts": { "low": 0, "medium": 0, "high": 0, "critical": 1 }
|
|
572
|
+
"counts": { "low": 0, "medium": 0, "high": 0, "critical": 1 },
|
|
573
|
+
"allowed": 0
|
|
514
574
|
},
|
|
515
575
|
"durationMs": 118
|
|
516
576
|
}
|
|
517
577
|
```
|
|
518
578
|
|
|
519
579
|
`blocked` tells CI everything: exit code `1` if `true`, `0` otherwise.
|
|
580
|
+
`files[].file` is project-relative (relative to the directory containing your
|
|
581
|
+
Ripple config); SARIF and GitHub annotations use repository-relative paths so
|
|
582
|
+
Code Scanning and PR annotations land on the right file in a monorepo.
|
|
520
583
|
|
|
521
584
|
### Use it in CI
|
|
522
585
|
|
package/dist/bin.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
|
|
2
|
-
export {
|
|
2
|
+
export { };
|