@alimaandev/ripple 0.5.0 → 0.7.0

package/dist/bin.js

@@ -1,18 +1,20 @@
 #!/usr/bin/env node
-import { DEFAULT_CONFIG, rippleConfigSchema, formatSchemaIssues } from './chunk-LDCFNORX.js';
+import { rippleConfigSchema, DEFAULT_CONFIG, formatSchemaIssues } from './chunk-CFH4UW2E.js';
 import { CommanderError, Command } from 'commander';
 import { createJiti } from 'jiti';
 import path8 from 'path';
-import fs from 'fs/promises';
+import fs3 from 'fs/promises';
 import fs2 from 'fs';
 import { Project, ts, SyntaxKind } from 'ts-morph';
 import chalk from 'chalk';
 import figures from 'figures';
 import treeify from 'treeify';
-import boxen from 'boxen';
+import { createHash } from 'crypto';
 import fg from 'fast-glob';
 import ora from 'ora';
+import picomatch from 'picomatch';
 import { execFileSync } from 'child_process';
+import { createInterface } from 'readline';
 
 // src/output/writer.ts
 var TerminalWriter = class {
@@ -38,7 +40,7 @@ var ExitCode = {
 };
 async function pathExists(filePath) {
   try {
-    await fs.access(filePath);
+    await fs3.access(filePath);
     return true;
   } catch {
     return false;
@@ -54,7 +56,7 @@ function pathExistsSync(filePath) {
 }
 async function readFileSafe(filePath) {
   try {
-    return await fs.readFile(filePath, "utf8");
+    return await fs3.readFile(filePath, "utf8");
   } catch {
     return void 0;
   }
@@ -269,8 +271,8 @@ async function loadProjectContext(cwd, explicitConfigPath) {
 function cycleMemberPaths(graph) {
   const members = /* @__PURE__ */ new Set();
   for (const cycle of graph.cycles) {
-    for (const path13 of cycle.members) {
-      members.add(path13);
+    for (const path15 of cycle.members) {
+      members.add(path15);
     }
   }
   return members;
@@ -393,6 +395,7 @@ function createCategorizer(options) {
   };
 }
 async function detectEntryPoints(rootDir) {
+  const started = Date.now();
   const entryPoints = /* @__PURE__ */ new Set();
   const packageJsonPath = await findPackageJson(rootDir);
   if (packageJsonPath) {
@@ -411,6 +414,9 @@ async function detectEntryPoints(rootDir) {
       }
     }
   }
+  if (process.env.RIPPLE_TRACE === "1") {
+    console.error(`[trace] detectEntryPoints: ${Date.now() - started}ms`);
+  }
   return entryPoints;
 }
 
@@ -507,7 +513,7 @@ function reverseTraverse(graph, targetKey, options) {
   const { maxDepth, categorize } = options;
   const affected = /* @__PURE__ */ new Map();
   const visited = /* @__PURE__ */ new Set([targetKey]);
-  const cycleMembers = cycleMemberPaths(graph);
+  const cycleMembers2 = cycleMemberPaths(graph);
   if (!graph.reverse.has(targetKey)) {
     return { affected, maxDepth: 0 };
   }
@@ -529,7 +535,7 @@ function reverseTraverse(graph, targetKey, options) {
       depth: current.depth,
       direct: current.depth === 1,
       categories: categorize(filePath),
-      inCycle: cycleMembers.has(current.key)
+      inCycle: cycleMembers2.has(current.key)
     });
     if (maxDepth === void 0 || current.depth < maxDepth) {
       for (const importer of graph.reverse.get(current.key) ?? []) {
@@ -786,24 +792,17 @@ function renderTree(nodes) {
   }
   return treeify.asTree(root, false, false).trimEnd();
 }
-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"
-  });
+  const title = chalk.bold.cyan(`ripple \xB7 ${label}`);
+  return `${title}${version ? ` ${chalk.dim(`\xB7 v${version}`)}` : ""}`;
 }
 function sectionHeader(title, style) {
   if (!style.color) return title;
-  return `${chalk.dim("\u2500".repeat(DIVIDER_WIDTH))}
-${chalk.bold(title)}`;
+  return `${chalk.dim("\u203A")} ${chalk.bold(title)}`;
 }
 
 // src/ui/gauge.ts
@@ -981,12 +980,12 @@ function renderGraphReport(input, options, writer) {
   writer.writeLine();
   if (input.forward) {
     writer.writeLine(sectionHeader("Dependants (forward)", style));
-    writer.writeLine(renderTree(input.forward.map((path13) => ({ label: path13 }))));
+    writer.writeLine(renderTree(input.forward.map((path15) => ({ label: path15 }))));
     writer.writeLine();
   }
   if (input.reverse) {
     writer.writeLine(sectionHeader("Dependents (reverse)", style));
-    writer.writeLine(renderTree(input.reverse.map((path13) => ({ label: path13 }))));
+    writer.writeLine(renderTree(input.reverse.map((path15) => ({ label: path15 }))));
     writer.writeLine();
   }
   writer.writeLine(sectionHeader("Circular dependencies", style));
@@ -1025,6 +1024,158 @@ function serializeJson(report) {
   return `${JSON.stringify(report, null, 2)}
 `;
 }
+var LEVEL_INDEX = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
+var GATE_INDEX = { medium: 1, high: 2, critical: 3 };
+var INFORMATION_URI = "https://github.com/alimaandev/ripple";
+function riskToSarifLevel(level) {
+  switch (level) {
+    case "CRITICAL":
+    case "HIGH":
+      return "error";
+    case "MEDIUM":
+      return "warning";
+    default:
+      return "note";
+  }
+}
+function primaryLocationHash(ruleId, uri, score) {
+  return createHash("sha256").update(`${ruleId}|${uri}|${score.toFixed(1)}`).digest("hex");
+}
+var RISK_RULE = {
+  id: "ripple/risk",
+  name: "riskScore",
+  shortDescription: {
+    text: "Risk of changing a file's blast radius"
+  },
+  fullDescription: {
+    text: "Ripple scores how risky a change to a file is \u2014 its impact area, affected files, and circular-dependency membership \u2014 and gates merges on the resulting level."
+  },
+  defaultConfiguration: { level: "warning" },
+  properties: { tags: ["ripple", "impact-analysis"] }
+};
+function fileResult(entry, gate) {
+  const { rel, result, allowed } = entry;
+  const level = allowed ? "note" : riskToSarifLevel(result.risk.level);
+  const blocked = LEVEL_INDEX[result.risk.level] >= GATE_INDEX[gate];
+  const score = result.risk.score.toFixed(1);
+  const affected = result.summary.affectedFiles;
+  const message = allowed ? `Allowlisted: ${result.risk.level} risk (${score}/100) - ${affected} affected file(s)` : `${result.risk.level} risk (${score}/100) - ${affected} affected file(s)`;
+  const entryResult = {
+    ruleId: "ripple/risk",
+    level,
+    message: { text: message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: rel },
+          region: { startLine: 1 }
+        }
+      }
+    ],
+    partialFingerprints: {
+      primaryLocationLineHash: primaryLocationHash("ripple/risk", rel, result.risk.score)
+    },
+    properties: {
+      ripple: {
+        score: result.risk.score,
+        level: result.risk.level,
+        affectedFiles: result.summary.affectedFiles,
+        targetInCycle: result.targetInCycle,
+        allowed,
+        blocked,
+        gate
+      }
+    }
+  };
+  if (allowed) {
+    entryResult.suppressions = [
+      { kind: "inSource", justification: "Allowlisted via diff.allow in ripple config" }
+    ];
+  }
+  return entryResult;
+}
+function buildDiffSarif(options) {
+  const { baseLabel, entries, gate, counts, blocked, durationMs, version } = options;
+  const results = entries.map((entry) => fileResult(entry, gate));
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "ripple",
+            fullName: "Ripple \u2014 dependency impact analysis",
+            informationUri: INFORMATION_URI,
+            version,
+            rules: [RISK_RULE]
+          }
+        },
+        results,
+        properties: {
+          ripple: {
+            command: "diff",
+            base: baseLabel,
+            gate,
+            blocked,
+            counts,
+            durationMs
+          }
+        }
+      }
+    ]
+  };
+}
+function buildAnalyzeSarif(options) {
+  const { result, cwd, version } = options;
+  const rel = result.targetPath.slice(cwd.length).replace(/^[/\\]+/, "").replace(/\\/g, "/");
+  const uri = rel || result.targetPath;
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "ripple",
+            fullName: "Ripple \u2014 dependency impact analysis",
+            informationUri: INFORMATION_URI,
+            version,
+            rules: [RISK_RULE]
+          }
+        },
+        results: [
+          {
+            ruleId: "ripple/risk",
+            level: riskToSarifLevel(result.risk.level),
+            message: {
+              text: `${result.risk.level} risk (${result.risk.score.toFixed(1)}/100) - ${result.summary.affectedFiles} affected file(s)`
+            },
+            locations: [
+              {
+                physicalLocation: {
+                  artifactLocation: { uri },
+                  region: { startLine: 1 }
+                }
+              }
+            ],
+            partialFingerprints: {
+              primaryLocationLineHash: primaryLocationHash("ripple/risk", uri, result.risk.score)
+            },
+            properties: {
+              ripple: {
+                score: result.risk.score,
+                level: result.risk.level,
+                affectedFiles: result.summary.affectedFiles,
+                targetInCycle: result.targetInCycle
+              }
+            }
+          }
+        ]
+      }
+    ]
+  };
+}
 function createTsProject() {
   return new Project({
     skipAddingFilesFromTsConfig: true,
@@ -1064,7 +1215,7 @@ function isSourceFile(filePath) {
 
 // src/scanner/discover.ts
 async function discoverSourceFiles(options) {
-  const ignoreGlobs = options.ignore.map(toIgnoreGlob).filter((glob) => glob !== "").concat(["**/node_modules/**"]);
+  const ignoreGlobs = options.ignore.map(toIgnoreGlob).filter((glob) => glob !== "").concat(["**/node_modules/**", "**/.ripple/**"]);
   const files = await globFiles({
     cwd: options.rootDir,
     patterns: options.include,
@@ -1206,13 +1357,24 @@ function parseSourceFile(project, filePath) {
       parseError: error instanceof Error ? error.message : String(error)
     };
   }
-  return {
-    path: filePath,
-    kind: sourceFileKind(filePath) ?? "ts",
-    imports: extractImports(sourceFile),
-    exports: extractExports(sourceFile),
-    symbols: extractSymbols(sourceFile)
-  };
+  try {
+    return {
+      path: filePath,
+      kind: sourceFileKind(filePath) ?? "ts",
+      imports: extractImports(sourceFile),
+      exports: extractExports(sourceFile),
+      symbols: extractSymbols(sourceFile)
+    };
+  } catch (error) {
+    return {
+      path: filePath,
+      kind: sourceFileKind(filePath) ?? "ts",
+      imports: [],
+      exports: { named: [], hasDefault: false, reExportedFrom: [], reExportedAll: [] },
+      symbols: { functions: [], classes: [], interfaces: [], enums: [], typeAliases: [] },
+      parseError: error instanceof Error ? error.message : String(error)
+    };
+  }
 }
 function parseMany(project, filePaths) {
   return filePaths.map((filePath) => parseSourceFile(project, filePath));
@@ -1278,8 +1440,8 @@ function findCycles(graph) {
     }
     const members = [...component].sort();
     const componentSet = new Set(component);
-    const path13 = representativeCyclePath(graph, component, componentSet);
-    cycles.push({ members, path: path13 ?? [members[0], members[0]] });
+    const path15 = representativeCyclePath(graph, component, componentSet);
+    cycles.push({ members, path: path15 ?? [members[0], members[0]] });
   }
   cycles.sort(
     (a, b) => a.members.length - b.members.length || a.members[0].localeCompare(b.members[0])
@@ -1288,14 +1450,14 @@ function findCycles(graph) {
 }
 function representativeCyclePath(graph, component, componentSet) {
   const inPath = /* @__PURE__ */ new Set();
-  const path13 = [];
+  const path15 = [];
   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 = path13.indexOf(current);
+      const start = path15.indexOf(current);
       if (start === -1) return void 0;
-      const cycle = path13.slice(start);
+      const cycle = path15.slice(start);
       if (cycle.length > 1 || graph.forward.get(current)?.has(current)) {
         cycle.push(current);
         return cycle;
@@ -1303,7 +1465,7 @@ function representativeCyclePath(graph, component, componentSet) {
       return void 0;
     }
     inPath.add(current);
-    path13.push(current);
+    path15.push(current);
     const next = [...graph.forward.get(current) ?? []].find(
       (candidate) => componentSet.has(candidate)
     );
@@ -1386,13 +1548,20 @@ function resolveImports(fromPath, importSpecifiers, context) {
 
 // src/graph/build.ts
 function buildGraph(project, filePaths, context) {
-  const parsedFiles = parseMany(project, filePaths);
+  return buildGraphFromParsed(parseMany(project, filePaths), context);
+}
+function buildGraphFromParsed(parsedFiles, context) {
+  const started = Date.now();
+  const trace = process.env.RIPPLE_TRACE === "1";
+  const mark = (label) => {
+    if (trace) console.error(`[trace] graph.${label}: ${Date.now() - started}ms`);
+  };
   const nodes = /* @__PURE__ */ new Map();
   const forward = /* @__PURE__ */ new Map();
   const reverse = /* @__PURE__ */ new Map();
   const external = /* @__PURE__ */ new Map();
   let parsedCount = 0;
-  let internalEdges = 0;
+  let internalEdges2 = 0;
   let unresolvedEdges = 0;
   let externalEdges = 0;
   for (const parsed of parsedFiles) {
@@ -1400,6 +1569,7 @@ function buildGraph(project, filePaths, context) {
     nodes.set(key, { path: parsed.path, parsed });
     if (!parsed.parseError) parsedCount++;
   }
+  mark("nodes");
   for (const parsed of parsedFiles) {
     const fromKey = pathKey(parsed.path, context.rootDir);
     const targets = /* @__PURE__ */ new Set();
@@ -1412,7 +1582,7 @@ function buildGraph(project, filePaths, context) {
       parsed.imports.map((decl) => decl.raw),
       context
     );
-    internalEdges += internal.length;
+    internalEdges2 += internal.length;
     unresolvedEdges += unresolved.length;
     externalEdges += externalSpecifiers.length;
     for (const target of internal) {
@@ -1437,32 +1607,212 @@ function buildGraph(project, filePaths, context) {
     stats: {
       files: parsedFiles.length,
       parsed: parsedCount,
-      internalEdges,
+      internalEdges: internalEdges2,
       unresolvedEdges,
       externalEdges,
       cycles: 0
     }
   };
+  mark("edges");
   graph.cycles = findCycles(graph);
   graph.stats.cycles = graph.cycles.length;
+  mark("cycles");
   return graph;
 }
+var CACHE_SCHEMA = 2;
+var CACHE_FILE = path8.join(".ripple", "cache", "parsed-v2.json");
+var cacheEnabled = () => process.env.RIPPLE_NO_CACHE !== "1";
+async function contentHash(filePath) {
+  const bytes = await fs3.readFile(filePath);
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function configCacheHash(config) {
+  const stable = {
+    include: [...config.include].sort(),
+    ignore: [...config.ignore].sort()
+  };
+  return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
+}
+function relPosix(rootDir, absPath) {
+  return toPosix(path8.relative(rootDir, absPath));
+}
+function cachePath(rootDir) {
+  return path8.join(rootDir, CACHE_FILE);
+}
+async function loadParsedCache(rootDir, configHash) {
+  let raw;
+  try {
+    raw = await fs3.readFile(cachePath(rootDir), "utf8");
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+  try {
+    const manifest = JSON.parse(raw);
+    if (manifest.schema !== CACHE_SCHEMA || manifest.configHash !== configHash) {
+      return /* @__PURE__ */ new Map();
+    }
+    return new Map(Object.entries(manifest.files ?? {}));
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
+async function saveParsedCache(rootDir, configHash, entries) {
+  const manifest = {
+    schema: CACHE_SCHEMA,
+    configHash,
+    files: Object.fromEntries(entries)
+  };
+  const target = cachePath(rootDir);
+  const tmp = target + ".tmp";
+  try {
+    await fs3.mkdir(path8.dirname(target), { recursive: true });
+    await fs3.writeFile(tmp, JSON.stringify(manifest), "utf8");
+    await fs3.rename(tmp, target);
+  } catch {
+    try {
+      await fs3.rm(tmp, { force: true });
+    } catch {
+    }
+  }
+}
+async function loadParsedFiles(options) {
+  const { project, rootDir, filePaths, config } = options;
+  if (!cacheEnabled()) {
+    return {
+      parsedFiles: parseMany(project, filePaths),
+      stats: { hits: 0, misses: filePaths.length }
+    };
+  }
+  const configHash = configCacheHash(config);
+  const cached = await loadParsedCache(rootDir, configHash);
+  const trace = process.env.RIPPLE_TRACE === "1";
+  const traceAt = (label, from) => {
+    if (trace) console.error(`[trace] cache.${label}: ${Date.now() - from}ms`);
+    return Date.now();
+  };
+  let stage = Date.now();
+  const states = await Promise.all(
+    filePaths.map(async (abs) => {
+      try {
+        const stat = await fs3.stat(abs);
+        return { abs, rel: relPosix(rootDir, abs), size: stat.size, mtimeMs: stat.mtimeMs };
+      } catch {
+        return { abs, rel: relPosix(rootDir, abs), size: -1, mtimeMs: -1 };
+      }
+    })
+  );
+  stage = traceAt("load-cache", stage);
+  const hits = /* @__PURE__ */ new Map();
+  const stale = [];
+  const parsed = /* @__PURE__ */ new Map();
+  let dirty = false;
+  for (const state of states) {
+    const entry = cached.get(state.rel);
+    if (entry !== void 0 && entry.size === state.size && entry.mtimeMs === state.mtimeMs && state.mtimeMs > 0) {
+      hits.set(state.rel, entry);
+      parsed.set(state.rel, { ...entry.parsed, path: state.abs });
+      continue;
+    }
+    let hash = "";
+    try {
+      hash = await contentHash(state.abs);
+    } catch {
+    }
+    if (entry !== void 0 && entry.hash === hash) {
+      if (entry.mtimeMs !== state.mtimeMs || entry.size !== state.size) {
+        hits.set(state.rel, { ...entry, size: state.size, mtimeMs: state.mtimeMs });
+        dirty = true;
+      } else {
+        hits.set(state.rel, entry);
+      }
+      parsed.set(state.rel, { ...entry.parsed, path: state.abs });
+    } else {
+      stale.push(state.abs);
+      dirty = true;
+    }
+  }
+  if (stale.length > 0) {
+    for (const filePath of stale) {
+      project.getSourceFile(filePath)?.forget();
+    }
+    for (const parsedFile of parseMany(project, stale)) {
+      parsed.set(relPosix(rootDir, parsedFile.path), parsedFile);
+    }
+  }
+  traceAt("freshness+parse", stage);
+  if (dirty) {
+    const next = new Map(hits);
+    for (const parsedFile of parsed.values()) {
+      const rel = relPosix(rootDir, parsedFile.path);
+      if (next.has(rel)) continue;
+      const state = states.find((candidate) => candidate.rel === rel);
+      let hash = "";
+      try {
+        hash = await contentHash(parsedFile.path);
+      } catch {
+      }
+      next.set(rel, {
+        hash,
+        size: state?.size ?? -1,
+        mtimeMs: state?.mtimeMs ?? -1,
+        parsed: { ...parsedFile, path: rel }
+      });
+    }
+    await saveParsedCache(rootDir, configHash, next);
+    traceAt("save", stage);
+  }
+  const parsedFiles = filePaths.map((abs) => {
+    const rel = relPosix(rootDir, abs);
+    const parsedFile = parsed.get(rel);
+    if (parsedFile === void 0) {
+      return {
+        path: abs,
+        kind: "ts",
+        imports: [],
+        exports: { named: [], hasDefault: false, reExportedFrom: [], reExportedAll: [] },
+        symbols: { functions: [], classes: [], interfaces: [], enums: [], typeAliases: [] },
+        parseError: "file disappeared during discovery"
+      };
+    }
+    return parsedFile;
+  });
+  return {
+    parsedFiles,
+    stats: { hits: hits.size, misses: stale.length }
+  };
+}
 
 // src/commands/pipeline.ts
 async function runPipeline(context) {
   const started = Date.now();
+  const trace = process.env.RIPPLE_TRACE === "1";
+  const mark = (label) => {
+    if (trace) console.error(`[trace] pipeline.${label}: ${Date.now() - started}ms`);
+  };
   const project = createTsProject();
+  mark("ts-project");
   const filePaths = await discoverSourceFiles({
     rootDir: context.rootDir,
     include: context.config.include,
     ignore: context.config.ignore
   });
-  const graph = buildGraph(project, filePaths, {
+  mark("discover");
+  const { parsedFiles, stats } = await loadParsedFiles({
+    project,
+    rootDir: context.rootDir,
+    filePaths,
+    config: context.config
+  });
+  if (trace) console.error(`[trace] cache: ${stats.hits} hits, ${stats.misses} misses`);
+  mark("parsed");
+  const graph = buildGraphFromParsed(parsedFiles, {
     rootDir: context.rootDir,
     aliases: context.aliases,
     fileKeys: new Set(filePaths.map((p) => pathKey(p, context.rootDir)))
   });
+  mark("graph");
   const entryPoints = await detectEntryPoints(context.rootDir);
+  mark("entry-points");
   return { graph, filePaths, entryPoints, durationMs: Date.now() - started };
 }
 function resolveTargetFile(fileArg, cwd) {
@@ -1505,6 +1855,12 @@ async function analyzeCommand(fileArg, options, ctx2) {
     ctx2.writer.write(serializeJson(report));
     return ExitCode.Success;
   }
+  if (options.sarif) {
+    ctx2.writer.write(
+      serializeJson(buildAnalyzeSarif({ result, cwd: ctx2.cwd, version: ctx2.version }))
+    );
+    return ExitCode.Success;
+  }
   renderAnalyzeReport(
     result,
     {
@@ -1518,6 +1874,150 @@ async function analyzeCommand(fileArg, options, ctx2) {
   return ExitCode.Success;
 }
 
+// src/formatter/graph-export.ts
+var escapeDot = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+var escapeMermaid = (value) => value.replace(/#/g, "#35;").replace(/"/g, "#quot;");
+var escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+function sortedKeys(input) {
+  return [...input.nodes.keys()].sort((a, b) => {
+    const left = input.nodes.get(a) ?? a;
+    const right = input.nodes.get(b) ?? b;
+    return left.localeCompare(right);
+  });
+}
+var nodeLabel = (input, key) => displayPath(input.nodes.get(key) ?? key, input.cwd);
+function cycleMembers(input) {
+  const present = /* @__PURE__ */ new Set();
+  for (const cycle of input.cycles) {
+    for (const member of cycle.members) {
+      if (input.nodes.has(member)) present.add(member);
+    }
+  }
+  return [...present].sort((a, b) => nodeLabel(input, a).localeCompare(nodeLabel(input, b)));
+}
+function internalEdges(input) {
+  const pairs = [];
+  for (const [source, targets] of input.edges) {
+    if (!input.nodes.has(source)) continue;
+    for (const target of targets) {
+      if (!input.nodes.has(target)) continue;
+      pairs.push([source, target]);
+    }
+  }
+  return pairs.sort((a, b) => {
+    const left = nodeLabel(input, a[0]).localeCompare(nodeLabel(input, b[0]));
+    return left !== 0 ? left : nodeLabel(input, a[1]).localeCompare(nodeLabel(input, b[1]));
+  });
+}
+function renderMermaidGraph(input) {
+  const keys = sortedKeys(input);
+  const idByKey = new Map(keys.map((key, index) => [key, `n${index}`]));
+  const lines = ["flowchart LR"];
+  lines.push("  classDef cycle fill:#4a2525,stroke:#f85149,color:#f0b3b3;");
+  for (const key of keys) {
+    lines.push(`  ${idByKey.get(key)}["${escapeMermaid(nodeLabel(input, key))}"]`);
+  }
+  for (const [source, target] of internalEdges(input)) {
+    lines.push(`  ${idByKey.get(source)} --> ${idByKey.get(target)}`);
+  }
+  const members = cycleMembers(input).map((key) => idByKey.get(key)).filter((id) => id !== void 0);
+  if (members.length > 0) {
+    lines.push(`  class ${members.join(",")} cycle;`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderDotGraph(input) {
+  const lines = [
+    "digraph ripple {",
+    "  rankdir=LR;",
+    '  node [shape=box, style="rounded,filled", fillcolor="#161b22", color="#30363d", fontcolor="#e6edf3"];',
+    '  edge [color="#8b949e"];'
+  ];
+  for (const key of sortedKeys(input)) {
+    const label = nodeLabel(input, key);
+    lines.push(`  "${escapeDot(label)}" [label="${escapeDot(label)}"];`);
+  }
+  for (const [source, target] of internalEdges(input)) {
+    lines.push(
+      `  "${escapeDot(nodeLabel(input, source))}" -> "${escapeDot(nodeLabel(input, target))}";`
+    );
+  }
+  for (const key of cycleMembers(input)) {
+    const label = nodeLabel(input, key);
+    lines.push(`  "${escapeDot(label)}" [color="#f85149", penwidth=1.5];`);
+  }
+  lines.push("}");
+  return `${lines.join("\n")}
+`;
+}
+function renderHtmlGraph(input) {
+  const keys = sortedKeys(input);
+  const edges = internalEdges(input);
+  const members = cycleMembers(input);
+  const cycleLines = input.cycles.map(
+    (cycle) => cycle.path.filter((key) => input.nodes.has(key)).map((key) => escapeHtml(nodeLabel(input, key))).join(" &#8594; ")
+  ).filter((line) => line.length > 0);
+  const edgeRows = edges.map(
+    ([source, target]) => `      <tr><td>${escapeHtml(nodeLabel(input, source))}</td><td>&#8594;</td><td>${escapeHtml(nodeLabel(input, target))}</td></tr>`
+  ).join("\n");
+  const cycleRows = cycleLines.length > 0 ? cycleLines.map((line) => `      <li><code>${line}</code></li>`).join("\n") : "      <li><em>none</em></li>";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ripple \u2014 dependency graph</title>
+<style>
+  :root { color-scheme: dark; }
+  body { margin: 0; padding: 2rem; background: #0d1117; color: #e6edf3;
+         font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+  h1 { font-size: 1.4rem; margin: 0 0 .25rem; }
+  h2 { font-size: 1.05rem; margin: 2rem 0 .5rem; color: #79c0ff; }
+  code, pre { font-family: SFMono-Regular, Consolas, monospace; }
+  pre { background: #161b22; border: 1px solid #30363d; border-radius: 8px;
+        padding: 1rem; overflow-x: auto; font-size: .85rem; }
+  table { border-collapse: collapse; width: 100%; font-size: .9rem; }
+  th, td { text-align: left; padding: .35rem .6rem; border-bottom: 1px solid #21262d; }
+  th { color: #8b949e; font-weight: 600; }
+  .stats { display: flex; gap: 1.5rem; margin-top: 1rem; }
+  .stat b { display: block; font-size: 1.6rem; color: #79c0ff; }
+  .stat span { color: #8b949e; font-size: .8rem; }
+  .muted { color: #8b949e; }
+  a { color: #79c0ff; }
+</style>
+</head>
+<body>
+  <h1>Ripple dependency graph</h1>
+  <p class="muted">Exported with <code>ripple graph --format html</code> \u2014 deterministic and offline.</p>
+  <div class="stats">
+    <div class="stat"><b>${keys.length}</b><span>files</span></div>
+    <div class="stat"><b>${edges.length}</b><span>edges</span></div>
+    <div class="stat"><b>${input.cycles.length}</b><span>cycle groups</span></div>
+  </div>
+
+  <h2>Circular dependencies</h2>
+  <ul>${cycleRows}</ul>
+  <p class="muted">Cycle members: ${members.map(escapeHtml).join(", ")}</p>
+
+  <h2>Graph</h2>
+  <pre><code class="language-mermaid">${escapeHtml(renderMermaidGraph(input)).trimEnd()}</code></pre>
+  <p class="muted">Render this diagram with the
+    <a href="https://mermaid.live">Mermaid live editor</a> or a tool that
+    understands Mermaid (GitHub markdown, docs sites, IDEs).</p>
+
+  <h2>Edges (${edges.length})</h2>
+  <table>
+    <thead><tr><th>Source</th><th></th><th>Target</th></tr></thead>
+    <tbody>
+${edgeRows}
+    </tbody>
+  </table>
+</body>
+</html>
+`;
+}
+
 // src/commands/graph.ts
 function walk(graph, startKey, edges, maxDepth, cwd) {
   const seen = /* @__PURE__ */ new Set([startKey]);
@@ -1539,8 +2039,36 @@ 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);
 }
+function reachableSubgraph(graph, startKey, reverse, maxDepth, cwd) {
+  const edges = reverse ? graph.reverse : graph.forward;
+  const nodes = /* @__PURE__ */ new Map();
+  const visited = /* @__PURE__ */ new Set([startKey]);
+  const queue = [{ key: startKey, depth: 0 }];
+  const collectedEdges = /* @__PURE__ */ new Map();
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    nodes.set(current.key, graph.nodes.get(current.key)?.path ?? current.key);
+    if (maxDepth !== void 0 && current.depth >= maxDepth) continue;
+    const targets = /* @__PURE__ */ new Set();
+    for (const candidate of edges.get(current.key) ?? []) {
+      targets.add(candidate);
+      if (!visited.has(candidate)) {
+        visited.add(candidate);
+        queue.push({ key: candidate, depth: current.depth + 1 });
+      }
+    }
+    if (targets.size > 0) collectedEdges.set(current.key, targets);
+  }
+  return { nodes, edges: collectedEdges, cycles: graph.cycles, cwd };
+}
+function writeExport(format, input, writer) {
+  const rendered = format === "mermaid" ? renderMermaidGraph(input) : format === "dot" ? renderDotGraph(input) : renderHtmlGraph(input);
+  writer.write(rendered);
+}
 async function graphCommand(fileArg, options, ctx2) {
-  const tracker = createStageTracker(!options.json);
+  const format = options.format ?? (options.json ? "json" : "terminal");
+  const tracker = createStageTracker(format === "terminal");
   tracker.next("Loading config");
   const cwd = ctx2.cwd;
   try {
@@ -1553,9 +2081,24 @@ async function graphCommand(fileArg, options, ctx2) {
       nodes: graph.nodes,
       cwd
     };
+    if (format === "mermaid" || format === "dot" || format === "html") {
+      let exportInput;
+      if (fileArg) {
+        const targetPath2 = resolveTargetFile(fileArg, cwd);
+        const { key: key2 } = requireNode(graph, targetPath2, context.rootDir);
+        exportInput = reachableSubgraph(graph, key2, options.reverse, options.depth, cwd);
+      } else {
+        const nodes = /* @__PURE__ */ new Map();
+        for (const [key2, node] of graph.nodes) nodes.set(key2, node.path);
+        exportInput = { nodes, edges: graph.forward, cycles: graph.cycles, cwd };
+      }
+      tracker.done();
+      writeExport(format, exportInput, ctx2.writer);
+      return ExitCode.Success;
+    }
     if (!fileArg) {
       tracker.done();
-      if (options.json) {
+      if (format === "json") {
         const report = buildGraphJsonReport(input, ctx2.version);
         ctx2.writer.write(serializeJson(report));
       } else {
@@ -1577,7 +2120,7 @@ async function graphCommand(fileArg, options, ctx2) {
     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) {
+    if (format === "json") {
       const report = buildGraphJsonReport(
         {
           ...input,
@@ -1720,29 +2263,72 @@ function renderResults(results, ctx2, color) {
   }
   ctx2.writer.writeLine();
 }
-var INIT_FILENAME = "ripple.config.json";
+var SCHEMA_REF = "./node_modules/@alimaandev/ripple/ripple.schema.json";
+function jsonPayload(full) {
+  const payload = full ? { ...DEFAULT_CONFIG } : { include: DEFAULT_CONFIG.include };
+  return { ...payload, $schema: SCHEMA_REF };
+}
+function tsValue(value, indent) {
+  if (value === void 0) return "undefined";
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const items = value.map((item) => tsValue(item, `${indent}  `)).join(`,
+${indent}  `);
+    return `[
+${indent}  ${items}
+${indent}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.entries(value).filter(
+      ([, entry]) => entry !== void 0
+    );
+    if (entries.length === 0) return "{}";
+    const items = entries.map(([key, entry]) => `${key}: ${tsValue(entry, `${indent}  `)}`).join(`,
+${indent}  `);
+    return `{
+${indent}  ${items}
+${indent}}`;
+  }
+  return JSON.stringify(value);
+}
+function tsPayload(full) {
+  if (!full) {
+    return `import type { RippleConfig } from "@alimaandev/ripple";
+
+const config: RippleConfig = {
+  include: ${JSON.stringify(DEFAULT_CONFIG.include)},
+};
+
+export default config;
+`;
+  }
+  const body = tsValue({ ...DEFAULT_CONFIG }, "  ");
+  return `import type { RippleConfig } from "@alimaandev/ripple";
+
+const config: RippleConfig = ${body};
+
+export default config;
+`;
+}
 async function initCommand(options, ctx2) {
   const style = { color: resolveColor(options.color) };
-  const target = path8.join(ctx2.cwd, INIT_FILENAME);
+  const fileName = options.ts ? "ripple.config.ts" : "ripple.config.json";
+  const target = path8.join(ctx2.cwd, fileName);
   try {
-    await fs.access(target);
+    await fs3.access(target);
     if (!options.force) {
       const mark = style.color ? chalk.red(icon("cross")) : icon("cross");
-      ctx2.writer.writeLine(
-        `${mark} ${INIT_FILENAME} already exists. Pass --force to overwrite it.`
-      );
+      ctx2.writer.writeLine(`${mark} ${fileName} already exists. Pass --force to overwrite it.`);
       return ExitCode.Failure;
     }
   } catch {
   }
-  const payload = {
-    ...DEFAULT_CONFIG
-  };
+  const content = options.ts ? tsPayload(Boolean(options.full)) : `${JSON.stringify(jsonPayload(Boolean(options.full)), null, 2)}
+`;
   try {
-    await fs.writeFile(target, `${JSON.stringify(payload, null, 2)}
-`, "utf8");
+    await fs3.writeFile(target, content, "utf8");
     const mark = style.color ? chalk.green(icon("tick")) : icon("tick");
-    ctx2.writer.writeLine(`${mark} Wrote ${INIT_FILENAME}`);
+    ctx2.writer.writeLine(`${mark} Wrote ${fileName}`);
     ctx2.writer.writeLine(
       `  ${dim("Edit it to tune include globs, aliases and risk weights.", style)}`
     );
@@ -1750,7 +2336,7 @@ async function initCommand(options, ctx2) {
   } catch (error) {
     const mark = style.color ? chalk.red(icon("cross")) : icon("cross");
     ctx2.writer.writeLine(
-      `${mark} Could not write ${INIT_FILENAME}: ${error instanceof Error ? error.message : String(error)}`
+      `${mark} Could not write ${fileName}: ${error instanceof Error ? error.message : String(error)}`
     );
     return ExitCode.Failure;
   }
@@ -1807,8 +2393,8 @@ function changedFiles(cwd, base) {
 }
 
 // src/formatter/annotations.ts
-var LEVEL_INDEX = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
-var GATE_INDEX = { medium: 1, high: 2, critical: 3 };
+var LEVEL_INDEX2 = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
+var GATE_INDEX2 = { medium: 1, high: 2, critical: 3 };
 function escapeProperty(value) {
   return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/:/g, "%3A").replace(/,/g, "%2C");
 }
@@ -1821,7 +2407,7 @@ function renderAnnotation(annotation) {
 }
 function buildFileAnnotations(files, gate) {
   return files.map(({ file, result }) => {
-    const blocked = LEVEL_INDEX[result.risk.level] >= GATE_INDEX[gate];
+    const blocked = LEVEL_INDEX2[result.risk.level] >= GATE_INDEX2[gate];
     return {
       level: blocked ? "error" : "warning",
       file,
@@ -1831,12 +2417,12 @@ function buildFileAnnotations(files, gate) {
   });
 }
 function buildGateAnnotation(blocked, gate, counts) {
-  const gateIndex = GATE_INDEX[gate];
+  const gateIndex = GATE_INDEX2[gate];
   const parts = [];
-  if (LEVEL_INDEX.CRITICAL >= gateIndex && counts.critical > 0)
+  if (LEVEL_INDEX2.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_INDEX2.HIGH >= gateIndex && counts.high > 0) parts.push(`${counts.high} HIGH`);
+  if (LEVEL_INDEX2.MEDIUM >= gateIndex && counts.medium > 0) parts.push(`${counts.medium} MEDIUM`);
   const atGate = parts.length > 0 ? parts.join(" \xB7 ") : "none";
   return {
     level: "notice",
@@ -1846,8 +2432,8 @@ function buildGateAnnotation(blocked, gate, counts) {
 }
 
 // src/commands/diff.ts
-var LEVEL_INDEX2 = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
-var GATE_INDEX2 = { medium: 1, high: 2, critical: 3 };
+var LEVEL_INDEX3 = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
+var GATE_INDEX3 = { medium: 1, high: 2, critical: 3 };
 var VERDICT_NOTE = {
   medium: "no MEDIUM or worse",
   high: "no HIGH or CRITICAL",
@@ -1860,14 +2446,20 @@ function countLevels(results) {
   }
   return counts;
 }
+function isAllowedByDiffAllowlist(relPath2, patterns) {
+  if (patterns.length === 0) return false;
+  const rel = toPosix(relPath2);
+  const matcher = picomatch(patterns.map(toPosix), { dot: true });
+  return matcher(rel);
+}
 function riskySummary(counts, gate) {
-  const gateIndex = GATE_INDEX2[gate];
+  const gateIndex = GATE_INDEX3[gate];
   const parts = [];
-  if (LEVEL_INDEX2.CRITICAL >= gateIndex && counts.critical > 0)
+  if (LEVEL_INDEX3.CRITICAL >= gateIndex && counts.critical > 0)
     parts.push(`${counts.critical} CRITICAL`);
-  if (LEVEL_INDEX2.HIGH >= gateIndex && counts.high > 0) parts.push(`${counts.high} HIGH`);
-  if (LEVEL_INDEX2.MEDIUM >= gateIndex && counts.medium > 0) parts.push(`${counts.medium} MEDIUM`);
-  if (LEVEL_INDEX2.LOW >= gateIndex && counts.low > 0) parts.push(`${counts.low} LOW`);
+  if (LEVEL_INDEX3.HIGH >= gateIndex && counts.high > 0) parts.push(`${counts.high} HIGH`);
+  if (LEVEL_INDEX3.MEDIUM >= gateIndex && counts.medium > 0) parts.push(`${counts.medium} MEDIUM`);
+  if (LEVEL_INDEX3.LOW >= gateIndex && counts.low > 0) parts.push(`${counts.low} LOW`);
   return parts.length > 0 ? parts.join(" \xB7 ") : "none";
 }
 async function diffCommand(options, ctx2) {
@@ -1905,9 +2497,16 @@ async function diffCommand(options, ctx2) {
     );
   }
   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_INDEX2[result.risk.level] >= GATE_INDEX2[gate]);
+  const allowPatterns = [...options.allow ?? [], ...context.config.diff.allow ?? []];
+  const allowedByRel = /* @__PURE__ */ new Map();
+  for (const rel of byRel.keys()) {
+    allowedByRel.set(rel, isAllowedByDiffAllowlist(rel, allowPatterns));
+  }
+  const entries = [...byRel.entries()].map(([rel, result]) => ({ rel, result, allowed: allowedByRel.get(rel) ?? false })).sort((a, b) => b.result.risk.score - a.result.risk.score);
+  const gateResults = entries.filter((entry) => !entry.allowed).map((entry) => entry.result);
+  const counts = countLevels(gateResults);
+  const allowedCount = entries.filter((entry) => entry.allowed).length;
+  const blocked = gateResults.some((result) => LEVEL_INDEX3[result.risk.level] >= GATE_INDEX3[gate]);
   const durationMs = Date.now() - started;
   if (format === "json") {
     ctx2.writer.write(
@@ -1916,9 +2515,11 @@ async function diffCommand(options, ctx2) {
           changed.baseLabel,
           changed.files,
           byRel,
+          allowedByRel,
           gate,
           blocked,
           counts,
+          allowedCount,
           durationMs,
           ctx2.version
         )
@@ -1926,10 +2527,26 @@ async function diffCommand(options, ctx2) {
     );
     return blocked ? ExitCode.Failure : ExitCode.Success;
   }
+  if (format === "sarif") {
+    ctx2.writer.write(
+      serializeJson(
+        buildDiffSarif({
+          baseLabel: changed.baseLabel,
+          entries,
+          gate,
+          counts,
+          blocked,
+          durationMs,
+          version: ctx2.version
+        })
+      )
+    );
+    return blocked ? ExitCode.Failure : ExitCode.Success;
+  }
   if (format === "github") {
     const annotations = [
       ...buildFileAnnotations(
-        [...byRel.entries()].map(([file, result]) => ({ file, result })),
+        [...byRel.entries()].filter(([rel]) => !(allowedByRel.get(rel) ?? false)).map(([file, result]) => ({ file, result })),
         gate
       ),
       buildGateAnnotation(blocked, gate, counts)
@@ -1943,9 +2560,10 @@ async function diffCommand(options, ctx2) {
       cwd: ctx2.cwd,
       baseLabel: changed.baseLabel,
       files: changed.files,
-      results,
+      entries,
       skipped,
       counts,
+      allowedCount,
       gate,
       blocked,
       durationMs,
@@ -1956,12 +2574,25 @@ async function diffCommand(options, ctx2) {
   return blocked ? ExitCode.Failure : ExitCode.Success;
 }
 function renderDiffReport(input, writer) {
-  const { cwd, baseLabel, files, results, skipped, counts, gate, blocked, durationMs, style } = input;
+  const {
+    cwd,
+    baseLabel,
+    files,
+    entries,
+    skipped,
+    counts,
+    allowedCount,
+    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")],
+    ["Source", pluralize(entries.length, "file")],
+    ["Allowed", pluralize(allowedCount, "file")],
     ["Duration", dim(formatDuration(durationMs), style)]
   ];
   const width = Math.max(...rows.map(([key]) => key.length));
@@ -1978,16 +2609,17 @@ function renderDiffReport(input, writer) {
     `${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_INDEX2[result.risk.level] >= GATE_INDEX2[gate];
+  writer.writeLine(sectionHeader(`Risk analysis (${entries.length} files)`, style));
+  for (const { result, allowed } of entries) {
+    const risky = LEVEL_INDEX3[result.risk.level] >= GATE_INDEX3[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);
+    const allowedTag = allowed ? ` ${dim("(allowed)", style)}` : "";
     writer.writeLine(
-      `${fileIconText} ${file}  ${riskBadge(result.risk.level, style)} \xB7 ${score}/100${gauge ? ` ${gauge}` : ""}`
+      `${fileIconText} ${file}  ${riskBadge(result.risk.level, style)} \xB7 ${score}/100${gauge ? ` ${gauge}` : ""}${allowedTag}`
     );
   }
   for (const rel of skipped) {
@@ -1997,7 +2629,7 @@ function renderDiffReport(input, writer) {
   }
   writer.writeLine();
 }
-function buildDiffJsonReport(baseLabel, changedFileNames, byRel, gate, blocked, counts, durationMs, version) {
+function buildDiffJsonReport(baseLabel, changedFileNames, byRel, allowedByRel, gate, blocked, counts, allowedCount, durationMs, version) {
   const files = [];
   for (const rel of changedFileNames) {
     const result = byRel.get(rel);
@@ -2007,7 +2639,8 @@ function buildDiffJsonReport(baseLabel, changedFileNames, byRel, gate, blocked,
         analyzed: true,
         risk: result.risk,
         affectedFiles: result.summary.affectedFiles,
-        targetInCycle: result.targetInCycle
+        targetInCycle: result.targetInCycle,
+        allowed: allowedByRel.get(rel) ?? false
       });
     } else {
       files.push({ file: rel, analyzed: false });
@@ -2021,20 +2654,468 @@ function buildDiffJsonReport(baseLabel, changedFileNames, byRel, gate, blocked,
     base: baseLabel,
     changedFiles: changedFileNames.length,
     files,
-    gate: { level: gate, blocked, counts },
+    gate: { level: gate, blocked, counts, allowed: allowedCount },
     durationMs
   };
 }
 
+// src/mcp/server.ts
+var PROTOCOL_VERSION = "2025-06-18";
+var ERR_PARSE = -32700;
+var ERR_INVALID_REQUEST = -32600;
+var ERR_INTERNAL = -32603;
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+var McpServer = class {
+  options;
+  tools = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.options = options;
+    for (const tool of options.tools) {
+      this.tools.set(tool.name, tool);
+    }
+  }
+  /**
+   * Process one inbound message. Returns the JSON-RPC response line to write
+   * back, or `null` for notifications and invalid requests.
+   */
+  async handleLine(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return this.response(void 0, {
+        code: ERR_PARSE,
+        message: "Parse error: not valid JSON"
+      });
+    }
+    if (!isObject(message) || message.jsonrpc !== "2.0") {
+      return this.response(void 0, {
+        code: ERR_INVALID_REQUEST,
+        message: "Invalid Request: expected a JSON-RPC 2.0 object"
+      });
+    }
+    const hasId = "id" in message;
+    if (message.method === "notifications/initialized") {
+      return null;
+    }
+    if (!hasId) {
+      return null;
+    }
+    const method = message.method;
+    if (typeof method !== "string") {
+      return this.response(message.id, {
+        code: ERR_INVALID_REQUEST,
+        message: "Invalid Request: method must be a string"
+      });
+    }
+    try {
+      const result = await this.dispatch(method, message.params);
+      return this.response(message.id, result);
+    } catch (error) {
+      return this.response(message.id, {
+        code: ERR_INTERNAL,
+        message: error instanceof Error ? error.message : "Internal error"
+      });
+    }
+  }
+  async dispatch(method, params) {
+    switch (method) {
+      case "initialize":
+        return {
+          protocolVersion: this.protocolVersion(params),
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: this.options.name, version: this.options.version }
+        };
+      case "ping":
+        return {};
+      case "tools/list":
+        return {
+          tools: [...this.tools.values()].map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+          }))
+        };
+      case "tools/call":
+        return this.callTool(params);
+      case "tools/list_changed":
+        throw new Error("Tool list changes are not supported by this server");
+      default:
+        throw new Error(`Method not found: ${method}`);
+    }
+  }
+  protocolVersion(params) {
+    if (isObject(params) && typeof params.protocolVersion === "string") {
+      return params.protocolVersion;
+    }
+    return PROTOCOL_VERSION;
+  }
+  async callTool(params) {
+    if (!isObject(params) || typeof params.name !== "string") {
+      throw new Error("Invalid params: expected { name: string, arguments?: object }");
+    }
+    const tool = this.tools.get(params.name);
+    if (!tool) {
+      throw new Error(`Unknown tool: ${params.name}`);
+    }
+    const args = isObject(params.arguments) || params.arguments === void 0 ? params.arguments ?? {} : null;
+    if (args === null) {
+      throw new Error(`Invalid arguments for tool ${params.name}: expected an object`);
+    }
+    try {
+      const result = await tool.handler(args);
+      return {
+        content: [{ type: "text", text: result.text }],
+        ...result.isError ? { isError: true } : {}
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: error instanceof Error ? error.message : "Tool failed"
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+  response(id, payload) {
+    if (typeof payload === "object" && payload !== null && "code" in payload && typeof payload.code === "number") {
+      const errorPayload = payload;
+      const error = { code: errorPayload.code, message: String(errorPayload.message) };
+      return `${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error })}
+`;
+    }
+    return `${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, result: payload })}
+`;
+  }
+};
+var MAX_DEPENDENTS = 200;
+function ok(text) {
+  return { text };
+}
+function fail(error) {
+  return { text: error instanceof Error ? error.message : "Tool failed", isError: true };
+}
+function requireString(args, key, tool) {
+  const value = args[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new RippleError(`Missing required argument "${key}" for ${tool}`, ExitCode.Failure);
+  }
+  return value;
+}
+function optionalPositiveInt(args, key, tool) {
+  const value = args[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new RippleError(
+      `Argument "${key}" for ${tool} must be a positive integer`,
+      ExitCode.Failure
+    );
+  }
+  return value;
+}
+function resolveFile(cwd, file) {
+  return path8.isAbsolute(file) ? file : path8.join(cwd, file);
+}
+function analyzeIn(project, cwd, file, maxDepth) {
+  const { context, graph, entryPoints } = project;
+  const targetPath = resolveFile(cwd, file);
+  const key = pathKey(targetPath, context.rootDir);
+  const node = graph.nodes.get(key);
+  if (!node) {
+    throw new RippleError(
+      `File not found in the project graph: ${file}. Is it a source file covered by ripple's discovery?`,
+      ExitCode.NotFound
+    );
+  }
+  return analyzeFile({
+    graph,
+    context,
+    entryPoints,
+    targetKey: key,
+    targetPath,
+    durationMs: 0,
+    ...maxDepth !== void 0 ? { maxDepth } : {}
+  });
+}
+function relPath(targetPath, cwd) {
+  const rel = targetPath.slice(cwd.length).replace(/^[/\\]+/, "");
+  return (rel || targetPath).replace(/\\/g, "/");
+}
+var IMPACT_SCHEMA = {
+  type: "object",
+  properties: {
+    file: {
+      type: "string",
+      description: "Project-relative or absolute path of the file to analyze."
+    },
+    maxDepth: {
+      type: "integer",
+      minimum: 1,
+      description: "Cap the reverse traversal depth (default: unlimited)."
+    }
+  },
+  required: ["file"]
+};
+var DEPENDENTS_SCHEMA = {
+  type: "object",
+  properties: {
+    file: {
+      type: "string",
+      description: "Project-relative or absolute path of the file."
+    },
+    depth: {
+      type: "integer",
+      minimum: 1,
+      description: "Max dependency depth to report (default: 1, direct dependents only)."
+    }
+  },
+  required: ["file"]
+};
+var RISK_SCHEMA = {
+  type: "object",
+  properties: {
+    file: {
+      type: "string",
+      description: "Project-relative or absolute path of the file."
+    }
+  },
+  required: ["file"]
+};
+var GATE_SCHEMA = {
+  type: "object",
+  properties: {
+    base: {
+      type: "string",
+      description: "Git ref to diff against (default: origin/main, main, or HEAD~1)."
+    },
+    gate: {
+      type: "string",
+      enum: ["medium", "high", "critical"],
+      description: "Risk level that blocks the merge (default: high)."
+    }
+  }
+};
+var LEVEL_INDEX4 = { LOW: 1, MEDIUM: 2, HIGH: 3, CRITICAL: 4 };
+function createMcpTools(deps) {
+  const { cwd, loadProject, getChanged } = deps;
+  return [
+    {
+      name: "impact",
+      description: "Blast-radius analysis of a file: how many files, routes, tests and components would be affected by changing it, plus its risk score. Call before editing or refactoring a file so the change set stays low-risk.",
+      inputSchema: IMPACT_SCHEMA,
+      handler: async (args) => {
+        try {
+          const file = requireString(args, "file", "impact");
+          const maxDepth = optionalPositiveInt(args, "maxDepth", "impact");
+          const project = await loadProject();
+          const result = analyzeIn(project, cwd, file, maxDepth);
+          return ok(
+            JSON.stringify(
+              {
+                file: relPath(result.targetPath, cwd),
+                risk: { score: result.risk.score, level: result.risk.level },
+                summary: result.summary,
+                targetInCycle: result.targetInCycle
+              },
+              null,
+              2
+            )
+          );
+        } catch (error) {
+          return fail(error);
+        }
+      }
+    },
+    {
+      name: "dependents",
+      description: "List the files that depend on a file (its importers), up to a depth. Depth 1 is direct dependents; deeper levels are transitive. Useful to know who breaks when the file changes.",
+      inputSchema: DEPENDENTS_SCHEMA,
+      handler: async (args) => {
+        try {
+          const file = requireString(args, "file", "dependents");
+          const depth = optionalPositiveInt(args, "depth", "dependents") ?? 1;
+          const project = await loadProject();
+          const result = analyzeIn(project, cwd, file);
+          const dependents = [...result.affected.values()].filter((affected) => affected.depth <= depth).sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path)).map((affected) => ({
+            path: relPath(affected.path, cwd),
+            depth: affected.depth,
+            direct: affected.direct,
+            inCycle: affected.inCycle,
+            categories: affected.categories
+          }));
+          return ok(
+            JSON.stringify(
+              {
+                file: relPath(result.targetPath, cwd),
+                depth,
+                count: dependents.length,
+                truncated: dependents.length > MAX_DEPENDENTS,
+                dependents: dependents.slice(0, MAX_DEPENDENTS)
+              },
+              null,
+              2
+            )
+          );
+        } catch (error) {
+          return fail(error);
+        }
+      }
+    },
+    {
+      name: "risk",
+      description: "The risk score (0-100) of changing a file and the factor breakdown behind it. Cheap way to compare the danger of different refactor targets.",
+      inputSchema: RISK_SCHEMA,
+      handler: async (args) => {
+        try {
+          const file = requireString(args, "file", "risk");
+          const project = await loadProject();
+          const result = analyzeIn(project, cwd, file);
+          return ok(
+            JSON.stringify(
+              {
+                file: relPath(result.targetPath, cwd),
+                score: result.risk.score,
+                level: result.risk.level,
+                targetInCycle: result.targetInCycle,
+                factors: result.risk.factors
+              },
+              null,
+              2
+            )
+          );
+        } catch (error) {
+          return fail(error);
+        }
+      }
+    },
+    {
+      name: "gate_status",
+      description: "Check the current change set against the ripple merge gate: which files changed since the base ref, their risk levels, and whether the gate passes or blocks. Call after editing files to verify the changes are safe to merge.",
+      inputSchema: GATE_SCHEMA,
+      handler: async (args) => {
+        try {
+          const base = args.base;
+          const gate = args.gate;
+          if (base !== void 0 && typeof base !== "string") {
+            return fail(
+              new RippleError('Argument "base" for gate_status must be a string', ExitCode.Failure)
+            );
+          }
+          if (gate !== void 0 && gate !== "medium" && gate !== "high" && gate !== "critical") {
+            return fail(
+              new RippleError(
+                'Argument "gate" for gate_status must be medium | high | critical',
+                ExitCode.Failure
+              )
+            );
+          }
+          const changed = getChanged(base);
+          const project = await loadProject();
+          const resolvedGate = gate ?? project.context.config.diff.gate ?? "high";
+          const gateIndex = LEVEL_INDEX4[resolvedGate.toUpperCase()] ?? 3;
+          const files = [];
+          const counts = { low: 0, medium: 0, high: 0, critical: 0 };
+          let blocked = false;
+          for (const rel of changed.files) {
+            try {
+              const result = analyzeIn(project, cwd, rel);
+              const level = result.risk.level;
+              counts[level.toLowerCase()] += 1;
+              if ((LEVEL_INDEX4[level] ?? 1) >= gateIndex) blocked = true;
+              files.push({
+                file: rel,
+                analyzed: true,
+                level,
+                score: result.risk.score,
+                affectedFiles: result.summary.affectedFiles,
+                targetInCycle: result.targetInCycle
+              });
+            } catch {
+              files.push({ file: rel, analyzed: false });
+            }
+          }
+          return ok(
+            JSON.stringify(
+              {
+                base: changed.baseLabel,
+                changedFiles: changed.files.length,
+                files,
+                counts,
+                gate: { level: resolvedGate, blocked, verdict: blocked ? "block" : "pass" }
+              },
+              null,
+              2
+            )
+          );
+        } catch (error) {
+          return fail(error);
+        }
+      }
+    }
+  ];
+}
+
+// src/commands/mcp.ts
+async function mcpCommand(options, ctx2) {
+  let snapshot = null;
+  const loadProject = async () => {
+    if (!snapshot) {
+      const context = await loadProjectContext(ctx2.cwd, options.config);
+      const { graph, entryPoints } = await runPipeline(context);
+      snapshot = { context, graph, entryPoints };
+    }
+    return snapshot;
+  };
+  const server = new McpServer({
+    name: "ripple",
+    version: ctx2.version,
+    tools: createMcpTools({
+      cwd: ctx2.cwd,
+      loadProject,
+      getChanged: (base) => changedFiles(ctx2.cwd, base)
+    })
+  });
+  const stdin = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  await new Promise((resolve) => {
+    stdin.on("line", (line) => {
+      if (!line.trim()) return;
+      void server.handleLine(line).then((response) => {
+        if (response) process.stdout.write(response);
+      });
+    });
+    stdin.on("close", () => resolve());
+  });
+  return ExitCode.Success;
+}
+
 // src/cli/program.ts
 var PROGRAM_NAME = "ripple";
+function helpExamples(examples) {
+  const lines = examples.map((example) => `  ${example}`);
+  return `
+Examples:
+${lines.join("\n")}
+`;
+}
 function createProgram(ctx2) {
   const program = new Command().name(PROGRAM_NAME).description("Dependency impact analysis for TypeScript and JavaScript projects.").version(ctx2.version, "-V, --version", "print the Ripple version").showHelpAfterError();
-  program.command("analyze <file>").description("Analyze the impact of changing a file").option("-j, --json", "emit a machine-readable JSON report").option("-v, --verbose", "include the risk factor breakdown").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 (file, options) => {
+  program.command("analyze <file>").description("Analyze the impact of changing a file").addHelpText(
+    "after",
+    helpExamples([
+      "ripple analyze src/authentication/login.ts",
+      "ripple analyze src/index.ts --depth 3"
+    ])
+  ).option("-j, --json", "emit a machine-readable JSON report").option("--sarif", "emit a SARIF 2.1.0 report for code scanning").option("-v, --verbose", "include the risk factor breakdown").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 (file, options) => {
     const exitCode2 = await analyzeCommand(
       file,
       {
         json: Boolean(options.json),
+        sarif: Boolean(options.sarif),
         verbose: Boolean(options.verbose),
         ...options.depth !== void 0 ? { depth: options.depth } : {},
         ...options.config !== void 0 ? { config: options.config } : {},
@@ -2046,11 +3127,23 @@ function createProgram(ctx2) {
       throw new ExitError(exitCode2);
     }
   });
-  program.command("graph [file]").description("Show project graph stats, or the dependency tree of one file").option("-j, --json", "emit a machine-readable JSON report").option("-v, --verbose", "include extra sections").option("-r, --reverse", "show dependents (what imports the file) instead of dependants").option("-d, --depth <number>", "cap the tree depth", parsePositiveInt).option("-c, --config <path>", "path to a ripple config file").option("--no-color", "disable ANSI colors").action(async (file, options) => {
+  program.command("graph [file]").description("Show project graph stats, or the dependency tree of one file").addHelpText(
+    "after",
+    helpExamples([
+      "ripple graph",
+      "ripple graph src/index.ts --reverse --depth 3",
+      "ripple graph --format mermaid"
+    ])
+  ).option("-j, --json", "emit a machine-readable JSON report").option(
+    "-f, --format <format>",
+    "output format: terminal | json | mermaid | dot | html",
+    parseGraphFormat
+  ).option("-v, --verbose", "include extra sections").option("-r, --reverse", "show dependents (what imports the file) instead of dependants").option("-d, --depth <number>", "cap the tree depth", parsePositiveInt).option("-c, --config <path>", "path to a ripple config file").option("--no-color", "disable ANSI colors").action(async (file, options) => {
     const exitCode2 = await graphCommand(
       file,
       {
         json: Boolean(options.json),
+        format: options.format ?? (options.json ? "json" : "terminal"),
         verbose: Boolean(options.verbose),
         reverse: Boolean(options.reverse),
         ...options.depth !== void 0 ? { depth: options.depth } : {},
@@ -2063,11 +3156,18 @@ 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("-f, --format <format>", "output format: terminal | json | github", parseDiffFormat).option("-v, --verbose", "include extra sections").option("-b, --base <ref>", "git ref to diff against (default: origin/main, main, HEAD~1)").option(
+  program.command("diff").description("Analyze changed files since a base ref and gate risky changes").addHelpText(
+    "after",
+    helpExamples(["ripple diff --base main --gate critical", "ripple diff --format github"])
+  ).option("-j, --json", "emit a machine-readable JSON report").option(
+    "-f, --format <format>",
+    "output format: terminal | json | github | sarif",
+    parseDiffFormat
+  ).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) => {
+  ).option("-d, --depth <number>", "cap the reverse traversal depth", parsePositiveInt).option("-a, --allow <glob...>", "changed files matching these globs never block the gate").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),
@@ -2076,6 +3176,7 @@ function createProgram(ctx2) {
         ...options.base !== void 0 ? { base: options.base } : {},
         ...options.gate !== void 0 ? { gate: options.gate } : {},
         ...options.depth !== void 0 ? { depth: options.depth } : {},
+        ...options.allow !== void 0 ? { allow: options.allow } : {},
         ...options.config !== void 0 ? { config: options.config } : {},
         color: options.color
       },
@@ -2085,7 +3186,7 @@ function createProgram(ctx2) {
       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) => {
+  program.command("doctor").description("Check the project and environment for Ripple readiness").addHelpText("after", helpExamples(["ripple doctor", "ripple doctor -v"])).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(
       {
         verbose: Boolean(options.verbose),
@@ -2098,16 +3199,35 @@ 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").option("--no-color", "disable ANSI colors").action(async (options) => {
+  program.command("init").description("Create a ripple.config with the default settings").addHelpText("after", helpExamples(["ripple init --force", "ripple init --ts --full"])).option("-f, --force", "overwrite an existing config file").option("--full", "write every built-in default instead of a minimal config").option("--ts", "write a typed ripple.config.ts instead of JSON").option("--no-color", "disable ANSI colors").action(async (options) => {
     const exitCode2 = await initCommand(
-      { force: Boolean(options.force), color: options.color },
+      {
+        force: Boolean(options.force),
+        full: Boolean(options.full),
+        ts: Boolean(options.ts),
+        color: options.color
+      },
+      ctx2
+    );
+    if (exitCode2 !== ExitCode.Success) {
+      throw new ExitError(exitCode2);
+    }
+  });
+  program.command("mcp").description("Serve Ripple analysis tools over the Model Context Protocol (stdio)").addHelpText(
+    "after",
+    helpExamples(['ripple mcp  # point an MCP client (Claude, Cursor, ...) at "ripple mcp"'])
+  ).option("-c, --config <path>", "path to a ripple config file").action(async (options) => {
+    const exitCode2 = await mcpCommand(
+      {
+        config: options.config
+      },
       ctx2
     );
     if (exitCode2 !== ExitCode.Success) {
       throw new ExitError(exitCode2);
     }
   });
-  program.command("version").description("Print the Ripple version").action(() => {
+  program.command("version").description("Print the Ripple version").addHelpText("after", helpExamples(["ripple version"])).action(() => {
     ctx2.writer.writeLine(ctx2.version);
   });
   program.addHelpText(
@@ -2147,13 +3267,23 @@ function parseGateLevel(value) {
   );
 }
 function parseDiffFormat(value) {
-  if (value === "terminal" || value === "json" || value === "github") {
+  if (value === "terminal" || value === "json" || value === "github" || value === "sarif") {
+    return value;
+  }
+  throw new CommanderError(
+    1,
+    "commander.invalidArgument",
+    `expected one of terminal | json | github | sarif, got "${value}"`
+  );
+}
+function parseGraphFormat(value) {
+  if (value === "terminal" || value === "json" || value === "mermaid" || value === "dot" || value === "html") {
     return value;
   }
   throw new CommanderError(
     1,
     "commander.invalidArgument",
-    `expected one of terminal | json | github, got "${value}"`
+    `expected one of terminal | json | mermaid | dot | html, got "${value}"`
   );
 }
 function printError(error, ctx2) {
@@ -2189,7 +3319,7 @@ async function run({ argv, ctx: ctx2 }) {
 
 // package.json
 var package_default = {
-  version: "0.5.0"};
+  version: "0.7.0"};
 
 // src/cli/bin.ts
 var ctx = {