dep-brain 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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,6 +6,8 @@
 
 `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`.
+
 ## Vision
 
 `dep-brain` aims to become a dependency decision engine:
@@ -26,6 +28,7 @@
 - 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
 - Gate CI with score and finding policies
 - Compare new findings against a baseline report
 
@@ -35,7 +38,7 @@ The long-term goal is not just to list problems, but to answer:
 - Can I remove it safely?
 - What should I fix first?
 
-## v1 Features
+## 1.6 Highlights
 
 - Duplicate dependency detection with lockfile instance tracking
 - Unused dependency detection with runtime vs dev-tool heuristics
@@ -53,6 +56,7 @@ 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`
 - Ranked top issues via `--top`
 - Baseline mode via `--baseline`
 - Focused analysis via `--focus`
@@ -82,6 +86,8 @@ 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 --focus duplicates
 npx dep-brain analyze --ci
 npx dep-brain analyze --baseline depbrain-baseline.json
@@ -167,7 +173,9 @@ Suggestions:
 dep-brain analyze --json
 ```
 
-Output includes `outputVersion` for schema stability and can be validated with:
+Output includes `outputVersion` for schema stability. `dep-brain@1.6.0` writes contract version `1.6`.
+
+Validate against:
 
 - `depbrain.output.schema.json`
 
@@ -202,6 +210,15 @@ 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.
+
 ## Plugins
 
 ```json
@@ -272,6 +289,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"
   },
@@ -311,6 +330,8 @@ Supported sections:
 - `risk.lowTrustWeightThreshold`
 - `risk.mediumTrustWeightThreshold`
 - `dashboard.outputPath`
+- `notifications.enabled`
+- `notifications.on`
 - `notifications.slackWebhookEnv`
 - `notifications.discordWebhookEnv`
 - `scoring.duplicateWeight`
@@ -338,6 +359,7 @@ 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
 ```
 
 ## Config Debugging
@@ -384,17 +406,19 @@ src/
 
 ## Product Direction
 
-`dep-brain` is in its `v1.0.0` production-ready CLI stage. The roadmap delivered through v1:
+`dep-brain` is in `v1.6.0` production CLI stage, with current focus on actionable dependency decisions and CI workflow integration.
+
+Recent releases added:
 
-- `v0.6`: explainability and confidence scoring
-- `v0.7`: safe removal guidance and actionable recommendations
-- `v0.8`: supply-chain trust and risk intelligence
-- `v0.9`: deeper monorepo and ownership intelligence
-- `v1.0`: stable CI, ecosystem exports, and production readiness
+- transitive risk ownership and path tracing
+- dashboard and plugin support
+- baseline, focus, and CI workflows
+- structured upgrade advice with release-note links
+- Slack and Discord notification summaries
 
-The project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
+Project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
 
-Risk findings now include a `trustScore`, structured `riskFactors`, `transitiveRiskScore`, and `riskyTransitiveDeps` path traces so teams can see which direct package introduces supply-chain risk.
+Risk findings include `trustScore`, structured `riskFactors`, `transitiveRiskScore`, and `riskyTransitiveDeps` path traces so teams can see which direct package introduces supply-chain risk.
 
 ## Repository Notes
 

package/action.yml

@@ -51,6 +51,14 @@ 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"
 
 runs:
   using: composite
@@ -70,6 +78,8 @@ 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 }}
       run: |
         set -euo pipefail
 
@@ -127,6 +137,10 @@ runs:
           args+=("--fail-on-risks")
         fi
 
+        if [ "$INPUT_NOTIFY" = "true" ]; then
+          args+=("--notify" "--notify-on" "$INPUT_NOTIFY_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

@@ -5,6 +5,7 @@ import { renderJsonReport } from "./reporters/json.js";
 import { renderMarkdownReport } from "./reporters/markdown.js";
 import { renderSarifReport } from "./reporters/sarif.js";
 import { renderDashboardReport } from "./reporters/dashboard.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 +161,20 @@ 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 (!result.policy.passed) {
             process.exitCode = 1;
         }
@@ -183,6 +198,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 +219,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 +246,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] [--notify-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 +261,8 @@ 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("  --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");

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,6 @@ 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 type { NotificationChannel, NotificationResult, NotificationSendInput, NotificationSender } from "./utils/notifications.js";
 export type { WorkspacePackage } from "./utils/workspaces.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 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";

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/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.0",
+  "version": "1.6.0",
   "description": "CLI and library for explainable dependency intelligence",
   "type": "module",
   "main": "dist/index.js",