@alimaandev/ripple 0.1.1 → 0.3.0

package/dist/bin.js

@@ -6,10 +6,13 @@ import path8 from 'path';
 import fs from 'fs/promises';
 import fs2 from 'fs';
 import { Project, ts, SyntaxKind } from 'ts-morph';
-import ora from 'ora';
-import treeify from 'treeify';
 import chalk from 'chalk';
+import figures from 'figures';
+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 {
@@ -266,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;
@@ -673,24 +676,79 @@ function analyzeFile(input) {
     maxDepth: reachedDepth
   };
 }
-function createSpinner(enabled) {
-  if (!enabled || !process.stdout.isTTY) {
-    return { start: () => {
-    }, stop: () => {
-    } };
+function dim(text, style) {
+  return style.color ? chalk.dim(text) : text;
+}
+function strong(text, style) {
+  return style.color ? chalk.bold(text) : text;
+}
+var RISK_COLORS = {
+  LOW: (text) => chalk.green(text),
+  MEDIUM: (text) => chalk.yellow(text),
+  HIGH: (text) => chalk.magenta(text),
+  CRITICAL: (text) => chalk.red.bold(text)
+};
+function riskColor(level) {
+  return RISK_COLORS[level];
+}
+function riskBadge(level, style) {
+  return style.color ? RISK_COLORS[level](level) : level;
+}
+function confidenceText(percent, style) {
+  const text = `${percent}%`;
+  if (!style.color) return text;
+  if (percent >= 90) return chalk.green(text);
+  if (percent >= 70) return chalk.yellow(text);
+  return chalk.red(text);
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  return `${(ms / 1e3).toFixed(2)}s`;
+}
+function pluralize(count, noun, plural = `${noun}s`) {
+  return `${count} ${count === 1 ? noun : plural}`;
+}
+function icon(name) {
+  return figures[name];
+}
+
+// src/ui/progress.ts
+var noop = {
+  next: () => {
+  },
+  done: () => {
   }
-  let instance;
+};
+function createStageTracker(enabled) {
+  if (!enabled || !process.stdout.isTTY) return noop;
+  let current;
+  let from = 0;
+  const stamp = (label, ms) => {
+    process.stdout.write(
+      `${chalk.green(icon("tick"))} ${label} ${chalk.dim(formatDuration(ms))}
+`
+    );
+  };
   return {
-    start(text) {
-      instance = ora(text).start();
+    next(label) {
+      if (current) stamp(current, Date.now() - from);
+      current = label;
+      from = Date.now();
     },
-    stop() {
-      instance?.stop();
-      instance = void 0;
+    done() {
+      if (current) stamp(current, Date.now() - from);
+      current = void 0;
     }
   };
 }
 
+// src/ui/color.ts
+function resolveColor(requested) {
+  if (requested === false) return false;
+  const noColor = process.env.NO_COLOR;
+  return noColor === void 0 || noColor === "";
+}
+
 // src/formatter/table.ts
 function renderTable(columns, rows) {
   const widths = columns.map((column, index) => {
@@ -728,50 +786,53 @@ function renderTree(nodes) {
   }
   return treeify.asTree(root, false, false).trimEnd();
 }
-function banner(text, style) {
-  return style.color ? chalk.cyanBright.bold(text) : text;
-}
-function sectionTitle(text, style) {
-  return style.color ? chalk.bold.underline(text) : text;
-}
-function dim(text, style) {
-  return style.color ? chalk.dim(text) : text;
-}
-function strong(text, style) {
-  return style.color ? chalk.bold(text) : text;
-}
-var RISK_COLORS = {
-  LOW: (text) => chalk.green(text),
-  MEDIUM: (text) => chalk.yellow(text),
-  HIGH: (text) => chalk.magenta(text),
-  CRITICAL: (text) => chalk.red.bold(text)
-};
-function riskBadge(level, style) {
-  return style.color ? RISK_COLORS[level](level) : level;
-}
-function confidenceText(percent, style) {
-  const text = `${percent}%`;
-  if (!style.color) return text;
-  if (percent >= 90) return chalk.green(text);
-  if (percent >= 70) return chalk.yellow(text);
-  return chalk.red(text);
+var DIVIDER_WIDTH = 38;
+function brandHeader(options) {
+  const { label, version, style } = options;
+  if (!style.color) {
+    return `ripple \u2014 ${label}${version ? ` \xB7 v${version}` : ""}`;
+  }
+  const tagline = `${icon("pointer")} ${label}${version ? ` \xB7 v${version}` : ""}`;
+  return boxen(` ${tagline}`, {
+    padding: { left: 1, right: 1 },
+    title: "ripple",
+    borderStyle: "round",
+    borderColor: "cyan"
+  });
 }
-function formatDuration(ms) {
-  if (ms < 1e3) return `${ms}ms`;
-  return `${(ms / 1e3).toFixed(2)}s`;
+function sectionHeader(title, style) {
+  if (!style.color) return title;
+  return `${chalk.dim("\u2500".repeat(DIVIDER_WIDTH))}
+${chalk.bold(title)}`;
 }
-function pluralize(count, noun, plural = `${noun}s`) {
-  return `${count} ${count === 1 ? noun : plural}`;
+
+// src/ui/gauge.ts
+var CELLS = 10;
+var FILL = "\u2588";
+var EMPTY = "\u2591";
+function riskGauge(score, level, style) {
+  if (!style.color) return "";
+  const filled = Math.max(0, Math.min(CELLS, Math.round(score / 100 * CELLS)));
+  return riskColor(level)(FILL.repeat(filled) + EMPTY.repeat(CELLS - filled));
 }
 
 // src/output/report.ts
 var DEFAULT_LIST_LIMIT = 20;
 var textStyle = (options) => ({ color: options.color });
 function fileLabel(filePath, depth, inCycle, style) {
-  const relative = dim(filePath, style);
-  const depthSuffix = dim(`(depth ${depth})`, style);
-  const cycleSuffix = dim("(cycle)", style);
-  return `${relative} ${depthSuffix}${inCycle ? ` ${cycleSuffix}` : ""}`;
+  const parts = [dim(filePath, style)];
+  if (depth >= 0) parts.push(dim(`\xB7 depth ${depth}`, style));
+  if (inCycle) parts.push(dim("\xB7 cycle", style));
+  return parts.join(" ");
+}
+function impactLine(result, style) {
+  const { summary } = result;
+  const parts = [];
+  if (summary.routes > 0) parts.push(pluralize(summary.routes, "route"));
+  if (summary.components > 0) parts.push(pluralize(summary.components, "component"));
+  if (summary.tests > 0) parts.push(pluralize(summary.tests, "test"));
+  if (summary.utilities > 0) parts.push(pluralize(summary.utilities, "utility"));
+  return parts.length > 0 ? parts.join(" \xB7 ") : dim("none", style);
 }
 function buildAffectedTree(result, cwd, style) {
   const { affected, graph } = result;
@@ -811,29 +872,32 @@ function renderAnalyzeReport(result, options, writer) {
   const style = textStyle(options);
   const { summary, risk } = result;
   const file = displayPath(result.targetPath, options.cwd);
-  writer.writeLine(banner("\u{1F30A} Ripple Analysis", style));
+  writer.writeLine(brandHeader({ label: "impact analysis", version: options.version, style }));
   writer.writeLine();
-  writer.writeLine(
-    renderKeyValue([
-      ["File", file],
-      ["Risk", riskBadge(risk.level, style)],
-      ["Affected Files", pluralize(summary.affectedFiles, "file")],
-      ["Components", String(summary.components)],
-      ["API Routes", String(summary.routes)],
-      ["Tests", String(summary.tests)],
-      ["Utilities", String(summary.utilities)],
-      ["Max Depth", String(summary.maxDepth)],
-      ["Confidence", confidenceText(summary.confidence, style)],
-      ["Duration", dim(formatDuration(result.durationMs), style)]
-    ])
-  );
+  const score = risk.score.toFixed(1);
+  const gauge = riskGauge(risk.score, risk.level, style);
+  const rows = [
+    ["File", file],
+    ["Risk", `${riskBadge(risk.level, style)} \xB7 ${score}/100${gauge ? ` ${gauge}` : ""}`],
+    ["Impact", impactLine(result, style)],
+    ["Affected", pluralize(summary.affectedFiles, "file")],
+    ["Max depth", String(summary.maxDepth)],
+    ["Confidence", confidenceText(summary.confidence, style)],
+    ["Duration", dim(formatDuration(result.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();
-  writer.writeLine(sectionTitle("Top Impact", style));
+  writer.writeLine(sectionHeader("Top impact", style));
   for (const area of summary.topImpact) {
-    writer.writeLine(`\u2022 ${strong(area.label, style)} ${dim(`(${area.count})`, style)}`);
+    writer.writeLine(
+      `${icon("bullet")} ${strong(area.label, style)} ${dim(`(${area.count})`, style)}`
+    );
   }
   writer.writeLine();
-  writer.writeLine(sectionTitle("Circular Dependencies", style));
+  writer.writeLine(sectionHeader("Circular dependencies", style));
   if (result.graph.cycles.length === 0) {
     writer.writeLine(dim("none", style));
   } else {
@@ -841,13 +905,13 @@ function renderAnalyzeReport(result, options, writer) {
       const chain = cycle.path.map((key) => {
         const node = result.graph.nodes.get(key);
         return displayPath(node?.path ?? key, options.cwd);
-      }).join(" \u2192 ");
-      writer.writeLine(`\u2B55 ${chain}`);
+      }).join(` ${icon("arrowRight")} `);
+      writer.writeLine(`${icon("circle")} ${chain}`);
     }
   }
   writer.writeLine();
   if (summary.affectedFiles > 0) {
-    writer.writeLine(sectionTitle(`Affected Files (${summary.affectedFiles})`, style));
+    writer.writeLine(sectionHeader(`Affected files (${summary.affectedFiles})`, style));
     const tree = buildAffectedTree(result, options.cwd, style);
     writer.writeLine(renderTree(tree));
     const limit = options.listLimit ?? DEFAULT_LIST_LIMIT;
@@ -859,22 +923,27 @@ function renderAnalyzeReport(result, options, writer) {
     writer.writeLine();
   }
   if (options.verbose) {
-    writer.writeLine(sectionTitle("Risk Factors", style));
+    writer.writeLine(sectionHeader("Risk factors", style));
     const columns = [
       { header: "Factor" },
       { header: "Weight" },
       { header: "Signal" },
       { header: "Points" }
     ];
-    const rows = risk.factors.map((factor) => [
+    const rowsVerbose = risk.factors.map((factor) => [
       factor.label,
       factor.weight.toFixed(2),
       factor.value.toFixed(2),
       factor.contribution.toFixed(2)
     ]);
-    writer.writeLine(renderTable(columns, rows));
+    writer.writeLine(renderTable(columns, rowsVerbose));
     writer.writeLine();
   }
+  if (style.color) {
+    writer.writeLine(
+      dim(`${icon("info")} Tip: run "ripple doctor" to check project health`, style)
+    );
+  }
 }
 function buildAnalyzeJsonReport(result, version, cwd) {
   const realPath = (key) => result.graph.nodes.get(key)?.path ?? key;
@@ -898,7 +967,7 @@ function buildAnalyzeJsonReport(result, version, cwd) {
 function renderGraphReport(input, options, writer) {
   const style = textStyle(options);
   const { stats } = input;
-  writer.writeLine(banner("\u{1F30A} Dependency Graph", style));
+  writer.writeLine(brandHeader({ label: "dependency graph", version: options.version, style }));
   writer.writeLine();
   writer.writeLine(
     renderKeyValue([
@@ -911,26 +980,26 @@ function renderGraphReport(input, options, writer) {
   );
   writer.writeLine();
   if (input.forward) {
-    writer.writeLine(sectionTitle("Dependants (forward)", style));
-    writer.writeLine(renderTree(input.forward.map((path12) => ({ label: path12 }))));
+    writer.writeLine(sectionHeader("Dependants (forward)", style));
+    writer.writeLine(renderTree(input.forward.map((path13) => ({ label: path13 }))));
     writer.writeLine();
   }
   if (input.reverse) {
-    writer.writeLine(sectionTitle("Dependents (reverse)", style));
-    writer.writeLine(renderTree(input.reverse.map((path12) => ({ label: path12 }))));
+    writer.writeLine(sectionHeader("Dependents (reverse)", style));
+    writer.writeLine(renderTree(input.reverse.map((path13) => ({ label: path13 }))));
     writer.writeLine();
   }
-  if (input.cycles.length > 0) {
-    writer.writeLine(sectionTitle("Circular Dependencies", style));
+  writer.writeLine(sectionHeader("Circular dependencies", style));
+  if (input.cycles.length === 0) {
+    writer.writeLine(dim("none", style));
+  } else {
     for (const cycle of input.cycles) {
       const chain = cycle.path.map((key) => {
         const node = input.nodes.get(key);
         return displayPath(node?.path ?? key, input.cwd);
-      }).join(" \u2192 ");
-      writer.writeLine(`\u2B55 ${chain}`);
+      }).join(` ${icon("arrowRight")} `);
+      writer.writeLine(`${icon("circle")} ${chain}`);
     }
-  } else {
-    writer.writeLine(dim("No circular dependencies found.", style));
   }
 }
 function buildGraphJsonReport(input, version) {
@@ -1209,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])
@@ -1219,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;
@@ -1234,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)
     );
@@ -1413,11 +1482,13 @@ async function analyzeCommand(fileArg, options, ctx2) {
   if (!await pathExists(targetPath)) {
     throw new RippleError(`File not found: ${fileArg}`, ExitCode.NotFound);
   }
-  const spinner = createSpinner(!options.json);
-  spinner.start("Analyzing project\u2026");
+  const tracker = createStageTracker(!options.json);
+  tracker.next("Loading config");
   const started = Date.now();
   const context = await loadProjectContext(ctx2.cwd, options.config);
+  tracker.next("Building dependency graph");
   const { graph, entryPoints, durationMs: pipelineMs } = await runPipeline(context);
+  tracker.next("Analyzing impact");
   const completed = Date.now();
   const result = analyzeFile({
     graph,
@@ -1428,7 +1499,7 @@ async function analyzeCommand(fileArg, options, ctx2) {
     durationMs: pipelineMs + (completed - started),
     ...options.depth !== void 0 ? { maxDepth: options.depth } : {}
   });
-  spinner.stop();
+  tracker.done();
   if (options.json) {
     const report = buildAnalyzeJsonReport(result, ctx2.version, ctx2.cwd);
     ctx2.writer.write(serializeJson(report));
@@ -1438,8 +1509,9 @@ async function analyzeCommand(fileArg, options, ctx2) {
     result,
     {
       cwd: ctx2.cwd,
-      color: options.color !== false,
-      verbose: options.verbose
+      color: resolveColor(options.color),
+      verbose: options.verbose,
+      version: ctx2.version
     },
     ctx2.writer
   );
@@ -1468,11 +1540,12 @@ function walk(graph, startKey, edges, maxDepth, cwd) {
   return entries.sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path)).map((entry) => entry.path);
 }
 async function graphCommand(fileArg, options, ctx2) {
-  const spinner = createSpinner(!options.json);
-  spinner.start(fileArg ? "Building dependency tree\u2026" : "Building graph\u2026");
+  const tracker = createStageTracker(!options.json);
+  tracker.next("Loading config");
   const cwd = ctx2.cwd;
   try {
     const context = await loadProjectContext(cwd, options.config);
+    tracker.next("Building graph");
     const { graph } = await runPipeline(context);
     const input = {
       stats: graph.stats,
@@ -1481,13 +1554,19 @@ async function graphCommand(fileArg, options, ctx2) {
       cwd
     };
     if (!fileArg) {
+      tracker.done();
       if (options.json) {
         const report = buildGraphJsonReport(input, ctx2.version);
         ctx2.writer.write(serializeJson(report));
       } else {
         renderGraphReport(
           input,
-          { cwd, color: options.color !== false, verbose: options.verbose },
+          {
+            cwd,
+            color: resolveColor(options.color),
+            verbose: options.verbose,
+            version: ctx2.version
+          },
           ctx2.writer
         );
       }
@@ -1497,6 +1576,7 @@ async function graphCommand(fileArg, options, ctx2) {
     const { key } = requireNode(graph, targetPath, context.rootDir);
     const dependants = walk(graph, key, graph.forward, options.depth, cwd);
     const dependents = walk(graph, key, graph.reverse, options.depth, cwd);
+    tracker.done();
     if (options.json) {
       const report = buildGraphJsonReport(
         {
@@ -1513,17 +1593,38 @@ async function graphCommand(fileArg, options, ctx2) {
           forward: options.reverse ? void 0 : dependants,
           reverse: options.reverse ? dependents : void 0
         },
-        { cwd, color: options.color !== false, verbose: options.verbose },
+        { cwd, color: resolveColor(options.color), verbose: options.verbose, version: ctx2.version },
         ctx2.writer
       );
     }
     return ExitCode.Success;
   } finally {
-    spinner.stop();
+    tracker.done();
   }
 }
+function createSpinner(enabled) {
+  if (!enabled || !process.stdout.isTTY) {
+    return { start: () => {
+    }, stop: () => {
+    } };
+  }
+  let instance;
+  return {
+    start(text) {
+      instance = ora(text).start();
+    },
+    stop() {
+      instance?.stop();
+      instance = void 0;
+    }
+  };
+}
+
+// src/commands/doctor.ts
 async function doctorCommand(options, ctx2) {
-  const spinner = createSpinner(options.color !== false);
+  const color = resolveColor(options.color);
+  const style = { color };
+  const spinner = createSpinner(color);
   spinner.start("Running diagnostics\u2026");
   const results = [];
   const check = (label, state, detail) => {
@@ -1548,7 +1649,7 @@ async function doctorCommand(options, ctx2) {
       context = await loadProjectContext(ctx2.cwd, options.config);
     } catch (error) {
       check("ripple config", "fail", error instanceof Error ? error.message : String(error));
-      renderResults(results, ctx2);
+      renderResults(results, ctx2, color);
       return ExitCode.InvalidConfig;
     }
     if (context.tsconfig) {
@@ -1597,29 +1698,39 @@ async function doctorCommand(options, ctx2) {
   } finally {
     spinner.stop();
   }
-  renderResults(results, ctx2);
+  renderResults(results, ctx2, color);
   const failed = results.some((check2) => check2.state === "fail");
   const warned = results.some((check2) => check2.state === "warn");
-  ctx2.writer.writeLine(
-    failed ? "\u2716 Diagnoses found problems." : warned ? "\u26A0 Diagnoses passed with warnings." : "\u2713 All checks passed."
-  );
+  const verdict = failed ? { icon: icon("cross"), text: "Diagnoses found problems.", color: chalk.red } : warned ? { icon: icon("warning"), text: "Diagnoses passed with warnings.", color: chalk.yellow } : { icon: icon("tick"), text: "All checks passed.", color: chalk.green };
+  const verdictIcon = style.color ? verdict.color(verdict.icon) : verdict.icon;
+  ctx2.writer.writeLine(`${verdictIcon} ${verdict.text}`);
   return failed ? ExitCode.Failure : ExitCode.Success;
 }
-function renderResults(results, ctx2) {
+function renderResults(results, ctx2, color) {
+  const style = { color };
+  ctx2.writer.writeLine(brandHeader({ label: "project health check", version: ctx2.version, style }));
+  ctx2.writer.writeLine();
+  const width = Math.max(...results.map((check) => check.label.length));
   for (const check of results) {
-    const icon = check.state === "ok" ? "\u2713" : check.state === "warn" ? "\u26A0" : "\u2716";
-    const suffix = check.detail ? ` ${check.detail}` : "";
-    ctx2.writer.writeLine(`${icon} ${check.label}${suffix}`);
+    const stateIcon = check.state === "ok" ? icon("tick") : check.state === "warn" ? icon("warning") : icon("cross");
+    const colored = check.state === "ok" ? chalk.green : check.state === "warn" ? chalk.yellow : chalk.red;
+    const mark = style.color ? colored(stateIcon) : stateIcon;
+    const detail = check.detail ? ` ${dim(check.detail, style)}` : "";
+    ctx2.writer.writeLine(`${mark} ${check.label.padEnd(width)}${detail}`);
   }
   ctx2.writer.writeLine();
 }
 var INIT_FILENAME = "ripple.config.json";
 async function initCommand(options, ctx2) {
+  const style = { color: resolveColor(options.color) };
   const target = path8.join(ctx2.cwd, INIT_FILENAME);
   try {
     await fs.access(target);
     if (!options.force) {
-      ctx2.writer.writeLine(`\u2716 ${INIT_FILENAME} already exists. Pass --force to overwrite it.`);
+      const mark = style.color ? chalk.red(icon("cross")) : icon("cross");
+      ctx2.writer.writeLine(
+        `${mark} ${INIT_FILENAME} already exists. Pass --force to overwrite it.`
+      );
       return ExitCode.Failure;
     }
   } catch {
@@ -1630,16 +1741,237 @@ async function initCommand(options, ctx2) {
   try {
     await fs.writeFile(target, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
-    ctx2.writer.writeLine(`\u2713 Wrote ${INIT_FILENAME}`);
-    ctx2.writer.writeLine(`  Edit it to tune include globs, aliases and risk weights.`);
+    const mark = style.color ? chalk.green(icon("tick")) : icon("tick");
+    ctx2.writer.writeLine(`${mark} Wrote ${INIT_FILENAME}`);
+    ctx2.writer.writeLine(
+      `  ${dim("Edit it to tune include globs, aliases and risk weights.", style)}`
+    );
     return ExitCode.Success;
   } catch (error) {
+    const mark = style.color ? chalk.red(icon("cross")) : icon("cross");
     ctx2.writer.writeLine(
-      `\u2716 Could not write ${INIT_FILENAME}: ${error instanceof Error ? error.message : String(error)}`
+      `${mark} Could not write ${INIT_FILENAME}: ${error instanceof Error ? error.message : String(error)}`
     );
     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";
@@ -1678,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(
       {
@@ -1691,8 +2044,11 @@ function createProgram(ctx2) {
       throw new ExitError(exitCode2);
     }
   });
-  program.command("init").description("Create a ripple.config.json with the default settings").option("-f, --force", "overwrite an existing config file").action(async (options) => {
-    const exitCode2 = await initCommand({ force: Boolean(options.force) }, ctx2);
+  program.command("init").description("Create a ripple.config.json with the default settings").option("-f, --force", "overwrite an existing config file").option("--no-color", "disable ANSI colors").action(async (options) => {
+    const exitCode2 = await initCommand(
+      { force: Boolean(options.force), color: options.color },
+      ctx2
+    );
     if (exitCode2 !== ExitCode.Success) {
       throw new ExitError(exitCode2);
     }
@@ -1700,6 +2056,11 @@ function createProgram(ctx2) {
   program.command("version").description("Print the Ripple version").action(() => {
     ctx2.writer.writeLine(ctx2.version);
   });
+  program.addHelpText(
+    "beforeAll",
+    `ripple \u2014 dependency impact analysis for TypeScript and JavaScript
+`
+  );
   return program;
 }
 var ExitError = class extends Error {
@@ -1721,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}`);
@@ -1754,7 +2125,7 @@ async function run({ argv, ctx: ctx2 }) {
 
 // package.json
 var package_default = {
-  version: "0.1.1"};
+  version: "0.3.0"};
 
 // src/cli/bin.ts
 var ctx = {