dep-brain 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
+- Added `--notify` and `--notify-on` CLI controls.
+- Added notification config with `enabled`, `on`, `slackWebhookEnv`, and `discordWebhookEnv`.
+- Added GitHub Action inputs for notification runs.
+- Kept analysis output contract at `1.6` because no JSON result fields changed.
+
 ## 1.5.0
 
 - Added structured upgrade advisor data under `outdated[].advice`.

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.5.1` adds upgrade-advice output, stepped major-version guidance, release-note links, and analysis output contract `1.6`.
+Current release `1.7.0` adds idempotent GitHub PR comments while keeping analysis output contract `1.6`.
 
 ## Vision
 
@@ -28,6 +28,8 @@ Current release `1.5.1` adds upgrade-advice output, stepped major-version guidan
 - Generate a simple project health score
 - 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
 
@@ -37,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.5 Highlights
+## 1.7 Highlights
 
 - Duplicate dependency detection with lockfile instance tracking
 - Unused dependency detection with runtime vs dev-tool heuristics
@@ -55,6 +57,8 @@ The long-term goal is not just to list problems, but to answer:
 - SARIF output via `--sarif`
 - 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`
@@ -84,6 +88,10 @@ npx dep-brain analyze --json --out depbrain.json
 npx dep-brain analyze --sarif --out depbrain.sarif
 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
@@ -169,7 +177,7 @@ Suggestions:
 dep-brain analyze --json
 ```
 
-Output includes `outputVersion` for schema stability. `dep-brain@1.5.1` writes contract version `1.6`.
+Output includes `outputVersion` for schema stability. `dep-brain@1.7.0` writes contract version `1.6`.
 
 Validate against:
 
@@ -206,6 +214,24 @@ dep-brain analyze --dashboard --dashboard-out reports/depbrain.html
 
 Writes a static HTML dashboard. Default path comes from `dashboard.outputPath`.
 
+## Notifications
+
+```bash
+DEPBRAIN_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... dep-brain analyze --notify
+DEPBRAIN_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... dep-brain analyze --notify --notify-on always
+```
+
+`--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
@@ -276,6 +302,8 @@ Create a `depbrain.config.json` file in the project root:
     "outputPath": "depbrain-dashboard.html"
   },
   "notifications": {
+    "enabled": false,
+    "on": "failure",
     "slackWebhookEnv": "DEPBRAIN_SLACK_WEBHOOK_URL",
     "discordWebhookEnv": "DEPBRAIN_DISCORD_WEBHOOK_URL"
   },
@@ -315,6 +343,8 @@ Supported sections:
 - `risk.lowTrustWeightThreshold`
 - `risk.mediumTrustWeightThreshold`
 - `dashboard.outputPath`
+- `notifications.enabled`
+- `notifications.on`
 - `notifications.slackWebhookEnv`
 - `notifications.discordWebhookEnv`
 - `scoring.duplicateWeight`
@@ -342,6 +372,8 @@ dep-brain analyze --fail-on-unused
 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
@@ -388,7 +420,7 @@ src/
 
 ## Product Direction
 
-`dep-brain` is in `v1.5.1` production CLI stage, with current focus on actionable dependency decisions instead of raw issue lists.
+`dep-brain` is in `v1.7.0` production CLI stage, with current focus on actionable dependency decisions and PR workflow integration.
 
 Recent releases added:
 
@@ -396,6 +428,8 @@ Recent releases added:
 - dashboard and plugin support
 - 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

@@ -51,6 +51,26 @@ inputs:
     description: Fail when risky dependencies are found.
     required: false
     default: "false"
+  notify:
+    description: Send Slack or Discord webhook summaries.
+    required: false
+    default: "false"
+  notify-on:
+    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
@@ -70,6 +90,11 @@ runs:
         INPUT_FAIL_ON_OUTDATED: ${{ inputs.fail-on-outdated }}
         INPUT_FAIL_ON_DUPLICATES: ${{ inputs.fail-on-duplicates }}
         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
 
@@ -127,6 +152,14 @@ runs:
           args+=("--fail-on-risks")
         fi
 
+        if [ "$INPUT_NOTIFY" = "true" ]; then
+          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/depbrain.config.json

@@ -36,6 +36,8 @@
     "outputPath": "depbrain-dashboard.html"
   },
   "notifications": {
+    "enabled": false,
+    "on": "failure",
     "slackWebhookEnv": "DEPBRAIN_SLACK_WEBHOOK_URL",
     "discordWebhookEnv": "DEPBRAIN_DISCORD_WEBHOOK_URL"
   },

package/depbrain.config.schema.json

@@ -68,6 +68,8 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "enabled": { "type": "boolean" },
+        "on": { "type": "string", "enum": ["always", "failure", "never"] },
         "slackWebhookEnv": { "type": "string" },
         "discordWebhookEnv": { "type": "string" }
       }

package/dist/cli.js

@@ -3,8 +3,11 @@ 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";
 import path from "node:path";
@@ -160,6 +163,42 @@ async function main() {
         if (flags.has("--dashboard")) {
             await writeOutput(renderDashboardReport(result), optionValues.get("--dashboard-out") ?? result.config.dashboard.outputPath);
         }
+        if (result.config.notifications.enabled) {
+            const notificationResults = await sendConfiguredNotifications(result);
+            for (const item of notificationResults) {
+                if (item.status === "sent") {
+                    console.error(`Notification sent to ${item.channel}.`);
+                }
+                else if (item.status === "failed") {
+                    console.error(`Notification failed for ${item.channel}: ${item.reason ?? "unknown error"}`);
+                }
+                else if (item.reason?.includes("webhook env")) {
+                    console.error(`Notification skipped for ${item.channel}: ${item.reason}`);
+                }
+            }
+        }
+        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;
         }
@@ -183,6 +222,7 @@ void main();
 function buildCliConfig(flags, optionValues) {
     const minScore = optionValues.get("--min-score");
     const policy = {};
+    const notifications = {};
     if (minScore) {
         policy.minScore = Number(minScore);
     }
@@ -203,8 +243,18 @@ function buildCliConfig(flags, optionValues) {
         policy.failOnDuplicates = true;
         policy.failOnRisks = true;
     }
+    if (flags.has("--notify")) {
+        notifications.enabled = true;
+    }
+    const notifyOn = optionValues.get("--notify-on");
+    if (notifyOn === "always" ||
+        notifyOn === "failure" ||
+        notifyOn === "never") {
+        notifications.on = notifyOn;
+    }
     return {
-        policy
+        policy,
+        notifications
     };
 }
 async function hasPackageJson(targetPath) {
@@ -220,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] [--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]");
@@ -235,6 +285,10 @@ function printHelp() {
     console.log("  --advise            Output upgrade advice for outdated dependencies");
     console.log("  --dashboard         Write an HTML dashboard");
     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");
@@ -368,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/core/analyzer.js

@@ -154,6 +154,8 @@ function mergeConfig(base, overrides) {
             outputPath: overrides.dashboard?.outputPath ?? base.dashboard.outputPath
         },
         notifications: {
+            enabled: overrides.notifications?.enabled ?? base.notifications.enabled,
+            on: overrides.notifications?.on ?? base.notifications.on,
             slackWebhookEnv: overrides.notifications?.slackWebhookEnv ?? base.notifications.slackWebhookEnv,
             discordWebhookEnv: overrides.notifications?.discordWebhookEnv ?? base.notifications.discordWebhookEnv
         },

package/dist/index.d.ts

@@ -5,4 +5,9 @@ export { PluginManager } from "./core/plugin-manager.js";
 export type { DepBrainPlugin, PluginDiagnostic, ProjectContext } from "./core/plugin-manager.js";
 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

@@ -1,3 +1,6 @@
 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/config.d.ts

@@ -36,6 +36,8 @@ export interface DepBrainConfig {
         outputPath: string;
     };
     notifications: {
+        enabled: boolean;
+        on: "always" | "failure" | "never";
         slackWebhookEnv: string;
         discordWebhookEnv: string;
     };

package/dist/utils/config.js

@@ -38,6 +38,8 @@ export const defaultConfig = {
         outputPath: "depbrain-dashboard.html"
     },
     notifications: {
+        enabled: false,
+        on: "failure",
         slackWebhookEnv: "DEPBRAIN_SLACK_WEBHOOK_URL",
         discordWebhookEnv: "DEPBRAIN_DISCORD_WEBHOOK_URL"
     },
@@ -100,6 +102,8 @@ function normalizeConfig(loaded) {
             outputPath: normalizeString(loaded.dashboard?.outputPath, defaultConfig.dashboard.outputPath)
         },
         notifications: {
+            enabled: normalizeBoolean(loaded.notifications?.enabled, defaultConfig.notifications.enabled),
+            on: normalizeNotificationTrigger(loaded.notifications?.on, defaultConfig.notifications.on),
             slackWebhookEnv: normalizeString(loaded.notifications?.slackWebhookEnv, defaultConfig.notifications.slackWebhookEnv),
             discordWebhookEnv: normalizeString(loaded.notifications?.discordWebhookEnv, defaultConfig.notifications.discordWebhookEnv)
         },
@@ -129,3 +133,8 @@ function normalizeNumber(value, fallback) {
 function normalizeString(value, fallback) {
     return typeof value === "string" && value.trim().length > 0 ? value : fallback;
 }
+function normalizeNotificationTrigger(value, fallback) {
+    return value === "always" || value === "failure" || value === "never"
+        ? value
+        : fallback;
+}

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/dist/utils/notifications.d.ts

@@ -0,0 +1,20 @@
+import type { AnalysisResult } from "../core/analyzer.js";
+import type { DepBrainConfig } from "./config.js";
+export type NotificationChannel = "slack" | "discord";
+export interface NotificationSendInput {
+    channel: NotificationChannel;
+    webhookUrl: string;
+    payload: unknown;
+}
+export interface NotificationResult {
+    channel: NotificationChannel;
+    status: "sent" | "skipped" | "failed";
+    reason?: string;
+}
+export type NotificationSender = (input: NotificationSendInput) => Promise<void>;
+export declare function sendConfiguredNotifications(result: AnalysisResult, options?: {
+    env?: Record<string, string | undefined>;
+    sender?: NotificationSender;
+}): Promise<NotificationResult[]>;
+export declare function shouldSendNotification(result: AnalysisResult, config: DepBrainConfig["notifications"]): boolean;
+export declare function renderNotificationMessage(result: AnalysisResult): string;

package/dist/utils/notifications.js

@@ -0,0 +1,116 @@
+export async function sendConfiguredNotifications(result, options = {}) {
+    const config = result.config.notifications;
+    if (!shouldSendNotification(result, config)) {
+        return [
+            {
+                channel: "slack",
+                status: "skipped",
+                reason: "notification trigger did not match analysis result"
+            },
+            {
+                channel: "discord",
+                status: "skipped",
+                reason: "notification trigger did not match analysis result"
+            }
+        ];
+    }
+    const env = options.env ?? process.env;
+    const sender = options.sender ?? postWebhook;
+    const message = renderNotificationMessage(result);
+    const targets = [
+        {
+            channel: "slack",
+            webhookUrl: env[config.slackWebhookEnv],
+            payload: { text: message }
+        },
+        {
+            channel: "discord",
+            webhookUrl: env[config.discordWebhookEnv],
+            payload: { content: message }
+        }
+    ];
+    const results = [];
+    for (const target of targets) {
+        if (!target.webhookUrl) {
+            results.push({
+                channel: target.channel,
+                status: "skipped",
+                reason: `${target.channel} webhook env is not set`
+            });
+            continue;
+        }
+        try {
+            await sender({
+                channel: target.channel,
+                webhookUrl: target.webhookUrl,
+                payload: target.payload
+            });
+            results.push({ channel: target.channel, status: "sent" });
+        }
+        catch (error) {
+            results.push({
+                channel: target.channel,
+                status: "failed",
+                reason: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return results;
+}
+export function shouldSendNotification(result, config) {
+    if (!config.enabled || config.on === "never") {
+        return false;
+    }
+    return config.on === "always" || !result.policy.passed;
+}
+export function renderNotificationMessage(result) {
+    const status = result.policy.passed ? "PASS" : "FAIL";
+    const counts = [
+        `duplicates ${result.duplicates.length}`,
+        `unused ${result.unused.length}`,
+        `outdated ${result.outdated.length}`,
+        `risks ${result.risks.length}`
+    ].join(", ");
+    const lines = [
+        `dep-brain ${status}: score ${result.score}/100`,
+        `path: ${result.rootDir}`,
+        `findings: ${counts}`
+    ];
+    const upgradePriorities = buildUpgradePriorityText(result);
+    if (result.policy.reasons.length > 0) {
+        lines.push(`policy: ${result.policy.reasons.join("; ")}`);
+    }
+    if (result.topIssues.length > 0) {
+        lines.push("top issues:");
+        for (const issue of result.topIssues.slice(0, 3)) {
+            lines.push(`- ${formatTopIssue(issue)}`);
+        }
+    }
+    if (upgradePriorities) {
+        lines.push(`upgrades: ${upgradePriorities}`);
+    }
+    return lines.join("\n");
+}
+async function postWebhook(input) {
+    const response = await fetch(input.webhookUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input.payload)
+    });
+    if (!response.ok) {
+        throw new Error(`${input.channel} webhook failed with HTTP ${response.status}`);
+    }
+}
+function formatTopIssue(issue) {
+    const owner = issue.package ? ` [${issue.package}]` : "";
+    return `[${issue.priority}] ${issue.kind} ${issue.name}${owner}: ${issue.summary}`;
+}
+function buildUpgradePriorityText(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/package.json

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