dep-brain 1.1.0 → 1.2.0

package/README.md

@@ -238,6 +238,21 @@ Create a `depbrain.config.json` file in the project root:
   "report": {
     "maxSuggestions": 3
   },
+  "plugins": {
+    "enabled": [],
+    "paths": []
+  },
+  "risk": {
+    "transitiveBloatThreshold": 50,
+    "typosquattingDistanceThreshold": 2
+  },
+  "dashboard": {
+    "outputPath": "depbrain-dashboard.html"
+  },
+  "notifications": {
+    "slackWebhookEnv": "DEPBRAIN_SLACK_WEBHOOK_URL",
+    "discordWebhookEnv": "DEPBRAIN_DISCORD_WEBHOOK_URL"
+  },
   "scoring": {
     "duplicateWeight": 5,
     "outdatedWeight": 1,
@@ -264,6 +279,13 @@ Supported sections:
 - `policy.failOnOutdated`
 - `policy.failOnRisks`
 - `report.maxSuggestions`
+- `plugins.enabled`
+- `plugins.paths`
+- `risk.transitiveBloatThreshold`
+- `risk.typosquattingDistanceThreshold`
+- `dashboard.outputPath`
+- `notifications.slackWebhookEnv`
+- `notifications.discordWebhookEnv`
 - `scoring.duplicateWeight`
 - `scoring.outdatedWeight`
 - `scoring.unusedWeight`

package/depbrain.config.json

@@ -19,6 +19,21 @@
   "report": {
     "maxSuggestions": 5
   },
+  "plugins": {
+    "enabled": [],
+    "paths": []
+  },
+  "risk": {
+    "transitiveBloatThreshold": 50,
+    "typosquattingDistanceThreshold": 2
+  },
+  "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,37 @@
         "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" }
+      }
+    },
+    "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/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,21 @@ 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
+        },
+        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,
@@ -238,6 +259,7 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
             outdated: baselineFiltered.outdated,
             risks: baselineFiltered.risks
         }),
+        extensions: {},
         config
     };
 }

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

@@ -0,0 +1,20 @@
+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 declare class PluginManager {
+    private readonly plugins;
+    private constructor();
+    static load(rootDir: string, config: DepBrainConfig): Promise<PluginManager>;
+    runPreScan(context: ProjectContext): Promise<void>;
+    runPostScan(result: AnalysisResult): Promise<AnalysisResult>;
+}

package/dist/core/plugin-manager.js

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+export class PluginManager {
+    plugins;
+    constructor(plugins) {
+        this.plugins = plugins;
+    }
+    static async load(rootDir, config) {
+        const specs = [
+            ...config.plugins.enabled.map((name) => `dep-brain-plugin-${name}`),
+            ...config.plugins.paths
+        ];
+        const plugins = [];
+        for (const spec of specs) {
+            const plugin = await loadPlugin(rootDir, spec);
+            if (plugin) {
+                plugins.push(plugin);
+            }
+        }
+        return new PluginManager(plugins);
+    }
+    async runPreScan(context) {
+        for (const plugin of this.plugins) {
+            await plugin.preScan?.(context);
+        }
+    }
+    async runPostScan(result) {
+        let current = result;
+        for (const plugin of this.plugins) {
+            const next = await plugin.postScan?.(current);
+            if (next) {
+                current = next;
+            }
+            const reportSection = await plugin.reportHook?.(current);
+            if (reportSection) {
+                current.extensions[plugin.name] = {
+                    ...(asRecord(current.extensions[plugin.name]) ?? {}),
+                    ...reportSection
+                };
+            }
+        }
+        return current;
+    }
+}
+async function loadPlugin(rootDir, spec) {
+    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;
+        return isPlugin(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+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, 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/utils/config.d.ts

@@ -19,6 +19,21 @@ export interface DepBrainConfig {
     report: {
         maxSuggestions: number;
     };
+    plugins: {
+        enabled: string[];
+        paths: string[];
+    };
+    risk: {
+        transitiveBloatThreshold: number;
+        typosquattingDistanceThreshold: number;
+    };
+    dashboard: {
+        outputPath: string;
+    };
+    notifications: {
+        slackWebhookEnv: string;
+        discordWebhookEnv: string;
+    };
     scoring: {
         duplicateWeight: number;
         outdatedWeight: number;
@@ -33,6 +48,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,21 @@ export const defaultConfig = {
     report: {
         maxSuggestions: 5
     },
+    plugins: {
+        enabled: [],
+        paths: []
+    },
+    risk: {
+        transitiveBloatThreshold: 50,
+        typosquattingDistanceThreshold: 2
+    },
+    dashboard: {
+        outputPath: "depbrain-dashboard.html"
+    },
+    notifications: {
+        slackWebhookEnv: "DEPBRAIN_SLACK_WEBHOOK_URL",
+        discordWebhookEnv: "DEPBRAIN_DISCORD_WEBHOOK_URL"
+    },
     scoring: {
         duplicateWeight: 5,
         outdatedWeight: 3,
@@ -63,6 +78,21 @@ 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)
+        },
+        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 +116,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.2.0",
   "description": "CLI and library for explainable dependency intelligence",
   "type": "module",
   "main": "dist/index.js",