@alimaandev/ripple 0.4.0 → 0.6.0

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/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';
@@ -9,9 +9,9 @@ import { Project, ts, SyntaxKind } from 'ts-morph';
 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 picomatch from 'picomatch';
 import { execFileSync } from 'child_process';
 
 // src/output/writer.ts
@@ -507,7 +507,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 +529,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 +786,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
@@ -1392,7 +1385,7 @@ function buildGraph(project, filePaths, context) {
   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) {
@@ -1412,7 +1405,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,7 +1430,7 @@ function buildGraph(project, filePaths, context) {
     stats: {
       files: parsedFiles.length,
       parsed: parsedCount,
-      internalEdges,
+      internalEdges: internalEdges2,
       unresolvedEdges,
       externalEdges,
       cycles: 0
@@ -1518,6 +1511,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 +1676,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 +1718,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 +1757,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 +1900,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);
     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 fs.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 +1973,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;
   }
@@ -1806,9 +2029,48 @@ function changedFiles(cwd, base) {
   return { baseLabel, files: [...files].sort() };
 }
 
-// src/commands/diff.ts
+// src/formatter/annotations.ts
 var LEVEL_INDEX = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
 var GATE_INDEX = { 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");
+}
+function escapeMessage(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function renderAnnotation(annotation) {
+  const props = annotation.file ? ` file=${escapeProperty(annotation.file)},title=${escapeProperty(annotation.title)}` : ` title=${escapeProperty(annotation.title)}`;
+  return `::${annotation.level}${props}::${escapeMessage(annotation.message)}`;
+}
+function buildFileAnnotations(files, gate) {
+  return files.map(({ file, result }) => {
+    const blocked = LEVEL_INDEX[result.risk.level] >= GATE_INDEX[gate];
+    return {
+      level: blocked ? "error" : "warning",
+      file,
+      title: `Ripple ${result.risk.level}`,
+      message: `${result.risk.level} risk (score ${result.risk.score}) \u2014 ${result.summary.affectedFiles} affected ${result.summary.affectedFiles === 1 ? "file" : "files"}`
+    };
+  });
+}
+function buildGateAnnotation(blocked, gate, counts) {
+  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`);
+  const atGate = parts.length > 0 ? parts.join(" \xB7 ") : "none";
+  return {
+    level: "notice",
+    title: `Ripple diff ${gate} gate`,
+    message: blocked ? `Gate blocked: ${atGate} at or above ${gate}` : `Gate passed: nothing at ${gate} or above`
+  };
+}
+
+// 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 VERDICT_NOTE = {
   medium: "no MEDIUM or worse",
   high: "no HIGH or CRITICAL",
@@ -1821,19 +2083,26 @@ function countLevels(results) {
   }
   return counts;
 }
+function isAllowedByDiffAllowlist(relPath, patterns) {
+  if (patterns.length === 0) return false;
+  const rel = toPosix(relPath);
+  const matcher = picomatch(patterns.map(toPosix), { dot: true });
+  return matcher(rel);
+}
 function riskySummary(counts, gate) {
-  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_INDEX.LOW >= gateIndex && counts.low > 0) parts.push(`${counts.low} LOW`);
+  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`);
   return parts.length > 0 ? parts.join(" \xB7 ") : "none";
 }
 async function diffCommand(options, ctx2) {
+  const format = options.format ?? (options.json ? "json" : "terminal");
   const style = { color: resolveColor(options.color) };
-  const tracker = createStageTracker(!options.json);
+  const tracker = createStageTracker(format === "terminal");
   const started = Date.now();
   const context = await loadProjectContext(ctx2.cwd, options.config);
   const gate = options.gate ?? context.config.diff.gate ?? "high";
@@ -1865,20 +2134,29 @@ 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_INDEX[result.risk.level] >= GATE_INDEX[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_INDEX2[result.risk.level] >= GATE_INDEX2[gate]);
   const durationMs = Date.now() - started;
-  if (options.json) {
+  if (format === "json") {
     ctx2.writer.write(
       serializeJson(
         buildDiffJsonReport(
           changed.baseLabel,
           changed.files,
           byRel,
+          allowedByRel,
           gate,
           blocked,
           counts,
+          allowedCount,
           durationMs,
           ctx2.version
         )
@@ -1886,14 +2164,27 @@ async function diffCommand(options, ctx2) {
     );
     return blocked ? ExitCode.Failure : ExitCode.Success;
   }
+  if (format === "github") {
+    const annotations = [
+      ...buildFileAnnotations(
+        [...byRel.entries()].filter(([rel]) => !(allowedByRel.get(rel) ?? false)).map(([file, result]) => ({ file, result })),
+        gate
+      ),
+      buildGateAnnotation(blocked, gate, counts)
+    ];
+    ctx2.writer.write(`${annotations.map(renderAnnotation).join("\n")}
+`);
+    return blocked ? ExitCode.Failure : ExitCode.Success;
+  }
   renderDiffReport(
     {
       cwd: ctx2.cwd,
       baseLabel: changed.baseLabel,
       files: changed.files,
-      results,
+      entries,
       skipped,
       counts,
+      allowedCount,
       gate,
       blocked,
       durationMs,
@@ -1904,12 +2195,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));
@@ -1926,16 +2230,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_INDEX[result.risk.level] >= GATE_INDEX[gate];
+  writer.writeLine(sectionHeader(`Risk analysis (${entries.length} files)`, style));
+  for (const { result, allowed } of entries) {
+    const risky = LEVEL_INDEX2[result.risk.level] >= GATE_INDEX2[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) {
@@ -1945,7 +2250,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);
@@ -1955,7 +2260,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 });
@@ -1969,16 +2275,29 @@ 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/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("-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,
       {
@@ -1994,11 +2313,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 } : {},
@@ -2011,18 +2342,23 @@ 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(
+  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", 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),
+        format: options.format ?? (options.json ? "json" : "terminal"),
         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.allow !== void 0 ? { allow: options.allow } : {},
         ...options.config !== void 0 ? { config: options.config } : {},
         color: options.color
       },
@@ -2032,7 +2368,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),
@@ -2045,16 +2381,21 @@ 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("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(
@@ -2093,6 +2434,26 @@ function parseGateLevel(value) {
     `expected one of medium | high | critical, got "${value}"`
   );
 }
+function parseDiffFormat(value) {
+  if (value === "terminal" || value === "json" || value === "github") {
+    return value;
+  }
+  throw new CommanderError(
+    1,
+    "commander.invalidArgument",
+    `expected one of terminal | json | github, 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 | mermaid | dot | html, got "${value}"`
+  );
+}
 function printError(error, ctx2) {
   if (error instanceof RippleError) {
     ctx2.errorWriter.writeLine(`\u2716 ${error.message}`);
@@ -2126,7 +2487,7 @@ async function run({ argv, ctx: ctx2 }) {
 
 // package.json
 var package_default = {
-  version: "0.4.0"};
+  version: "0.6.0"};
 
 // src/cli/bin.ts
 var ctx = {