dep-brain 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.7.0
+
+- Added idempotent GitHub PR comments with `--pr-comment`.
+- Added `--comment-on` trigger support for `always`, `failure`, and `new-findings`.
+- Added PR comment markdown renderer with top issues, policy reasons, upgrade priorities, and baseline delta counts.
+- Added GitHub Action inputs for PR comment runs.
+- Kept analysis output contract at `1.6` because no JSON result fields changed.
+
 ## 1.6.0
 
 - Added Slack and Discord webhook notification summaries.

package/README.md

@@ -6,7 +6,7 @@
 
 `dep-brain` is a CLI and library for explainable dependency intelligence in JavaScript and TypeScript projects.
 
-Current release `1.6.0` adds Slack and Discord notification summaries while keeping analysis output contract `1.6`.
+Current release `1.7.0` adds idempotent GitHub PR comments while keeping analysis output contract `1.6`.
 
 ## Vision
 
@@ -29,6 +29,7 @@ Current release `1.6.0` adds Slack and Discord notification summaries while keep
 - Output reports in console, JSON, Markdown, SARIF, dashboard, and top-issues formats
 - Output upgrade-advice reports via `--advise`
 - Send Slack and Discord webhook summaries for CI runs
+- Create or update GitHub PR comments for pull request checks
 - Gate CI with score and finding policies
 - Compare new findings against a baseline report
 
@@ -38,7 +39,7 @@ The long-term goal is not just to list problems, but to answer:
 - Can I remove it safely?
 - What should I fix first?
 
-## 1.6 Highlights
+## 1.7 Highlights
 
 - Duplicate dependency detection with lockfile instance tracking
 - Unused dependency detection with runtime vs dev-tool heuristics
@@ -57,6 +58,7 @@ The long-term goal is not just to list problems, but to answer:
 - Static HTML dashboard via `--dashboard`
 - Upgrade advisor output via `--advise`
 - Slack and Discord notification summaries via `--notify`
+- GitHub PR comments via `--pr-comment`
 - Ranked top issues via `--top`
 - Baseline mode via `--baseline`
 - Focused analysis via `--focus`
@@ -88,6 +90,8 @@ npx dep-brain analyze --dashboard
 npx dep-brain analyze --dashboard --dashboard-out reports/depbrain.html
 npx dep-brain analyze --notify
 npx dep-brain analyze --notify --notify-on always
+npx dep-brain analyze --pr-comment
+npx dep-brain analyze --pr-comment --comment-on new-findings
 npx dep-brain analyze --focus duplicates
 npx dep-brain analyze --ci
 npx dep-brain analyze --baseline depbrain-baseline.json
@@ -173,7 +177,7 @@ Suggestions:
 dep-brain analyze --json
 ```
 
-Output includes `outputVersion` for schema stability. `dep-brain@1.6.0` writes contract version `1.6`.
+Output includes `outputVersion` for schema stability. `dep-brain@1.7.0` writes contract version `1.6`.
 
 Validate against:
 
@@ -219,6 +223,15 @@ DEPBRAIN_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... dep-brain anal
 
 `--notify` sends compact summaries to configured Slack and Discord webhook URLs. Default trigger is `failure`, so passing runs stay quiet unless `--notify-on always` is set.
 
+## PR Comments
+
+```bash
+dep-brain analyze --ci --pr-comment
+dep-brain analyze --ci --baseline depbrain-baseline.json --pr-comment --comment-on new-findings
+```
+
+`--pr-comment` creates or updates one GitHub pull request comment using `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, and `GITHUB_EVENT_PATH`. The comment includes policy status, health score, top issues, upgrade priorities, and baseline delta counts when `--baseline` is used.
+
 ## Plugins
 
 ```json
@@ -360,6 +373,7 @@ dep-brain analyze --min-score 85 --fail-on-risks
 dep-brain analyze --config depbrain.config.json
 dep-brain analyze --baseline depbrain-baseline.json --fail-on-unused
 dep-brain analyze --ci --notify
+dep-brain analyze --ci --pr-comment
 ```
 
 ## Config Debugging
@@ -406,7 +420,7 @@ src/
 
 ## Product Direction
 
-`dep-brain` is in `v1.6.0` production CLI stage, with current focus on actionable dependency decisions and CI workflow integration.
+`dep-brain` is in `v1.7.0` production CLI stage, with current focus on actionable dependency decisions and PR workflow integration.
 
 Recent releases added:
 
@@ -415,6 +429,7 @@ Recent releases added:
 - baseline, focus, and CI workflows
 - structured upgrade advice with release-note links
 - Slack and Discord notification summaries
+- idempotent GitHub PR comments
 
 Project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
 

package/action.yml

@@ -59,6 +59,18 @@ inputs:
     description: Notification trigger. Use always, failure, or never.
     required: false
     default: "failure"
+  pr-comment:
+    description: Create or update a GitHub PR comment.
+    required: false
+    default: "false"
+  comment-on:
+    description: PR comment trigger. Use always, failure, or new-findings.
+    required: false
+    default: "failure"
+  github-token:
+    description: GitHub token for PR comments.
+    required: false
+    default: ""
 
 runs:
   using: composite
@@ -80,6 +92,9 @@ runs:
         INPUT_FAIL_ON_RISKS: ${{ inputs.fail-on-risks }}
         INPUT_NOTIFY: ${{ inputs.notify }}
         INPUT_NOTIFY_ON: ${{ inputs.notify-on }}
+        INPUT_PR_COMMENT: ${{ inputs.pr-comment }}
+        INPUT_COMMENT_ON: ${{ inputs.comment-on }}
+        GITHUB_TOKEN: ${{ inputs.github-token || github.token }}
       run: |
         set -euo pipefail
 
@@ -141,6 +156,10 @@ runs:
           args+=("--notify" "--notify-on" "$INPUT_NOTIFY_ON")
         fi
 
+        if [ "$INPUT_PR_COMMENT" = "true" ]; then
+          args+=("--pr-comment" "--comment-on" "$INPUT_COMMENT_ON")
+        fi
+
         node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
 
 branding:

package/dist/cli.js

@@ -3,8 +3,10 @@ import { analyzeProject } from "./core/analyzer.js";
 import { renderConsoleReport } from "./reporters/console.js";
 import { renderJsonReport } from "./reporters/json.js";
 import { renderMarkdownReport } from "./reporters/markdown.js";
+import { renderPrCommentReport } from "./reporters/pr-comment.js";
 import { renderSarifReport } from "./reporters/sarif.js";
 import { renderDashboardReport } from "./reporters/dashboard.js";
+import { shouldPostPrComment, upsertGitHubPrComment } from "./utils/github.js";
 import { sendConfiguredNotifications } from "./utils/notifications.js";
 import { defaultConfig } from "./utils/config.js";
 import { promises as fs } from "node:fs";
@@ -175,6 +177,28 @@ async function main() {
                 }
             }
         }
+        if (flags.has("--pr-comment")) {
+            const trigger = parsePrCommentTrigger(optionValues.get("--comment-on"));
+            const newFindingsCount = countFindings(result);
+            if (shouldPostPrComment({
+                trigger,
+                policyPassed: result.policy.passed,
+                newFindingsCount
+            })) {
+                const commentResult = await upsertGitHubPrComment({
+                    body: renderPrCommentReport(result, { hasBaseline: Boolean(baseline) })
+                });
+                if (commentResult.status === "created" || commentResult.status === "updated") {
+                    console.error(`PR comment ${commentResult.status}.`);
+                }
+                else {
+                    console.error(`PR comment skipped: ${commentResult.reason ?? "unknown reason"}`);
+                }
+            }
+            else {
+                console.error(`PR comment skipped: ${trigger} trigger did not match.`);
+            }
+        }
         if (!result.policy.passed) {
             process.exitCode = 1;
         }
@@ -246,7 +270,7 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--dashboard] [--notify] [--notify-on kind] [--focus kind] [--ci] [--out path] [--config path] [--baseline path] [--min-score n] [--fail-on-risks]");
+    console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--dashboard] [--notify] [--pr-comment] [--comment-on kind] [--focus kind] [--ci] [--out path] [--config path] [--baseline path] [--min-score n] [--fail-on-risks]");
     console.log("  dep-brain report --from <file> [--md] [--json] [--sarif] [--top] [--advise] [--dashboard] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain init [--out depbrain.config.json]");
@@ -263,6 +287,8 @@ function printHelp() {
     console.log("  --dashboard-out <path> Write dashboard HTML to a custom path");
     console.log("  --notify            Send Slack or Discord webhook summaries");
     console.log("  --notify-on <kind>  Send notifications on always, failure, or never");
+    console.log("  --pr-comment        Create or update a GitHub PR comment");
+    console.log("  --comment-on <kind> Post PR comment on always, failure, or new-findings");
     console.log("  --focus <kind>      Run all, health, duplicates, unused, outdated, or risks");
     console.log("  --ci                Apply low-noise CI defaults");
     console.log("  --config <path>     Path to depbrain.config.json");
@@ -396,3 +422,15 @@ function compareAdviceRisk(left, right) {
     const rank = { high: 3, medium: 2, low: 1 };
     return rank[left] - rank[right];
 }
+function parsePrCommentTrigger(value) {
+    if (value === "always" || value === "failure" || value === "new-findings") {
+        return value;
+    }
+    return "failure";
+}
+function countFindings(result) {
+    return (result.duplicates.length +
+        result.unused.length +
+        result.outdated.length +
+        result.risks.length);
+}

package/dist/index.d.ts

@@ -6,5 +6,8 @@ export type { DepBrainPlugin, PluginDiagnostic, ProjectContext } from "./core/pl
 export type { AnalysisContext, CheckResult, Issue } from "./core/types.js";
 export type { DepBrainConfig, DepBrainConfigOverrides } from "./utils/config.js";
 export { renderNotificationMessage, sendConfiguredNotifications, shouldSendNotification } from "./utils/notifications.js";
+export { shouldPostPrComment, upsertGitHubPrComment } from "./utils/github.js";
+export { PR_COMMENT_MARKER, renderPrCommentReport } from "./reporters/pr-comment.js";
 export type { NotificationChannel, NotificationResult, NotificationSendInput, NotificationSender } from "./utils/notifications.js";
+export type { GitHubPrCommentInput, GitHubPrCommentResult, GitHubRequest, PrCommentTrigger } from "./utils/github.js";
 export type { WorkspacePackage } from "./utils/workspaces.js";

package/dist/index.js

@@ -2,3 +2,5 @@ export { analyzeProject } from "./core/analyzer.js";
 export { OUTPUT_VERSION } from "./core/analyzer.js";
 export { PluginManager } from "./core/plugin-manager.js";
 export { renderNotificationMessage, sendConfiguredNotifications, shouldSendNotification } from "./utils/notifications.js";
+export { shouldPostPrComment, upsertGitHubPrComment } from "./utils/github.js";
+export { PR_COMMENT_MARKER, renderPrCommentReport } from "./reporters/pr-comment.js";

package/dist/reporters/pr-comment.d.ts

@@ -0,0 +1,6 @@
+import type { AnalysisResult } from "../core/analyzer.js";
+export declare const PR_COMMENT_MARKER = "<!-- dep-brain-report -->";
+export interface PrCommentOptions {
+    hasBaseline?: boolean;
+}
+export declare function renderPrCommentReport(result: AnalysisResult, options?: PrCommentOptions): string;

package/dist/reporters/pr-comment.js

@@ -0,0 +1,46 @@
+export const PR_COMMENT_MARKER = "<!-- dep-brain-report -->";
+export function renderPrCommentReport(result, options = {}) {
+    const lines = [
+        PR_COMMENT_MARKER,
+        "## Dependency Brain",
+        "",
+        `**Policy:** ${result.policy.passed ? "PASS" : "FAIL"}`,
+        `**Project Health:** ${result.score}/100`,
+        `**Findings:** duplicates ${result.duplicates.length}, unused ${result.unused.length}, outdated ${result.outdated.length}, risks ${result.risks.length}`
+    ];
+    if (options.hasBaseline) {
+        lines.push(`**New since baseline:** duplicates ${result.duplicates.length}, unused ${result.unused.length}, outdated ${result.outdated.length}, risks ${result.risks.length}`);
+    }
+    if (result.policy.reasons.length > 0) {
+        lines.push("");
+        lines.push("### Policy Reasons");
+        for (const reason of result.policy.reasons) {
+            lines.push(`- ${reason}`);
+        }
+    }
+    if (result.topIssues.length > 0) {
+        lines.push("");
+        lines.push("### Top Issues");
+        for (const item of result.topIssues.slice(0, 5)) {
+            lines.push(`- **${item.priority.toUpperCase()}** ${item.kind} \`${item.name}\`${item.package ? ` [${item.package}]` : ""}: ${item.summary}`);
+        }
+    }
+    const upgradePriorities = summarizeUpgradePriorities(result);
+    if (upgradePriorities) {
+        lines.push("");
+        lines.push("### Upgrade Priorities");
+        lines.push(upgradePriorities);
+    }
+    lines.push("");
+    lines.push("_Generated by dep-brain._");
+    return lines.join("\n");
+}
+function summarizeUpgradePriorities(result) {
+    const counts = result.outdated.reduce((acc, item) => {
+        acc[item.advice.risk] += 1;
+        return acc;
+    }, { high: 0, medium: 0, low: 0 });
+    return [`high ${counts.high}`, `medium ${counts.medium}`, `low ${counts.low}`]
+        .filter((entry) => !entry.endsWith(" 0"))
+        .join(", ");
+}

package/dist/utils/github.d.ts

@@ -0,0 +1,25 @@
+export type PrCommentTrigger = "always" | "failure" | "new-findings";
+export interface GitHubPrCommentInput {
+    body: string;
+    env?: Record<string, string | undefined>;
+    request?: GitHubRequest;
+}
+export interface GitHubPrCommentResult {
+    status: "created" | "updated" | "skipped";
+    reason?: string;
+}
+export type GitHubRequest = (url: string, init: {
+    method: "GET" | "POST" | "PATCH";
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export declare function upsertGitHubPrComment(input: GitHubPrCommentInput): Promise<GitHubPrCommentResult>;
+export declare function shouldPostPrComment(input: {
+    trigger: PrCommentTrigger;
+    policyPassed: boolean;
+    newFindingsCount: number;
+}): boolean;

package/dist/utils/github.js

@@ -0,0 +1,112 @@
+import { promises as fs } from "node:fs";
+import { PR_COMMENT_MARKER } from "../reporters/pr-comment.js";
+export async function upsertGitHubPrComment(input) {
+    const env = input.env ?? process.env;
+    const token = env.GITHUB_TOKEN;
+    const repository = env.GITHUB_REPOSITORY;
+    const eventPath = env.GITHUB_EVENT_PATH;
+    if (!token) {
+        return { status: "skipped", reason: "GITHUB_TOKEN is not set" };
+    }
+    if (!repository) {
+        return { status: "skipped", reason: "GITHUB_REPOSITORY is not set" };
+    }
+    if (!eventPath) {
+        return { status: "skipped", reason: "GITHUB_EVENT_PATH is not set" };
+    }
+    const pullNumber = await readPullNumber(eventPath);
+    if (!pullNumber) {
+        return { status: "skipped", reason: "pull request event not found" };
+    }
+    const request = input.request ?? defaultGitHubRequest;
+    const commentsUrl = `https://api.github.com/repos/${repository}/issues/${pullNumber}/comments`;
+    const headers = buildHeaders(token);
+    const existingResponse = await request(commentsUrl, {
+        method: "GET",
+        headers
+    });
+    if (!existingResponse.ok) {
+        return {
+            status: "skipped",
+            reason: `failed to list comments: HTTP ${existingResponse.status}`
+        };
+    }
+    const comments = normalizeComments(await existingResponse.json());
+    const existing = comments.find((comment) => typeof comment.body === "string" && comment.body.includes(PR_COMMENT_MARKER));
+    if (existing) {
+        const updateResponse = await request(`https://api.github.com/repos/${repository}/issues/comments/${existing.id}`, {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify({ body: input.body })
+        });
+        return updateResponse.ok
+            ? { status: "updated" }
+            : {
+                status: "skipped",
+                reason: `failed to update comment: HTTP ${updateResponse.status}`
+            };
+    }
+    const createResponse = await request(commentsUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ body: input.body })
+    });
+    return createResponse.ok
+        ? { status: "created" }
+        : {
+            status: "skipped",
+            reason: `failed to create comment: HTTP ${createResponse.status}`
+        };
+}
+export function shouldPostPrComment(input) {
+    if (input.trigger === "always") {
+        return true;
+    }
+    if (input.trigger === "failure") {
+        return !input.policyPassed;
+    }
+    return input.newFindingsCount > 0;
+}
+async function readPullNumber(eventPath) {
+    try {
+        const raw = await fs.readFile(eventPath, "utf8");
+        const event = JSON.parse(raw);
+        const value = event.pull_request?.number ?? event.number;
+        return typeof value === "number" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultGitHubRequest(url, init) {
+    const response = await fetch(url, init);
+    return {
+        ok: response.ok,
+        status: response.status,
+        json: () => response.json()
+    };
+}
+function buildHeaders(token) {
+    return {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "x-github-api-version": "2022-11-28"
+    };
+}
+function normalizeComments(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => {
+        if (!item || typeof item !== "object") {
+            return null;
+        }
+        const comment = item;
+        return typeof comment.id === "number"
+            ? { id: comment.id, body: comment.body }
+            : null;
+    })
+        .filter((item) => item !== null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dep-brain",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "CLI and library for explainable dependency intelligence",
   "type": "module",
   "main": "dist/index.js",