dep-brain 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.3.0
+
+- Added plugin diagnostics under `extensions.depBrain.plugins` for failed plugin loads and hook errors.
+- Added built-in `license` plugin through `plugins.enabled: ["license"]`.
+- Added configurable risk thresholds for stale release days, aging release days, low downloads, and trust score weights.
+- Added `--dashboard` and `--dashboard-out` for static HTML dashboard generation.
+- Updated starter config, schemas, README, and tests for v1.3 behavior.
+
+## 1.2.0
+
+- Added `PluginManager` with `preScan`, `postScan`, and `reportHook` lifecycle support.
+- Added disabled-by-default plugin config through `plugins.enabled` and `plugins.paths`.
+- Added `extensions` to analysis output so plugins can enrich results without breaking schema.
+- Added future config slots for risk thresholds, dashboard output, and notification webhook env names.
+- Added regression coverage for plugin hooks enriching `extensions`.
+
 ## 1.1.0
 
 - Added `--focus` modes for targeted duplicate, unused, outdated, risk, and health analysis.

package/README.md

@@ -23,7 +23,7 @@
 - Highlight dependency risk signals
 - Score package trust using supply-chain metadata
 - Generate a simple project health score
-- Output reports in console, JSON, Markdown, SARIF, and top-issues formats
+- Output reports in console, JSON, Markdown, SARIF, dashboard, and top-issues formats
 - Gate CI with score and finding policies
 - Compare new findings against a baseline report
 
@@ -48,12 +48,14 @@ The long-term goal is not just to list problems, but to answer:
 - JSON output via `--json`
 - Markdown output via `--md`
 - SARIF output via `--sarif`
+- Static HTML dashboard via `--dashboard`
 - Ranked top issues via `--top`
 - Baseline mode via `--baseline`
 - Focused analysis via `--focus`
 - Low-noise CI defaults via `--ci`
 - Starter config generation via `dep-brain init`
 - Reusable GitHub Action via `action.yml`
+- Built-in `license` plugin and plugin diagnostics
 - Library entrypoint for programmatic use
 
 ## CLI Usage
@@ -73,6 +75,8 @@ npx dep-brain analyze ./path-to-project --fail-on-unused --json
 npx dep-brain analyze --md > depbrain.md
 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 --focus duplicates
 npx dep-brain analyze --ci
 npx dep-brain analyze --baseline depbrain-baseline.json
@@ -176,6 +180,28 @@ dep-brain analyze --top
 
 Shows the highest-priority actionable findings first, including confidence and next-step guidance.
 
+## Dashboard Output
+
+```bash
+dep-brain analyze --dashboard
+dep-brain analyze --dashboard --dashboard-out reports/depbrain.html
+```
+
+Writes a static HTML dashboard. Default path comes from `dashboard.outputPath`.
+
+## Plugins
+
+```json
+{
+  "plugins": {
+    "enabled": ["license"],
+    "paths": ["./depbrain-plugin.mjs"]
+  }
+}
+```
+
+Built-in `license` plugin adds license counts under `extensions.license`. Failed plugin loads and hook errors are reported under `extensions.depBrain.plugins`.
+
 ## Report From JSON
 
 ```bash
@@ -194,30 +220,6 @@ dep-brain analyze --baseline depbrain-baseline.json --min-score 90 --fail-on-ris
 
 The baseline file is a normal JSON analysis report. Matching entries in `duplicates`, `unused`, `outdated`, and `risks` are ignored before score, policy, suggestions, and top issues are calculated.
 
-## GitHub Action
-
-```yaml
-name: Dependency Brain
-
-on:
-  pull_request:
-
-jobs:
-  dep-brain:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - uses: prakashu51/dep-brain@v1
-        with:
-          format: sarif
-          out: depbrain.sarif
-          min-score: 85
-          fail-on-risks: "true"
-```
-
 ## Config File
 
 Create a `depbrain.config.json` file in the project root:
@@ -238,6 +240,26 @@ Create a `depbrain.config.json` file in the project root:
   "report": {
     "maxSuggestions": 3
   },
+  "plugins": {
+    "enabled": ["license"],
+    "paths": []
+  },
+  "risk": {
+    "transitiveBloatThreshold": 50,
+    "typosquattingDistanceThreshold": 2,
+    "staleReleaseDays": 730,
+    "agingReleaseDays": 365,
+    "lowDownloadThreshold": 1000,
+    "lowTrustWeightThreshold": 6,
+    "mediumTrustWeightThreshold": 3
+  },
+  "dashboard": {
+    "outputPath": "depbrain-dashboard.html"
+  },
+  "notifications": {
+    "slackWebhookEnv": "DEPBRAIN_SLACK_WEBHOOK_URL",
+    "discordWebhookEnv": "DEPBRAIN_DISCORD_WEBHOOK_URL"
+  },
   "scoring": {
     "duplicateWeight": 5,
     "outdatedWeight": 1,
@@ -264,6 +286,18 @@ Supported sections:
 - `policy.failOnOutdated`
 - `policy.failOnRisks`
 - `report.maxSuggestions`
+- `plugins.enabled`
+- `plugins.paths`
+- `risk.transitiveBloatThreshold`
+- `risk.typosquattingDistanceThreshold`
+- `risk.staleReleaseDays`
+- `risk.agingReleaseDays`
+- `risk.lowDownloadThreshold`
+- `risk.lowTrustWeightThreshold`
+- `risk.mediumTrustWeightThreshold`
+- `dashboard.outputPath`
+- `notifications.slackWebhookEnv`
+- `notifications.discordWebhookEnv`
 - `scoring.duplicateWeight`
 - `scoring.outdatedWeight`
 - `scoring.unusedWeight`

package/depbrain.config.json

@@ -19,6 +19,26 @@
   "report": {
     "maxSuggestions": 5
   },
+  "plugins": {
+    "enabled": [],
+    "paths": []
+  },
+  "risk": {
+    "transitiveBloatThreshold": 50,
+    "typosquattingDistanceThreshold": 2,
+    "staleReleaseDays": 730,
+    "agingReleaseDays": 365,
+    "lowDownloadThreshold": 1000,
+    "lowTrustWeightThreshold": 6,
+    "mediumTrustWeightThreshold": 3
+  },
+  "dashboard": {
+    "outputPath": "depbrain-dashboard.html"
+  },
+  "notifications": {
+    "slackWebhookEnv": "DEPBRAIN_SLACK_WEBHOOK_URL",
+    "discordWebhookEnv": "DEPBRAIN_DISCORD_WEBHOOK_URL"
+  },
   "scoring": {
     "duplicateWeight": 5,
     "outdatedWeight": 3,

package/depbrain.config.schema.json

@@ -36,6 +36,42 @@
         "maxSuggestions": { "type": "number" }
       }
     },
+    "plugins": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "array", "items": { "type": "string" } },
+        "paths": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "risk": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "transitiveBloatThreshold": { "type": "number" },
+        "typosquattingDistanceThreshold": { "type": "number" },
+        "staleReleaseDays": { "type": "number" },
+        "agingReleaseDays": { "type": "number" },
+        "lowDownloadThreshold": { "type": "number" },
+        "lowTrustWeightThreshold": { "type": "number" },
+        "mediumTrustWeightThreshold": { "type": "number" }
+      }
+    },
+    "dashboard": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "outputPath": { "type": "string" }
+      }
+    },
+    "notifications": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "slackWebhookEnv": { "type": "string" },
+        "discordWebhookEnv": { "type": "string" }
+      }
+    },
     "scoring": {
       "type": "object",
       "additionalProperties": false,

package/depbrain.output.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Dependency Brain Analysis Output",
   "type": "object",
-  "required": ["outputVersion", "rootDir", "score", "scoreBreakdown", "policy", "ownershipSummary", "duplicates", "unused", "outdated", "risks", "suggestions", "topIssues", "config"],
+  "required": ["outputVersion", "rootDir", "score", "scoreBreakdown", "policy", "ownershipSummary", "duplicates", "unused", "outdated", "risks", "suggestions", "topIssues", "extensions", "config"],
   "additionalProperties": false,
   "properties": {
     "recommendation": {
@@ -175,6 +175,10 @@
       }
     },
     "suggestions": { "type": "array", "items": { "type": "string" } },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true
+    },
     "topIssues": {
       "type": "array",
       "items": {

package/dist/checks/risk.d.ts

@@ -2,8 +2,10 @@ import type { DependencyGraph } from "../core/graph-builder.js";
 import type { RiskDependency } from "../core/analyzer.js";
 import type { CheckResult } from "../core/types.js";
 import { type PackageMetadata } from "../utils/npm-api.js";
+import type { DepBrainConfig } from "../utils/config.js";
 export interface RiskCheckOptions {
     resolvePackageMetadata?: (name: string) => Promise<PackageMetadata | null>;
+    thresholds?: DepBrainConfig["risk"];
 }
 export declare function findRiskDependencies(graph: DependencyGraph, options?: RiskCheckOptions): Promise<RiskDependency[]>;
-export declare function runRiskCheck(graph: DependencyGraph): Promise<CheckResult>;
+export declare function runRiskCheck(graph: DependencyGraph, options?: RiskCheckOptions): Promise<CheckResult>;

package/dist/checks/risk.js

@@ -1,6 +1,4 @@
 import { getPackageMetadata } from "../utils/npm-api.js";
-const TWO_YEARS_IN_DAYS = 365 * 2;
-const ONE_YEAR_IN_DAYS = 365;
 export async function findRiskDependencies(graph, options = {}) {
     const resolvePackageMetadata = options.resolvePackageMetadata ?? getPackageMetadata;
     const names = Object.keys({
@@ -17,7 +15,7 @@ export async function findRiskDependencies(graph, options = {}) {
             : graph.devDependencies[name]
                 ? "devDependencies"
                 : "unknown";
-        const assessment = assessRisk(metadata, dependencyType);
+        const assessment = assessRisk(metadata, dependencyType, options.thresholds);
         if (!shouldReportRisk(assessment.trustScore, dependencyType)) {
             return null;
         }
@@ -50,8 +48,8 @@ async function mapWithConcurrency(items, limit, mapper) {
     await Promise.all(workers);
     return results;
 }
-export async function runRiskCheck(graph) {
-    const risks = await findRiskDependencies(graph);
+export async function runRiskCheck(graph, options = {}) {
+    const risks = await findRiskDependencies(graph, options);
     return {
         name: "risk",
         summary: `${risks.length} risky dependencies found`,
@@ -75,22 +73,27 @@ export async function runRiskCheck(graph) {
         }))
     };
 }
-function assessRisk(metadata, dependencyType) {
+function assessRisk(metadata, dependencyType, thresholds) {
     const reasons = [];
     const reasonCodes = [];
     let weight = 0;
-    if (metadata.daysSincePublish !== null && metadata.daysSincePublish > TWO_YEARS_IN_DAYS) {
-        reasons.push("No release in over 2 years");
+    const staleReleaseDays = thresholds?.staleReleaseDays ?? 730;
+    const agingReleaseDays = thresholds?.agingReleaseDays ?? 365;
+    const lowDownloadThreshold = thresholds?.lowDownloadThreshold ?? 1000;
+    const lowTrustWeightThreshold = thresholds?.lowTrustWeightThreshold ?? 6;
+    const mediumTrustWeightThreshold = thresholds?.mediumTrustWeightThreshold ?? 3;
+    if (metadata.daysSincePublish !== null && metadata.daysSincePublish > staleReleaseDays) {
+        reasons.push(`No release in over ${formatDays(staleReleaseDays)}`);
         reasonCodes.push("stale_release");
         weight += 3;
     }
     else if (metadata.daysSincePublish !== null &&
-        metadata.daysSincePublish > ONE_YEAR_IN_DAYS) {
-        reasons.push("No release in over 12 months");
+        metadata.daysSincePublish > agingReleaseDays) {
+        reasons.push(`No release in over ${formatDays(agingReleaseDays)}`);
         reasonCodes.push("aging_release");
         weight += 2;
     }
-    if (metadata.downloads !== null && metadata.downloads < 1000) {
+    if (metadata.downloads !== null && metadata.downloads < lowDownloadThreshold) {
         reasons.push("Low weekly download volume");
         reasonCodes.push("low_download_volume");
         weight += 2;
@@ -118,7 +121,11 @@ function assessRisk(metadata, dependencyType) {
         weight += 1;
     }
     const confidence = reasons.length === 0 ? 0.5 : Math.min(0.99, 0.52 + weight * 0.07);
-    const trustScore = weight >= 6 ? "low" : weight >= 3 ? "medium" : "high";
+    const trustScore = weight >= lowTrustWeightThreshold
+        ? "low"
+        : weight >= mediumTrustWeightThreshold
+            ? "medium"
+            : "high";
     return {
         confidence,
         trustScore,
@@ -135,6 +142,15 @@ function assessRisk(metadata, dependencyType) {
         }
     };
 }
+function formatDays(days) {
+    if (days === 730) {
+        return "2 years";
+    }
+    if (days === 365) {
+        return "12 months";
+    }
+    return `${days} days`;
+}
 function shouldReportRisk(trustScore, dependencyType) {
     if (trustScore === "high") {
         return false;

package/dist/cli.js

@@ -4,6 +4,7 @@ import { renderConsoleReport } from "./reporters/console.js";
 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 { defaultConfig } from "./utils/config.js";
 import { promises as fs } from "node:fs";
 import path from "node:path";
@@ -59,7 +60,9 @@ async function main() {
                         ? JSON.stringify(reportData, null, 2)
                         : flags.has("--sarif")
                             ? renderSarifReport(reportData)
-                            : renderMarkdownReport(reportData);
+                            : flags.has("--dashboard")
+                                ? renderDashboardReport(reportData)
+                                : renderMarkdownReport(reportData);
                 await writeOutput(output, optionValues.get("--out"));
                 return;
             }
@@ -149,6 +152,9 @@ async function main() {
                     : consoleOutput;
         }
         await writeOutput(output, optionValues.get("--out"));
+        if (flags.has("--dashboard")) {
+            await writeOutput(renderDashboardReport(result), optionValues.get("--dashboard-out") ?? result.config.dashboard.outputPath);
+        }
         if (!result.policy.passed) {
             process.exitCode = 1;
         }
@@ -209,8 +215,8 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--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] [--out path]");
+    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 report --from <file> [--md] [--json] [--sarif] [--top] [--dashboard] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain init [--out depbrain.config.json]");
     console.log("  dep-brain help");
@@ -221,6 +227,8 @@ function printHelp() {
     console.log("  --md                Output Markdown report");
     console.log("  --sarif             Output SARIF format for Code Scanning");
     console.log("  --top               Output the ranked top issues only");
+    console.log("  --dashboard         Write an HTML dashboard");
+    console.log("  --dashboard-out <path> Write dashboard HTML to a custom path");
     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.d.ts

@@ -110,6 +110,7 @@ export interface AnalysisResult {
     risks: RiskDependency[];
     suggestions: string[];
     topIssues: TopIssue[];
+    extensions: Record<string, unknown>;
     config: DepBrainConfig;
     packages?: PackageAnalysisResult[];
 }
@@ -130,6 +131,7 @@ export interface PackageAnalysisResult {
     risks: RiskDependency[];
     suggestions: string[];
     topIssues: TopIssue[];
+    extensions: Record<string, unknown>;
 }
 export declare const OUTPUT_VERSION = "1.4";
 export interface ScoreBreakdown {

package/dist/core/analyzer.js

@@ -6,6 +6,7 @@ import { runUnusedCheck } from "../checks/unused.js";
 import { loadDepBrainConfig } from "../utils/config.js";
 import { findWorkspacePackages } from "../utils/workspaces.js";
 import { buildDependencyGraph } from "./graph-builder.js";
+import { PluginManager } from "./plugin-manager.js";
 import { calculateHealthScore, calculateScoreDeductions } from "./scorer.js";
 import { buildAnalysisContext } from "./context.js";
 export const OUTPUT_VERSION = "1.4";
@@ -14,12 +15,15 @@ export async function analyzeProject(options = {}) {
     const loadedConfig = await loadDepBrainConfig(rootDir, options.configPath);
     const config = mergeConfig(loadedConfig, options.config);
     const focus = options.focus ?? "all";
+    const plugins = await PluginManager.load(rootDir, config);
+    await plugins.runPreScan({ rootDir, config });
     const workspaces = await findWorkspacePackages(rootDir);
     if (workspaces.length === 0) {
-        return analyzeSingleProject(rootDir, config, {
+        const result = await analyzeSingleProject(rootDir, config, {
             baseline: options.baseline,
             focus
         });
+        return plugins.runPostScan(result);
     }
     const rootGraph = await buildDependencyGraph(rootDir);
     const duplicates = shouldRunCheck("duplicate", focus)
@@ -79,7 +83,7 @@ export async function analyzeProject(options = {}) {
         outdated: outdated.length,
         risks: risks.length
     }, config);
-    return {
+    const result = {
         outputVersion: OUTPUT_VERSION,
         rootDir,
         score,
@@ -102,9 +106,11 @@ export async function analyzeProject(options = {}) {
             outdated,
             risks
         }),
+        extensions: {},
         config,
         packages
     };
+    return plugins.runPostScan(result);
 }
 function mergeConfig(base, overrides) {
     if (!overrides) {
@@ -131,6 +137,26 @@ function mergeConfig(base, overrides) {
         report: {
             maxSuggestions: overrides.report?.maxSuggestions ?? base.report.maxSuggestions
         },
+        plugins: {
+            enabled: overrides.plugins?.enabled ?? base.plugins.enabled,
+            paths: overrides.plugins?.paths ?? base.plugins.paths
+        },
+        risk: {
+            transitiveBloatThreshold: overrides.risk?.transitiveBloatThreshold ?? base.risk.transitiveBloatThreshold,
+            typosquattingDistanceThreshold: overrides.risk?.typosquattingDistanceThreshold ?? base.risk.typosquattingDistanceThreshold,
+            staleReleaseDays: overrides.risk?.staleReleaseDays ?? base.risk.staleReleaseDays,
+            agingReleaseDays: overrides.risk?.agingReleaseDays ?? base.risk.agingReleaseDays,
+            lowDownloadThreshold: overrides.risk?.lowDownloadThreshold ?? base.risk.lowDownloadThreshold,
+            lowTrustWeightThreshold: overrides.risk?.lowTrustWeightThreshold ?? base.risk.lowTrustWeightThreshold,
+            mediumTrustWeightThreshold: overrides.risk?.mediumTrustWeightThreshold ?? base.risk.mediumTrustWeightThreshold
+        },
+        dashboard: {
+            outputPath: overrides.dashboard?.outputPath ?? base.dashboard.outputPath
+        },
+        notifications: {
+            slackWebhookEnv: overrides.notifications?.slackWebhookEnv ?? base.notifications.slackWebhookEnv,
+            discordWebhookEnv: overrides.notifications?.discordWebhookEnv ?? base.notifications.discordWebhookEnv
+        },
         scoring: {
             duplicateWeight: overrides.scoring?.duplicateWeight ?? base.scoring.duplicateWeight,
             outdatedWeight: overrides.scoring?.outdatedWeight ?? base.scoring.outdatedWeight,
@@ -166,7 +192,7 @@ function evaluatePolicy(summary, config) {
 }
 async function analyzeSingleProject(rootDir, config, options = {}) {
     const context = await buildAnalysisContext(rootDir, config);
-    const results = await runChecks(context, options.focus ?? "all");
+    const results = await runChecks(context, options.focus ?? "all", config);
     const issueGroups = normalizeIssues(results, config);
     const duplicates = mapDuplicateIssues(issueGroups.duplicates);
     const unused = mapUnusedIssues(issueGroups.unused);
@@ -238,6 +264,7 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
             outdated: baselineFiltered.outdated,
             risks: baselineFiltered.risks
         }),
+        extensions: {},
         config
     };
 }
@@ -258,7 +285,7 @@ function shouldIgnorePackage(name, bucket, config) {
         }
     });
 }
-async function runChecks(context, focus) {
+async function runChecks(context, focus, config) {
     const checks = [
         {
             name: "duplicate",
@@ -274,7 +301,7 @@ async function runChecks(context, focus) {
         },
         {
             name: "risk",
-            run: () => runRiskCheck(context.graph)
+            run: () => runRiskCheck(context.graph, { thresholds: config.risk })
         }
     ];
     const results = [];

package/dist/core/plugin-manager.d.ts

@@ -0,0 +1,29 @@
+import type { AnalysisResult } from "./analyzer.js";
+import type { DepBrainConfig } from "../utils/config.js";
+export interface ProjectContext {
+    rootDir: string;
+    config: DepBrainConfig;
+}
+export interface DepBrainPlugin {
+    name: string;
+    preScan?: (context: ProjectContext) => Promise<void> | void;
+    postScan?: (result: AnalysisResult) => Promise<AnalysisResult | void> | AnalysisResult | void;
+    reportHook?: (result: AnalysisResult) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+    cliCommands?: (cli: unknown) => void;
+}
+export interface PluginDiagnostic {
+    spec: string;
+    code: "load_failed" | "invalid_plugin" | "hook_failed";
+    message: string;
+    plugin?: string;
+    hook?: "preScan" | "postScan" | "reportHook";
+}
+export declare class PluginManager {
+    private readonly plugins;
+    private readonly diagnostics;
+    private constructor();
+    static load(rootDir: string, config: DepBrainConfig): Promise<PluginManager>;
+    runPreScan(context: ProjectContext): Promise<void>;
+    runPostScan(result: AnalysisResult): Promise<AnalysisResult>;
+    private attachDiagnostics;
+}

package/dist/core/plugin-manager.js

@@ -0,0 +1,193 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+export class PluginManager {
+    plugins;
+    diagnostics;
+    constructor(plugins, diagnostics) {
+        this.plugins = plugins;
+        this.diagnostics = diagnostics;
+    }
+    static async load(rootDir, config) {
+        const specs = [
+            ...config.plugins.enabled.map((name) => `dep-brain-plugin-${name}`),
+            ...config.plugins.paths
+        ];
+        const plugins = [];
+        const diagnostics = [];
+        for (const spec of specs) {
+            const result = await loadPlugin(rootDir, spec);
+            if (result.plugin) {
+                plugins.push(result.plugin);
+            }
+            if (result.diagnostic) {
+                diagnostics.push(result.diagnostic);
+            }
+        }
+        return new PluginManager(plugins, diagnostics);
+    }
+    async runPreScan(context) {
+        for (const plugin of this.plugins) {
+            try {
+                await plugin.preScan?.(context);
+            }
+            catch (error) {
+                this.diagnostics.push(buildHookDiagnostic(plugin.name, "preScan", error));
+            }
+        }
+    }
+    async runPostScan(result) {
+        let current = result;
+        for (const plugin of this.plugins) {
+            try {
+                const next = await plugin.postScan?.(current);
+                if (next) {
+                    current = next;
+                }
+            }
+            catch (error) {
+                this.diagnostics.push(buildHookDiagnostic(plugin.name, "postScan", error));
+            }
+            try {
+                const reportSection = await plugin.reportHook?.(current);
+                if (reportSection) {
+                    current.extensions[plugin.name] = {
+                        ...(asRecord(current.extensions[plugin.name]) ?? {}),
+                        ...reportSection
+                    };
+                }
+            }
+            catch (error) {
+                this.diagnostics.push(buildHookDiagnostic(plugin.name, "reportHook", error));
+            }
+        }
+        return this.attachDiagnostics(current);
+    }
+    attachDiagnostics(result) {
+        if (this.diagnostics.length === 0) {
+            return result;
+        }
+        result.extensions.depBrain = {
+            ...(asRecord(result.extensions.depBrain) ?? {}),
+            plugins: this.diagnostics
+        };
+        return result;
+    }
+}
+async function loadPlugin(rootDir, spec) {
+    const builtIn = getBuiltInPlugin(spec);
+    if (builtIn) {
+        return { plugin: builtIn };
+    }
+    try {
+        const resolved = spec.startsWith(".") || path.isAbsolute(spec)
+            ? path.resolve(rootDir, spec)
+            : spec;
+        const moduleUrl = path.isAbsolute(resolved) ? pathToFileURL(resolved).href : resolved;
+        const mod = await import(moduleUrl);
+        const exported = mod.default ?? mod.plugin ?? mod;
+        const candidate = typeof exported === "function" ? new exported() : exported;
+        if (isPlugin(candidate)) {
+            return { plugin: candidate };
+        }
+        return {
+            plugin: null,
+            diagnostic: {
+                spec,
+                code: "invalid_plugin",
+                message: "Plugin must export an object with a string name."
+            }
+        };
+    }
+    catch (error) {
+        return {
+            plugin: null,
+            diagnostic: {
+                spec,
+                code: "load_failed",
+                message: error instanceof Error ? error.message : String(error)
+            }
+        };
+    }
+}
+function getBuiltInPlugin(spec) {
+    if (spec !== "license" && spec !== "dep-brain-plugin-license") {
+        return null;
+    }
+    return {
+        name: "license",
+        reportHook: async (result) => {
+            const packages = await collectLicensePackages(result.rootDir);
+            const licenses = packages.reduce((acc, item) => {
+                acc[item.license] = (acc[item.license] ?? 0) + 1;
+                return acc;
+            }, {});
+            return {
+                summary: {
+                    total: packages.length,
+                    unknown: packages.filter((item) => item.license === "UNKNOWN").length,
+                    licenses
+                },
+                packages
+            };
+        }
+    };
+}
+async function collectLicensePackages(rootDir) {
+    const raw = await fs.readFile(path.join(rootDir, "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    const names = Object.keys({
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {})
+    }).sort();
+    return Promise.all(names.map(async (name) => ({
+        name,
+        license: await readPackageLicense(rootDir, name)
+    })));
+}
+async function readPackageLicense(rootDir, name) {
+    try {
+        const raw = await fs.readFile(path.join(rootDir, "node_modules", name, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        if (typeof pkg.license === "string" && pkg.license.trim().length > 0) {
+            return pkg.license;
+        }
+        if (Array.isArray(pkg.licenses) && pkg.licenses.length > 0) {
+            const licenses = pkg.licenses
+                .map((item) => {
+                if (typeof item === "string") {
+                    return item;
+                }
+                if (item && typeof item === "object" && typeof item.type === "string") {
+                    return item.type;
+                }
+                return null;
+            })
+                .filter((item) => Boolean(item));
+            return licenses.length > 0 ? licenses.join(", ") : "UNKNOWN";
+        }
+    }
+    catch {
+        return "UNKNOWN";
+    }
+    return "UNKNOWN";
+}
+function buildHookDiagnostic(plugin, hook, error) {
+    return {
+        spec: plugin,
+        plugin,
+        hook,
+        code: "hook_failed",
+        message: error instanceof Error ? error.message : String(error)
+    };
+}
+function isPlugin(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        typeof value.name === "string");
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { analyzeProject } from "./core/analyzer.js";
 export type { AnalysisOptions, AnalysisFocus, AnalysisResult, DepBrainBaseline, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, Recommendation, RiskFactors, ScoreBreakdown, RiskDependency, TopIssue, TrustScore, UnusedDependency, WorkspaceDependencyUsage, WorkspaceOwnershipSummary } from "./core/analyzer.js";
 export { OUTPUT_VERSION } from "./core/analyzer.js";
+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 type { WorkspacePackage } from "./utils/workspaces.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { analyzeProject } from "./core/analyzer.js";
 export { OUTPUT_VERSION } from "./core/analyzer.js";
+export { PluginManager } from "./core/plugin-manager.js";

package/dist/reporters/dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult } from "../core/analyzer.js";
+export declare function renderDashboardReport(result: AnalysisResult): string;

package/dist/reporters/dashboard.js

@@ -0,0 +1,84 @@
+export function renderDashboardReport(result) {
+    const topIssues = result.topIssues.map(renderTopIssue).join("");
+    const suggestions = result.suggestions.map((item) => `<li>${escapeHtml(item)}</li>`).join("");
+    return [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        "<title>Dependency Brain Dashboard</title>",
+        "<style>",
+        "body{font-family:Arial,sans-serif;margin:0;color:#172033;background:#f6f8fb}",
+        "main{max-width:1120px;margin:0 auto;padding:32px}",
+        "header{display:flex;justify-content:space-between;gap:24px;align-items:flex-start;margin-bottom:24px}",
+        "h1{font-size:28px;margin:0 0 8px}",
+        "h2{font-size:18px;margin:0 0 12px}",
+        ".muted{color:#637083;font-size:13px}",
+        ".score{font-size:48px;font-weight:700}",
+        ".grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px;margin-bottom:20px}",
+        ".panel{background:#fff;border:1px solid #dce3ee;border-radius:8px;padding:16px}",
+        ".metric{font-size:28px;font-weight:700;margin-top:4px}",
+        ".pass{color:#167a43}.fail{color:#b42318}",
+        "ol,ul{margin:0;padding-left:20px}",
+        "li{margin:8px 0}",
+        ".issue{margin-bottom:10px}",
+        ".kind{font-size:12px;text-transform:uppercase;color:#637083}",
+        "@media(max-width:760px){main{padding:20px}.grid{grid-template-columns:repeat(2,minmax(0,1fr))}header{display:block}.score{font-size:40px}}",
+        "</style>",
+        "</head>",
+        "<body>",
+        "<main>",
+        "<header>",
+        "<div>",
+        "<h1>Dependency Brain Dashboard</h1>",
+        `<div class="muted">${escapeHtml(result.rootDir)}</div>`,
+        "</div>",
+        `<div class="${result.policy.passed ? "pass" : "fail"} score">${result.score}/100</div>`,
+        "</header>",
+        '<section class="grid">',
+        renderMetric("Duplicates", result.duplicates.length),
+        renderMetric("Unused", result.unused.length),
+        renderMetric("Outdated", result.outdated.length),
+        renderMetric("Risks", result.risks.length),
+        "</section>",
+        '<section class="panel">',
+        "<h2>Policy</h2>",
+        `<p class="${result.policy.passed ? "pass" : "fail"}">${result.policy.passed ? "Passed" : "Failed"}</p>`,
+        result.policy.reasons.length > 0
+            ? `<ul>${result.policy.reasons.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>`
+            : '<p class="muted">No policy failures.</p>',
+        "</section>",
+        '<section class="panel">',
+        "<h2>Top Issues</h2>",
+        topIssues.length > 0 ? `<ol>${topIssues}</ol>` : '<p class="muted">No actionable issues found.</p>',
+        "</section>",
+        '<section class="panel">',
+        "<h2>Suggestions</h2>",
+        suggestions.length > 0 ? `<ul>${suggestions}</ul>` : '<p class="muted">No suggestions.</p>',
+        "</section>",
+        "</main>",
+        "</body>",
+        "</html>"
+    ].join("\n");
+}
+function renderMetric(label, value) {
+    return `<div class="panel"><div class="muted">${escapeHtml(label)}</div><div class="metric">${value}</div></div>`;
+}
+function renderTopIssue(item) {
+    return [
+        '<li class="issue">',
+        `<div class="kind">${escapeHtml(item.kind)} ${escapeHtml(item.priority)}</div>`,
+        `<strong>${escapeHtml(item.name)}</strong>`,
+        `<div>${escapeHtml(item.recommendation.summary)}</div>`,
+        "</li>"
+    ].join("");
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}

package/dist/utils/config.d.ts

@@ -19,6 +19,26 @@ export interface DepBrainConfig {
     report: {
         maxSuggestions: number;
     };
+    plugins: {
+        enabled: string[];
+        paths: string[];
+    };
+    risk: {
+        transitiveBloatThreshold: number;
+        typosquattingDistanceThreshold: number;
+        staleReleaseDays: number;
+        agingReleaseDays: number;
+        lowDownloadThreshold: number;
+        lowTrustWeightThreshold: number;
+        mediumTrustWeightThreshold: number;
+    };
+    dashboard: {
+        outputPath: string;
+    };
+    notifications: {
+        slackWebhookEnv: string;
+        discordWebhookEnv: string;
+    };
     scoring: {
         duplicateWeight: number;
         outdatedWeight: number;
@@ -33,6 +53,10 @@ export interface DepBrainConfigOverrides {
     ignore?: Partial<DepBrainConfig["ignore"]>;
     policy?: Partial<DepBrainConfig["policy"]>;
     report?: Partial<DepBrainConfig["report"]>;
+    plugins?: Partial<DepBrainConfig["plugins"]>;
+    risk?: Partial<DepBrainConfig["risk"]>;
+    dashboard?: Partial<DepBrainConfig["dashboard"]>;
+    notifications?: Partial<DepBrainConfig["notifications"]>;
     scoring?: Partial<DepBrainConfig["scoring"]>;
     scan?: Partial<DepBrainConfig["scan"]>;
 }

package/dist/utils/config.js

@@ -21,6 +21,26 @@ export const defaultConfig = {
     report: {
         maxSuggestions: 5
     },
+    plugins: {
+        enabled: [],
+        paths: []
+    },
+    risk: {
+        transitiveBloatThreshold: 50,
+        typosquattingDistanceThreshold: 2,
+        staleReleaseDays: 730,
+        agingReleaseDays: 365,
+        lowDownloadThreshold: 1000,
+        lowTrustWeightThreshold: 6,
+        mediumTrustWeightThreshold: 3
+    },
+    dashboard: {
+        outputPath: "depbrain-dashboard.html"
+    },
+    notifications: {
+        slackWebhookEnv: "DEPBRAIN_SLACK_WEBHOOK_URL",
+        discordWebhookEnv: "DEPBRAIN_DISCORD_WEBHOOK_URL"
+    },
     scoring: {
         duplicateWeight: 5,
         outdatedWeight: 3,
@@ -63,6 +83,26 @@ function normalizeConfig(loaded) {
         report: {
             maxSuggestions: normalizeNumber(loaded.report?.maxSuggestions, defaultConfig.report.maxSuggestions)
         },
+        plugins: {
+            enabled: normalizeStringArray(loaded.plugins?.enabled, defaultConfig.plugins.enabled),
+            paths: normalizeStringArray(loaded.plugins?.paths, defaultConfig.plugins.paths)
+        },
+        risk: {
+            transitiveBloatThreshold: normalizeNumber(loaded.risk?.transitiveBloatThreshold, defaultConfig.risk.transitiveBloatThreshold),
+            typosquattingDistanceThreshold: normalizeNumber(loaded.risk?.typosquattingDistanceThreshold, defaultConfig.risk.typosquattingDistanceThreshold),
+            staleReleaseDays: normalizeNumber(loaded.risk?.staleReleaseDays, defaultConfig.risk.staleReleaseDays),
+            agingReleaseDays: normalizeNumber(loaded.risk?.agingReleaseDays, defaultConfig.risk.agingReleaseDays),
+            lowDownloadThreshold: normalizeNumber(loaded.risk?.lowDownloadThreshold, defaultConfig.risk.lowDownloadThreshold),
+            lowTrustWeightThreshold: normalizeNumber(loaded.risk?.lowTrustWeightThreshold, defaultConfig.risk.lowTrustWeightThreshold),
+            mediumTrustWeightThreshold: normalizeNumber(loaded.risk?.mediumTrustWeightThreshold, defaultConfig.risk.mediumTrustWeightThreshold)
+        },
+        dashboard: {
+            outputPath: normalizeString(loaded.dashboard?.outputPath, defaultConfig.dashboard.outputPath)
+        },
+        notifications: {
+            slackWebhookEnv: normalizeString(loaded.notifications?.slackWebhookEnv, defaultConfig.notifications.slackWebhookEnv),
+            discordWebhookEnv: normalizeString(loaded.notifications?.discordWebhookEnv, defaultConfig.notifications.discordWebhookEnv)
+        },
         scoring: {
             duplicateWeight: normalizeNumber(loaded.scoring?.duplicateWeight, defaultConfig.scoring.duplicateWeight),
             outdatedWeight: normalizeNumber(loaded.scoring?.outdatedWeight, defaultConfig.scoring.outdatedWeight),
@@ -86,3 +126,6 @@ function normalizeBoolean(value, fallback) {
 function normalizeNumber(value, fallback) {
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+function normalizeString(value, fallback) {
+    return typeof value === "string" && value.trim().length > 0 ? value : fallback;
+}

package/package.json

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