@alimaandev/ripple 0.2.0 → 0.3.0

package/README.md

@@ -16,7 +16,10 @@ Change less. Break less. Know the blast radius of any file before you touch it.
     &nbsp;<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>&nbsp;
   </p>
 
-  <pre><code>npm install -g @alimaandev/ripple</code></pre>
+  <pre><code>npm install -g @alimaandev/ripple
+
+# 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%" />
 
@@ -76,6 +79,7 @@ Just deterministic analysis against the code you actually have.
 | **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.                                               |
 
@@ -108,8 +112,17 @@ npm link                        # exposes the global `ripple` binary
 
 ### Run your first analysis
 
+No install required — `npx` pulls the package from the registry on the fly:
+
 ```bash
 cd tests/fixtures/basic
+npx @alimaandev/ripple analyze src/authentication/login.ts
+```
+
+Once you're sold, install it globally:
+
+```bash
+npm install -g @alimaandev/ripple
 ripple analyze src/authentication/login.ts
 ```
 
@@ -192,28 +205,35 @@ ripple <command> [options]
 | ---------------- | ------------------------------------------------- |
 | `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                         |
 
 ### 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                                     |
+| 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`) |
+| `diff`    | `-g, --gate <level>`  | Blocking level: `medium`, `high`, or `critical` (default: `high`)  |
+| `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`
 
@@ -243,6 +263,41 @@ $ ripple doctor
 
 Writes `ripple.config.json` with the recommended defaults, ready to edit.
 
+### `ripple diff`
+
+Analyzes every file that changed since a base git ref, scores each with the
+same risk model as `analyze`, and gates the change set: any file reaching
+the gate level (HIGH by default) makes the command exit `1`. Untracked
+files are included; deleted files and non-source changes are skipped.
+
+```bash
+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
+```
+
+```text
+╭ ripple ─────────────────────╮
+│  ❯ diff vs origin/main      │
+╰─────────────────────────────╯
+
+Changed  2 files
+Source   2 files
+Duration 118ms
+
+✖ Gate blocked — 1 CRITICAL (no HIGH or CRITICAL)
+
+─────────────────────────────────────
+Risk analysis (2 files)
+✖ src/auth/token.ts     CRITICAL · 88.2/100 ████████░░
+● src/auth/session.ts   LOW · 12.4/100 █░░░░░░░░░
+… 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.
+
 ## Configuration
 
 Ripple discovers `ripple.config.ts`, `.js`, `.cjs`, `.mjs`, or `.json` in the
@@ -379,6 +434,39 @@ error-tolerant recovery, `graph/` resolves specifiers and detects cycles, and
 > change without a major version bump. `graph --json` follows the same
 > convention.
 
+### `ripple diff --json`
+
+The diff report wraps a per-file view of the same risk model, plus the gate
+verdict:
+
+```json
+{
+  "tool": "ripple",
+  "version": "0.3.0",
+  "command": "diff",
+  "base": "origin/main",
+  "changedFiles": 2,
+  "files": [
+    {
+      "file": "src/auth/token.ts",
+      "analyzed": true,
+      "risk": { "score": 88.2, "level": "CRITICAL", "factors": [] },
+      "affectedFiles": 14,
+      "targetInCycle": false
+    },
+    { "file": "src/api/legacy.js", "analyzed": false }
+  ],
+  "gate": {
+    "level": "high",
+    "blocked": true,
+    "counts": { "low": 0, "medium": 0, "high": 0, "critical": 1 }
+  },
+  "durationMs": 118
+}
+```
+
+`blocked` tells CI everything: exit code `1` if `true`, `0` otherwise.
+
 ### Use it in CI
 
 ```bash
@@ -386,6 +474,16 @@ ripple analyze src/authentication/login.ts --json | jq -r .risk.level
 # MEDIUM
 ```
 
+Gate every changed file in one call:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+ripple diff --json --gate high
+# exits 1 when any changed file is HIGH or CRITICAL
+```
+
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
@@ -430,12 +528,12 @@ fi
 
 ## Exit codes
 
-| Code | Meaning                   |
-| ---- | ------------------------- |
-| `0`  | Success                   |
-| `1`  | General failure           |
-| `2`  | Target file not found     |
-| `3`  | Config missing or invalid |
+| Code | Meaning                               |
+| ---- | ------------------------------------- |
+| `0`  | Success                               |
+| `1`  | General failure / gate blocked        |
+| `2`  | Target file or git base ref not found |
+| `3`  | Config missing or invalid             |
 
 ## Development
 
@@ -461,6 +559,10 @@ npm install -g @alimaandev/ripple
 ripple analyze src/your-file.ts --json | jq -r .risk.level   # MEDIUM, HIGH, ...
 ```
 
+If Ripple has ever kept you from an accidental breaking change, a
+[little star](https://github.com/alimaandev/ripple) goes a long way — it
+helps other developers find it.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/dist/bin.js

@@ -12,6 +12,7 @@ import treeify from 'treeify';
 import boxen from 'boxen';
 import fg from 'fast-glob';
 import ora from 'ora';
+import { execFileSync } from 'child_process';
 
 // src/output/writer.ts
 var TerminalWriter = class {
@@ -268,8 +269,8 @@ async function loadProjectContext(cwd, explicitConfigPath) {
 function cycleMemberPaths(graph) {
   const members = /* @__PURE__ */ new Set();
   for (const cycle of graph.cycles) {
-    for (const path12 of cycle.members) {
-      members.add(path12);
+    for (const path13 of cycle.members) {
+      members.add(path13);
     }
   }
   return members;
@@ -980,12 +981,12 @@ function renderGraphReport(input, options, writer) {
   writer.writeLine();
   if (input.forward) {
     writer.writeLine(sectionHeader("Dependants (forward)", style));
-    writer.writeLine(renderTree(input.forward.map((path12) => ({ label: path12 }))));
+    writer.writeLine(renderTree(input.forward.map((path13) => ({ label: path13 }))));
     writer.writeLine();
   }
   if (input.reverse) {
     writer.writeLine(sectionHeader("Dependents (reverse)", style));
-    writer.writeLine(renderTree(input.reverse.map((path12) => ({ label: path12 }))));
+    writer.writeLine(renderTree(input.reverse.map((path13) => ({ label: path13 }))));
     writer.writeLine();
   }
   writer.writeLine(sectionHeader("Circular dependencies", style));
@@ -1277,8 +1278,8 @@ function findCycles(graph) {
     }
     const members = [...component].sort();
     const componentSet = new Set(component);
-    const path12 = representativeCyclePath(graph, component, componentSet);
-    cycles.push({ members, path: path12 ?? [members[0], members[0]] });
+    const path13 = representativeCyclePath(graph, component, componentSet);
+    cycles.push({ members, path: path13 ?? [members[0], members[0]] });
   }
   cycles.sort(
     (a, b) => a.members.length - b.members.length || a.members[0].localeCompare(b.members[0])
@@ -1287,14 +1288,14 @@ function findCycles(graph) {
 }
 function representativeCyclePath(graph, component, componentSet) {
   const inPath = /* @__PURE__ */ new Set();
-  const path12 = [];
+  const path13 = [];
   let current = component[0];
   for (let steps = 0; steps <= component.length * 2 && current !== void 0; steps++) {
     const firstOccurrence = inPath.has(current);
     if (firstOccurrence) {
-      const start = path12.indexOf(current);
+      const start = path13.indexOf(current);
       if (start === -1) return void 0;
-      const cycle = path12.slice(start);
+      const cycle = path13.slice(start);
       if (cycle.length > 1 || graph.forward.get(current)?.has(current)) {
         cycle.push(current);
         return cycle;
@@ -1302,7 +1303,7 @@ function representativeCyclePath(graph, component, componentSet) {
       return void 0;
     }
     inPath.add(current);
-    path12.push(current);
+    path13.push(current);
     const next = [...graph.forward.get(current) ?? []].find(
       (candidate) => componentSet.has(candidate)
     );
@@ -1754,6 +1755,223 @@ async function initCommand(options, ctx2) {
     return ExitCode.Failure;
   }
 }
+var DEFAULT_BASES = ["origin/main", "main", "HEAD~1"];
+function git(args, cwd) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function refExists(ref, cwd) {
+  try {
+    const out = git(["rev-parse", "--verify", ref], cwd);
+    return out.length > 0;
+  } catch {
+    return false;
+  }
+}
+function resolveBase(cwd, requested) {
+  if (requested) {
+    if (!refExists(requested, cwd)) {
+      throw new RippleError(`Git ref not found: ${requested}`, ExitCode.NotFound);
+    }
+    return requested;
+  }
+  for (const candidate of DEFAULT_BASES) {
+    if (refExists(candidate, cwd)) return candidate;
+  }
+  throw new RippleError(
+    "No git base ref found (tried origin/main, main, HEAD~1). Pass --base <ref> explicitly.",
+    ExitCode.NotFound
+  );
+}
+function changedFiles(cwd, base) {
+  const baseLabel = resolveBase(cwd, base);
+  let baseCommit = baseLabel;
+  try {
+    const mergeBase = git(["merge-base", baseLabel, "HEAD"], cwd);
+    if (mergeBase) baseCommit = mergeBase;
+  } catch {
+  }
+  const files = /* @__PURE__ */ new Set();
+  const tracked = git(["diff", "--name-only", "--diff-filter=ACMRT", baseCommit], cwd);
+  for (const line of tracked.split("\n")) {
+    if (line.trim()) files.add(line.trim());
+  }
+  const untracked = git(["ls-files", "--others", "--exclude-standard"], cwd);
+  for (const line of untracked.split("\n")) {
+    if (line.trim()) files.add(line.trim());
+  }
+  return { baseLabel, files: [...files].sort() };
+}
+
+// src/commands/diff.ts
+var LEVEL_INDEX = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
+var GATE_INDEX = { medium: 1, high: 2, critical: 3 };
+var VERDICT_NOTE = {
+  medium: "no MEDIUM or worse",
+  high: "no HIGH or CRITICAL",
+  critical: "no CRITICAL"
+};
+function countLevels(results) {
+  const counts = { low: 0, medium: 0, high: 0, critical: 0 };
+  for (const result of results) {
+    counts[result.risk.level.toLowerCase()] += 1;
+  }
+  return counts;
+}
+function riskySummary(counts, gate) {
+  const gateIndex = GATE_INDEX[gate];
+  const parts = [];
+  if (LEVEL_INDEX.CRITICAL >= gateIndex && counts.critical > 0)
+    parts.push(`${counts.critical} CRITICAL`);
+  if (LEVEL_INDEX.HIGH >= gateIndex && counts.high > 0) parts.push(`${counts.high} HIGH`);
+  if (LEVEL_INDEX.MEDIUM >= gateIndex && counts.medium > 0) parts.push(`${counts.medium} MEDIUM`);
+  if (LEVEL_INDEX.LOW >= gateIndex && counts.low > 0) parts.push(`${counts.low} LOW`);
+  return parts.length > 0 ? parts.join(" \xB7 ") : "none";
+}
+async function diffCommand(options, ctx2) {
+  const style = { color: resolveColor(options.color) };
+  const tracker = createStageTracker(!options.json);
+  const gate = options.gate ?? "high";
+  const started = Date.now();
+  tracker.next("Resolving git changes");
+  const changed = changedFiles(ctx2.cwd, options.base);
+  tracker.next("Analyzing changed files");
+  const context = await loadProjectContext(ctx2.cwd, options.config);
+  const { graph, entryPoints } = await runPipeline(context);
+  const byRel = /* @__PURE__ */ new Map();
+  const skipped = [];
+  for (const rel of changed.files) {
+    const abs = path8.resolve(ctx2.cwd, rel);
+    const key = pathKey(abs, context.rootDir);
+    if (!graph.nodes.has(key)) {
+      skipped.push(rel);
+      continue;
+    }
+    byRel.set(
+      rel,
+      analyzeFile({
+        graph,
+        context,
+        entryPoints,
+        targetKey: key,
+        targetPath: abs,
+        durationMs: 0,
+        ...options.depth !== void 0 ? { maxDepth: options.depth } : {}
+      })
+    );
+  }
+  tracker.done();
+  const results = [...byRel.values()].sort((a, b) => b.risk.score - a.risk.score);
+  const counts = countLevels(results);
+  const blocked = results.some((result) => LEVEL_INDEX[result.risk.level] >= GATE_INDEX[gate]);
+  const durationMs = Date.now() - started;
+  if (options.json) {
+    ctx2.writer.write(
+      serializeJson(
+        buildDiffJsonReport(
+          changed.baseLabel,
+          changed.files,
+          byRel,
+          gate,
+          blocked,
+          counts,
+          durationMs,
+          ctx2.version
+        )
+      )
+    );
+    return blocked ? ExitCode.Failure : ExitCode.Success;
+  }
+  renderDiffReport(
+    {
+      cwd: ctx2.cwd,
+      baseLabel: changed.baseLabel,
+      files: changed.files,
+      results,
+      skipped,
+      counts,
+      gate,
+      blocked,
+      durationMs,
+      style
+    },
+    ctx2.writer
+  );
+  return blocked ? ExitCode.Failure : ExitCode.Success;
+}
+function renderDiffReport(input, writer) {
+  const { cwd, baseLabel, files, results, skipped, counts, gate, blocked, durationMs, style } = input;
+  writer.writeLine(brandHeader({ label: `diff vs ${baseLabel}`, style }));
+  writer.writeLine();
+  const rows = [
+    ["Changed", pluralize(files.length, "file")],
+    ["Source", pluralize(results.length, "file")],
+    ["Duration", dim(formatDuration(durationMs), style)]
+  ];
+  const width = Math.max(...rows.map(([key]) => key.length));
+  for (const [key, value] of rows) {
+    writer.writeLine(`${key.padEnd(width)}  ${value}`);
+  }
+  writer.writeLine();
+  const mark = blocked ? icon("cross") : icon("tick");
+  const color = blocked ? chalk.red : chalk.green;
+  const markText = style.color ? color(mark) : mark;
+  const verdict = blocked ? "Gate blocked" : "Gate passed";
+  const verdictText = style.color ? color(strong(verdict, style)) : verdict;
+  writer.writeLine(
+    `${markText} ${verdictText} \u2014 ${riskySummary(counts, gate)} ${dim(`(${VERDICT_NOTE[gate]})`, style)}`
+  );
+  writer.writeLine();
+  writer.writeLine(sectionHeader(`Risk analysis (${results.length} files)`, style));
+  for (const result of results) {
+    const risky = LEVEL_INDEX[result.risk.level] >= GATE_INDEX[gate];
+    const fileIcon = risky ? icon("cross") : icon("tick");
+    const fileIconText = style.color ? risky ? chalk.red(fileIcon) : chalk.green(fileIcon) : fileIcon;
+    const score = result.risk.score.toFixed(1);
+    const gauge = riskGauge(result.risk.score, result.risk.level, style);
+    const file = displayPath(result.targetPath, cwd);
+    writer.writeLine(
+      `${fileIconText} ${file}  ${riskBadge(result.risk.level, style)} \xB7 ${score}/100${gauge ? ` ${gauge}` : ""}`
+    );
+  }
+  for (const rel of skipped) {
+    writer.writeLine(
+      `${dim(icon("ellipsis"), style)} ${dim(rel, style)} ${dim("(not a source file)", style)}`
+    );
+  }
+  writer.writeLine();
+}
+function buildDiffJsonReport(baseLabel, changedFileNames, byRel, gate, blocked, counts, durationMs, version) {
+  const files = [];
+  for (const rel of changedFileNames) {
+    const result = byRel.get(rel);
+    if (result) {
+      files.push({
+        file: rel,
+        analyzed: true,
+        risk: result.risk,
+        affectedFiles: result.summary.affectedFiles,
+        targetInCycle: result.targetInCycle
+      });
+    } else {
+      files.push({ file: rel, analyzed: false });
+    }
+  }
+  files.sort((a, b) => (b.risk?.score ?? -1) - (a.risk?.score ?? -1));
+  return {
+    tool: "ripple",
+    version,
+    command: "diff",
+    base: baseLabel,
+    changedFiles: changedFileNames.length,
+    files,
+    gate: { level: gate, blocked, counts },
+    durationMs
+  };
+}
 
 // src/cli/program.ts
 var PROGRAM_NAME = "ripple";
@@ -1792,6 +2010,27 @@ function createProgram(ctx2) {
       throw new ExitError(exitCode2);
     }
   });
+  program.command("diff").description("Analyze changed files since a base ref and gate risky changes").option("-j, --json", "emit a machine-readable JSON report").option("-v, --verbose", "include extra sections").option("-b, --base <ref>", "git ref to diff against (default: origin/main, main, HEAD~1)").option(
+    "-g, --gate <level>",
+    "risk level that blocks the gate (medium | high | critical)",
+    parseGateLevel
+  ).option("-d, --depth <number>", "cap the reverse traversal depth", parsePositiveInt).option("-c, --config <path>", "path to a ripple config file").option("--no-color", "disable ANSI colors").action(async (options) => {
+    const exitCode2 = await diffCommand(
+      {
+        json: Boolean(options.json),
+        verbose: Boolean(options.verbose),
+        ...options.base !== void 0 ? { base: options.base } : {},
+        ...options.gate !== void 0 ? { gate: options.gate } : {},
+        ...options.depth !== void 0 ? { depth: options.depth } : {},
+        ...options.config !== void 0 ? { config: options.config } : {},
+        color: options.color
+      },
+      ctx2
+    );
+    if (exitCode2 !== ExitCode.Success) {
+      throw new ExitError(exitCode2);
+    }
+  });
   program.command("doctor").description("Check the project and environment for Ripple readiness").option("-v, --verbose", "print detailed diagnostics").option("-c, --config <path>", "path to a ripple config file").option("--no-color", "disable ANSI colors").action(async (options) => {
     const exitCode2 = await doctorCommand(
       {
@@ -1843,6 +2082,16 @@ function parsePositiveInt(value) {
   }
   return parsed;
 }
+function parseGateLevel(value) {
+  if (value === "medium" || value === "high" || value === "critical") {
+    return value;
+  }
+  throw new CommanderError(
+    1,
+    "commander.invalidArgument",
+    `expected one of medium | high | critical, got "${value}"`
+  );
+}
 function printError(error, ctx2) {
   if (error instanceof RippleError) {
     ctx2.errorWriter.writeLine(`\u2716 ${error.message}`);
@@ -1876,7 +2125,7 @@ async function run({ argv, ctx: ctx2 }) {
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.3.0"};
 
 // src/cli/bin.ts
 var ctx = {