@alimaandev/ripple 0.4.0 → 0.5.0

package/README.md

@@ -97,7 +97,7 @@ Everything below is real output against a shipped example project in `tests/fixt
 ```bash
 npm install -g @alimaandev/ripple
 
-ripple version                  # → 0.4.0
+ripple version                  # → 0.5.0
 ```
 
 Or install from source:
@@ -212,28 +212,29 @@ ripple <command> [options]
 
 ### Options
 
-| Command   | Flag                  | Description                                                        |
-| --------- | --------------------- | ------------------------------------------------------------------ |
-| `analyze` | `-j, --json`          | Emit the JSON report instead of the terminal report                |
-| `analyze` | `-v, --verbose`       | Include the risk-factor point breakdown                            |
-| `analyze` | `-d, --depth <n>`     | Cap the reverse traversal at `n` levels                            |
-| `analyze` | `-c, --config <path>` | Use a specific config file                                         |
-| `analyze` | `--no-color`          | Disable ANSI colors                                                |
-| `graph`   | `-j, --json`          | Emit the JSON report                                               |
-| `graph`   | `-r, --reverse`       | Show dependents (what imports this file) instead of dependencies   |
-| `graph`   | `-d, --depth <n>`     | Cap tree depth                                                     |
-| `graph`   | `-c, --config <path>` | Use a specific config file                                         |
-| `graph`   | `--no-color`          | Disable ANSI colors                                                |
-| `doctor`  | `-c, --config <path>` | Use a specific config file                                         |
-| `doctor`  | `-v, --verbose`       | Verbose output                                                     |
-| `doctor`  | `--no-color`          | Disable ANSI colors                                                |
-| `init`    | `-f, --force`         | Overwrite an existing config                                       |
-| `diff`    | `-j, --json`          | Emit the JSON report instead of the terminal report                |
+| Command   | Flag                  | Description                                                                                    |
+| --------- | --------------------- | ---------------------------------------------------------------------------------------------- |
+| `analyze` | `-j, --json`          | Emit the JSON report instead of the terminal report                                            |
+| `analyze` | `-v, --verbose`       | Include the risk-factor point breakdown                                                        |
+| `analyze` | `-d, --depth <n>`     | Cap the reverse traversal at `n` levels                                                        |
+| `analyze` | `-c, --config <path>` | Use a specific config file                                                                     |
+| `analyze` | `--no-color`          | Disable ANSI colors                                                                            |
+| `graph`   | `-j, --json`          | Emit the JSON report                                                                           |
+| `graph`   | `-r, --reverse`       | Show dependents (what imports this file) instead of dependencies                               |
+| `graph`   | `-d, --depth <n>`     | Cap tree depth                                                                                 |
+| `graph`   | `-c, --config <path>` | Use a specific config file                                                                     |
+| `graph`   | `--no-color`          | Disable ANSI colors                                                                            |
+| `doctor`  | `-c, --config <path>` | Use a specific config file                                                                     |
+| `doctor`  | `-v, --verbose`       | Verbose output                                                                                 |
+| `doctor`  | `--no-color`          | Disable ANSI colors                                                                            |
+| `init`    | `-f, --force`         | Overwrite an existing config                                                                   |
+| `diff`    | `-j, --json`          | Emit the JSON report instead of the terminal report                                            |
 | `diff`    | `-b, --base <ref>`    | Git ref to diff against (default: `origin/main`, `main`, `HEAD~1`, or `diff.base` from config) |
-| `diff`    | `-g, --gate <level>`  | Blocking level: `medium`, `high`, or `critical` (default: `high`, or `diff.gate` from config)   |
-| `diff`    | `-d, --depth <n>`     | Cap reverse traversal per file                                     |
-| `diff`    | `-c, --config <path>` | Use a specific config file                                         |
-| `diff`    | `--no-color`          | Disable ANSI colors                                                |
+| `diff`    | `-g, --gate <level>`  | Blocking level: `medium`, `high`, or `critical` (default: `high`, or `diff.gate` from config)  |
+| `diff`    | `-f, --format <fmt>`  | Output: `terminal`, `json`, or `github` (workflow annotations)                                 |
+| `diff`    | `-d, --depth <n>`     | Cap reverse traversal per file                                                                 |
+| `diff`    | `-c, --config <path>` | Use a specific config file                                                                     |
+| `diff`    | `--no-color`          | Disable ANSI colors                                                                            |
 
 ### `ripple doctor`
 
@@ -298,6 +299,23 @@ Risk analysis (2 files)
 Run `ripple diff` locally before opening a PR, and in CI as the same gate —
 identical code, identical verdict.
 
+```bash
+ripple diff --format github
+```
+
+`--format github` emits GitHub Actions workflow commands. Each risky change
+shows as a warning or error annotation right on the PR's Files tab —
+`::error` when a file blocks the gate, `::warning` otherwise — plus a
+`::notice` line with the gate verdict. The exit code still carries the
+verdict, so the job fails when the gate blocks:
+
+```yaml
+- run: npx @alimaandev/ripple diff --format github
+```
+
+(`--json` is shorthand for `--format json`; the format flag also accepts
+`terminal`, the default.)
+
 ## Configuration
 
 Ripple discovers `ripple.config.ts`, `.js`, `.cjs`, `.mjs`, or `.json` in the

package/dist/bin.js

@@ -1806,9 +1806,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",
@@ -1822,18 +1861,19 @@ function countLevels(results) {
   return counts;
 }
 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";
@@ -1867,9 +1907,9 @@ 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 blocked = results.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(
@@ -1886,6 +1926,18 @@ async function diffCommand(options, ctx2) {
     );
     return blocked ? ExitCode.Failure : ExitCode.Success;
   }
+  if (format === "github") {
+    const annotations = [
+      ...buildFileAnnotations(
+        [...byRel.entries()].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,
@@ -1928,7 +1980,7 @@ function renderDiffReport(input, writer) {
   writer.writeLine();
   writer.writeLine(sectionHeader(`Risk analysis (${results.length} files)`, style));
   for (const result of results) {
-    const risky = LEVEL_INDEX[result.risk.level] >= GATE_INDEX[gate];
+    const 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);
@@ -2011,7 +2063,7 @@ 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").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
@@ -2019,6 +2071,7 @@ function createProgram(ctx2) {
     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 } : {},
@@ -2093,6 +2146,16 @@ 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 printError(error, ctx2) {
   if (error instanceof RippleError) {
     ctx2.errorWriter.writeLine(`\u2716 ${error.message}`);
@@ -2126,7 +2189,7 @@ async function run({ argv, ctx: ctx2 }) {
 
 // package.json
 var package_default = {
-  version: "0.4.0"};
+  version: "0.5.0"};
 
 // src/cli/bin.ts
 var ctx = {