@alimaandev/ripple 0.6.0 → 0.7.0

package/README.md

@@ -21,7 +21,7 @@ Change less. Break less. Know the blast radius of any file before you touch it.
 # or try it without installing anything:
 npx @alimaandev/ripple analyze src/your-file.ts</code></pre>
 
-  <img src="https://raw.githubusercontent.com/alimaandev/ripple/main/assets/hero.svg" alt="Terminal output of `ripple analyze` — risk, affected files, routes, components, tests, and confidence score" title="ripple analyze" width="100%" />
+  <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%" />
 
 </div>
 
@@ -100,7 +100,7 @@ Everything below is real output against a shipped example project in `tests/fixt
 ```bash
 npm install -g @alimaandev/ripple
 
-ripple version                  # → 0.6.0
+ripple version                  # → 0.7.0
 ```
 
 Or install from source:
@@ -132,7 +132,7 @@ ripple analyze src/authentication/login.ts
 Expected output:
 
 ```text
-ripple · impact analysis · v0.6.0
+ripple · impact analysis · v0.7.0
 
 File        src/authentication/login.ts
 Risk        MEDIUM · 34.7/100 ███░░░░░░░
@@ -165,7 +165,7 @@ ripple graph
 ```
 
 ```text
-ripple · dependency graph · v0.6.0
+ripple · dependency graph · v0.7.0
 
 Files            25
 Edges            28
@@ -219,6 +219,7 @@ ripple <command> [options]
 | Command   | Flag                  | Description                                                                                    |
 | --------- | --------------------- | ---------------------------------------------------------------------------------------------- |
 | `analyze` | `-j, --json`          | Emit the JSON report instead of the terminal report                                            |
+| `analyze` | `--sarif`             | Emit a SARIF 2.1.0 report for code scanning                                                    |
 | `analyze` | `-v, --verbose`       | Include the risk-factor point breakdown                                                        |
 | `analyze` | `-d, --depth <n>`     | Cap the reverse traversal at `n` levels                                                        |
 | `analyze` | `-c, --config <path>` | Use a specific config file                                                                     |
@@ -235,11 +236,16 @@ ripple <command> [options]
 | `diff`    | `-j, --json`          | Emit the JSON report instead of the terminal report                                            |
 | `diff`    | `-b, --base <ref>`    | Git ref to diff against (default: `origin/main`, `main`, `HEAD~1`, or `diff.base` from config) |
 | `diff`    | `-g, --gate <level>`  | Blocking level: `medium`, `high`, or `critical` (default: `high`, or `diff.gate` from config)  |
-| `diff`    | `-f, --format <fmt>`  | Output: `terminal`, `json`, or `github` (workflow annotations)                                 |
+| `diff`    | `-f, --format <fmt>`  | Output: `terminal`, `json`, `github` (workflow annotations), or `sarif`                        |
 | `diff`    | `-d, --depth <n>`     | Cap reverse traversal per file                                                                 |
 | `diff`    | `-c, --config <path>` | Use a specific config file                                                                     |
 | `diff`    | `--no-color`          | Disable ANSI colors                                                                            |
 
+### `ripple mcp`
+
+Serve Ripple's analysis tools over the Model Context Protocol (see
+[the MCP section](#ripple-mcp-1) below).
+
 ### `ripple doctor`
 
 Independent health checks — config validity, tsconfig presence, source
@@ -333,6 +339,57 @@ verdict, so the job fails when the gate blocks:
 (`--json` is shorthand for `--format json`; the format flag also accepts
 `terminal`, the default.)
 
+`--format sarif` emits SARIF 2.1.0, the format GitHub Code Scanning speaks:
+
+```bash
+ripple diff --format sarif > ripple.sarif
+```
+
+Each analyzed change becomes a finding on the file — `error` when it is
+CRITICAL/HIGH, `warning` for MEDIUM, `note` for LOW — with a stable
+`primaryLocationLineHash` fingerprint so results deduplicate across runs.
+Allowlisted files are emitted as `note` with an in-source suppression, so
+they show as exempted rather than failing. Upload the report straight into
+Code Scanning alerts:
+
+```yaml
+- uses: actions/upload-sarif@v3
+  with:
+    sarif_file: ripple.sarif
+```
+
+The exit code still carries the gate verdict regardless of format.
+
+### `ripple mcp`
+
+`ripple mcp` exposes Ripple's analysis to AI coding agents as a Model
+Context Protocol server over stdio. Point any MCP client at the command and
+the agent can check a file's blast radius before touching it:
+
+```json
+{
+  "mcpServers": {
+    "ripple": { "command": "npx", "args": ["@alimaandev/ripple", "mcp"] }
+  }
+}
+```
+
+Four tools are served:
+
+| Tool          | Inputs              | Returns                                                                 |
+| ------------- | ------------------- | ----------------------------------------------------------------------- |
+| `impact`      | `file`, `maxDepth?` | Blast radius: affected files, routes, tests, components, risk level     |
+| `dependents`  | `file`, `depth?`    | Who imports the file, up to a depth (default 1, direct)                 |
+| `risk`        | `file`              | Risk score with the factor breakdown behind it                          |
+| `gate_status` | `base?`, `gate?`    | Current change set vs the merge gate: files, levels, pass/block verdict |
+
+A typical agent loop: `impact src/auth/session.ts` before refactoring,
+`dependents` to see who breaks, then `gate_status` after editing to confirm
+the gate still passes. Tool results are JSON text; failures return
+`isError` results instead of crashing the session.
+
+  <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%" />
+
 ## Configuration
 
 Ripple discovers `ripple.config.ts`, `.js`, `.cjs`, `.mjs`, or `.json` in the