@alimaandev/ripple 0.4.0 → 0.6.0

package/README.md

@@ -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.4.0
+ripple version                  # → 0.6.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.6.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.6.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,39 +205,40 @@ 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` | `-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                                         |
-| `analyze` | `--no-color`          | Disable ANSI colors                                                |
-| `graph`   | `-j, --json`          | Emit the JSON report                                               |
-| `graph`   | `-r, --reverse`       | Show dependents (what imports this file) instead of dependencies   |
-| `graph`   | `-d, --depth <n>`     | Cap tree depth                                                     |
-| `graph`   | `-c, --config <path>` | Use a specific config file                                         |
-| `graph`   | `--no-color`          | Disable ANSI colors                                                |
-| `doctor`  | `-c, --config <path>` | Use a specific config file                                         |
-| `doctor`  | `-v, --verbose`       | Verbose output                                                     |
-| `doctor`  | `--no-color`          | Disable ANSI colors                                                |
-| `init`    | `-f, --force`         | Overwrite an existing config                                       |
-| `diff`    | `-j, --json`          | Emit the JSON report instead of the terminal report                |
+| Command   | Flag                  | Description                                                                                    |
+| --------- | --------------------- | ---------------------------------------------------------------------------------------------- |
+| `analyze` | `-j, --json`          | Emit the JSON report instead of the terminal report                                            |
+| `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                                                                     |
+| `analyze` | `--no-color`          | Disable ANSI colors                                                                            |
+| `graph`   | `-j, --json`          | Emit the JSON report                                                                           |
+| `graph`   | `-r, --reverse`       | Show dependents (what imports this file) instead of dependencies                               |
+| `graph`   | `-d, --depth <n>`     | Cap tree depth                                                                                 |
+| `graph`   | `-c, --config <path>` | Use a specific config file                                                                     |
+| `graph`   | `--no-color`          | Disable ANSI colors                                                                            |
+| `doctor`  | `-c, --config <path>` | Use a specific config file                                                                     |
+| `doctor`  | `-v, --verbose`       | Verbose output                                                                                 |
+| `doctor`  | `--no-color`          | Disable ANSI colors                                                                            |
+| `init`    | `-f, --force`         | Overwrite an existing config                                                                   |
+| `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`    | `-d, --depth <n>`     | Cap reverse traversal per file                                     |
-| `diff`    | `-c, --config <path>` | Use a specific config file                                         |
-| `diff`    | `--no-color`          | Disable ANSI colors                                                |
+| `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`    | `-d, --depth <n>`     | Cap reverse traversal per file                                                                 |
+| `diff`    | `-c, --config <path>` | Use a specific config file                                                                     |
+| `diff`    | `--no-color`          | Disable ANSI colors                                                                            |
 
 ### `ripple doctor`
 
@@ -262,6 +267,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`
 
@@ -275,29 +289,50 @@ 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)
 ```
 
 Run `ripple diff` locally before opening a PR, and in CI as the same gate —
 identical code, identical verdict.
 
+```bash
+ripple diff --format github
+```
+
+`--format github` emits GitHub Actions workflow commands. Each risky change
+shows as a warning or error annotation right on the PR's Files tab —
+`::error` when a file blocks the gate, `::warning` otherwise — plus a
+`::notice` line with the gate verdict. The exit code still carries the
+verdict, so the job fails when the gate blocks:
+
+```yaml
+- run: npx @alimaandev/ripple diff --format github
+```
+
+(`--json` is shorthand for `--format json`; the format flag also accepts
+`terminal`, the default.)
+
 ## Configuration
 
 Ripple discovers `ripple.config.ts`, `.js`, `.cjs`, `.mjs`, or `.json` in the
@@ -306,6 +341,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" },
@@ -324,11 +360,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                                |
@@ -338,6 +379,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.
@@ -400,7 +442,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": [] },
@@ -451,7 +493,7 @@ verdict:
 ```json
 {
   "tool": "ripple",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "command": "diff",
   "base": "origin/main",
   "changedFiles": 2,
@@ -561,6 +603,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