@alimaandev/ripple 0.5.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>
 
@@ -69,19 +69,22 @@ Just deterministic analysis against the code you actually have.
 
 ## Features
 
-| Feature                      | What it does                                                                                                     |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| **Impact analysis**          | Reverse dependency traversal, transitively, with depth caps. Know who imports a target file.                     |
-| **Risk scoring**             | A transparent 0–100 score from seven weighted signals, with a per-factor breakdown in `--verbose`.               |
-| **Cycle detection**          | Strongly-connected components with a concrete cycle path — `a → c → b → a`, not just a list of names.            |
-| **Alias & path support**     | tsconfig `paths` and custom aliases like `{ "@": "./src" }`, including single-wildcard patterns.                 |
-| **Real-world resolution**    | Extension probing, index files, `.js` → `.ts` rewriting, dynamic `import()`, `require()`, `export … from`.       |
-| **Categorized results**      | Routes, layouts, components, utilities, and tests detected by path conventions — not a raw string of file names. |
-| **Entry-point intelligence** | `package.json` `main`/`bin` plus conventional root and `src` entry files, flagged in the report.                 |
-| **Stable JSON contract**     | A machine-readable report for CI gates, dashboards, and tooling — additive-only compatibility.                   |
-| **Change-set gating**        | `ripple diff` analyzes every changed file since a base ref and blocks the merge on risky code.                   |
-| **Error-tolerant parsing**   | A broken file lowers confidence instead of aborting the run. No false precision.                                 |
-| **Deterministic & offline**  | Same input, same output, every time. No hidden network dependency.                                               |
+| Feature                      | What it does                                                                                                            |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **Impact analysis**          | Reverse dependency traversal, transitively, with depth caps. Know who imports a target file.                            |
+| **Risk scoring**             | A transparent 0–100 score from seven weighted signals, with a per-factor breakdown in `--verbose`.                      |
+| **Cycle detection**          | Strongly-connected components with a concrete cycle path — `a → c → b → a`, not just a list of names.                   |
+| **Alias & path support**     | tsconfig `paths` and custom aliases like `{ "@": "./src" }`, including single-wildcard patterns.                        |
+| **Real-world resolution**    | Extension probing, index files, `.js` → `.ts` rewriting, dynamic `import()`, `require()`, `export … from`.              |
+| **Categorized results**      | Routes, layouts, components, utilities, and tests detected by path conventions — not a raw string of file names.        |
+| **Entry-point intelligence** | `package.json` `main`/`bin` plus conventional root and `src` entry files, flagged in the report.                        |
+| **Stable JSON contract**     | A machine-readable report for CI gates, dashboards, and tooling — additive-only compatibility.                          |
+| **Change-set gating**        | `ripple diff` analyzes every changed file since a base ref and blocks the merge on risky code.                          |
+| **Diff allowlist**           | `--allow <glob>` (or `diff.allow` in config) exempts legacy files from blocking the gate — analyze, report, don't fail. |
+| **Graph exports**            | `ripple graph --format mermaid                                                                                          | dot | html` renders the project graph as a Mermaid flowchart, Graphviz digraph, or a self-contained HTML report. |
+| **Config JSON Schema**       | Editors autocomplete and validate `ripple.config.json` against the shipped `ripple.schema.json` via `$schema`.          |
+| **Error-tolerant parsing**   | A broken file lowers confidence instead of aborting the run. No false precision.                                        |
+| **Deterministic & offline**  | Same input, same output, every time. No hidden network dependency.                                                      |
 
 ## Quick start
 
@@ -97,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.5.0
+ripple version                  # → 0.7.0
 ```
 
 Or install from source:
@@ -129,9 +132,7 @@ ripple analyze src/authentication/login.ts
 Expected output:
 
 ```text
-╭ ripple ────────────────────────────╮
-│  ❯ impact analysis · v0.2.0        │
-╰────────────────────────────────────╯
+ripple · impact analysis · v0.7.0
 
 File        src/authentication/login.ts
 Risk        MEDIUM · 34.7/100 ███░░░░░░░
@@ -140,18 +141,15 @@ Affected    7 files
 Max depth   2
 Confidence  100%
 
-────────────────────────────────────
-Top impact
+› Top impact
 ● Dashboard (2)
 ● Admin (1)
 ● Index TS (1)
 
-────────────────────────────────────
-Circular dependencies
+› Circular dependencies
 ◯ src/circular/a.ts → src/circular/c.ts → src/circular/b.ts → src/circular/a.ts
 
-────────────────────────────────────
-Affected files (7)
+› Affected files (7)
 ├─ src/admin/page.tsx · depth 1
 ├─ src/dashboard/page.tsx · depth 1
 └─ src/main.ts · depth 2
@@ -167,9 +165,7 @@ ripple graph
 ```
 
 ```text
-╭ ripple ────────────────────────────╮
-│  ❯ dependency graph · v0.2.0       │
-╰────────────────────────────────────╯
+ripple · dependency graph · v0.7.0
 
 Files            25
 Edges            28
@@ -177,11 +173,19 @@ External         4
 Unresolved       0
 Circular groups  1
 
-────────────────────────────────────
-Circular dependencies
+› Circular dependencies
 ◯ src/circular/a.ts → src/circular/c.ts → src/circular/b.ts → src/circular/a.ts
 ```
 
+Export the graph for documentation or a team wiki — no extra tooling needed:
+
+```bash
+ripple graph --format mermaid   # Mermaid flowchart (GitHub renders it natively)
+ripple graph --format dot       # Graphviz digraph
+ripple graph --format html      # self-contained dark-themed HTML report
+ripple graph src/authentication/login.ts --format mermaid   # just a file's blast radius
+```
+
 Point it at a file to see its dependency tree — forwards (what it imports)
 or, with `-r`, backwards (what imports it):
 
@@ -201,20 +205,21 @@ Dependents (reverse)
 ripple <command> [options]
 ```
 
-| Command          | Description                                       |
-| ---------------- | ------------------------------------------------- |
-| `analyze <file>` | Impact analysis for a target file                 |
-| `graph [file]`   | Project stats, or a single file's dependency tree |
-| `diff`           | Gate all files changed since a git base ref       |
-| `doctor`         | Project and environment health check              |
-| `init`           | Scaffold a `ripple.config.json`                   |
-| `version`        | Print the current version                         |
+| Command          | Description                                       | Example                                      |
+| ---------------- | ------------------------------------------------- | -------------------------------------------- |
+| `analyze <file>` | Impact analysis for a target file                 | `ripple analyze src/authentication/login.ts` |
+| `graph [file]`   | Project stats, or a single file's dependency tree | `ripple graph src/circular/b.ts -r`          |
+| `diff`           | Gate all files changed since a git base ref       | `ripple diff --base main --gate critical`    |
+| `doctor`         | Project and environment health check              | `ripple doctor -v`                           |
+| `init`           | Scaffold a `ripple.config.json`                   | `ripple init`                                |
+| `version`        | Print the current version                         | `ripple version`                             |
 
 ### 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                                                                     |
@@ -231,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
@@ -263,6 +273,15 @@ $ ripple doctor
 ### `ripple init`
 
 Writes `ripple.config.json` with the recommended defaults, ready to edit.
+The minimal config references the shipped JSON Schema so editors
+autocomplete and validate as you type:
+
+```bash
+ripple init                # minimal ripple.config.json + $schema
+ripple init --full         # every built-in default, written out
+ripple init --ts           # typed ripple.config.ts
+ripple init --ts --full    # full defaults as TypeScript
+```
 
 ### `ripple diff`
 
@@ -276,23 +295,27 @@ cd my-project
 ripple diff                       # vs origin/main (then main, then HEAD~1)
 ripple diff --base HEAD~1 --json  # machine-readable gate report
 ripple diff --gate critical       # only CRITICAL blocks the merge
+ripple diff --allow "src/legacy/**"   # legacy files never block the gate
 ```
 
+Adopting the gate on an existing codebase? Allowlist the files you haven't
+fixed yet — they are still analyzed and shown in the report, marked
+`(allowed)`, but they can't fail CI. The same list lives in config as
+`diff.allow`, so the whole team shares it.
+
 ```text
-╭ ripple ─────────────────────╮
-│  ❯ diff vs origin/main      │
-╰─────────────────────────────╯
+ripple · diff vs origin/main
 
 Changed  2 files
 Source   2 files
+Allowed  1 file
 Duration 118ms
 
-✖ Gate blocked — 1 CRITICAL (no HIGH or CRITICAL)
+✔ Gate passed — none (no HIGH or CRITICAL)
 
-─────────────────────────────────────
-Risk analysis (2 files)
+› Risk analysis (2 files)
 ✖ src/auth/token.ts     CRITICAL · 88.2/100 ████████░░
-● src/auth/session.ts   LOW · 12.4/100 █░░░░░░░░░
+✔ src/legacy/session.ts LOW · 12.4/100 █░░░░░░░░░ (allowed)
 … src/api/legacy.js     (not a source file)
 ```
 
@@ -316,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
@@ -324,6 +398,7 @@ defaults — every field is optional.
 
 ```json
 {
+  "$schema": "./node_modules/@alimaandev/ripple/ripple.schema.json",
   "include": ["**/*.{ts,tsx,js,jsx}"],
   "ignore": ["node_modules", "dist", "build", "coverage", ".next", "out"],
   "aliases": { "@": "./src" },
@@ -342,11 +417,16 @@ defaults — every field is optional.
   },
   "diff": {
     "base": "origin/main",
-    "gate": "high"
+    "gate": "high",
+    "allow": ["src/legacy/**"]
   }
 }
 ```
 
+> [!TIP]
+> The `$schema` line powers editor autocomplete and validation for
+> `ripple.config.json` — the package ships `ripple.schema.json` for it.
+
 | Field             | Default                                                     | Purpose                                                |
 | ----------------- | ----------------------------------------------------------- | ------------------------------------------------------ |
 | `include`         | `**/*.{ts,tsx,js,jsx}`                                      | Source globs to analyze                                |
@@ -356,6 +436,7 @@ defaults — every field is optional.
 | `risk.weights`    | see example                                                 | Risk signal weights                                    |
 | `risk.thresholds` | 30 / 55 / 80                                                | Score thresholds for MEDIUM / HIGH / CRITICAL          |
 | `diff.base`       | `origin/main` → `main` → `HEAD~1`                           | Git ref to diff against when `--base` is not given     |
+| `diff.allow`      | `[]`                                                        | Globs of files that never block the gate               |
 | `diff.gate`       | `high`                                                      | Blocking level when `--gate` is not given              |
 
 `node_modules` is always excluded, regardless of config.
@@ -418,7 +499,7 @@ error-tolerant recovery, `graph/` resolves specifiers and detects cycles, and
 ```json
 {
   "tool": "ripple",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "command": "analyze",
   "file": "src/authentication/login.ts",
   "risk": { "score": 34.4, "level": "MEDIUM", "factors": [] },
@@ -469,7 +550,7 @@ verdict:
 ```json
 {
   "tool": "ripple",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "command": "diff",
   "base": "origin/main",
   "changedFiles": 2,
@@ -579,6 +660,11 @@ pnpm run build          # tsup
 Architecture and design decisions live in [docs/architecture.md](docs/architecture.md).
 Before contributing, read [CONTRIBUTING.md](CONTRIBUTING.md).
 
+Quality gates run on every pull request: lint, typecheck, build, unit tests
+(against a global coverage floor for `src/**`), integration tests on Linux
+and Windows, and a dogfood job — Ripple gates its own PRs with
+`ripple diff --format github`.
+
 ## Get started
 
 ```bash