dep-brain 0.2.1 → 0.4.0

package/README.md

@@ -46,6 +46,7 @@ npx dep-brain analyze ./path-to-project
 npx dep-brain analyze --config depbrain.config.json
 npx dep-brain analyze --min-score 90 --fail-on-risks
 npx dep-brain analyze ./path-to-project --fail-on-unused --json
+ npx dep-brain analyze --md > depbrain.md
 
 dep-brain config
 dep-brain config --config depbrain.config.json
@@ -91,6 +92,10 @@ Suggestions:
 dep-brain analyze --json
 ```
 
+Output includes `outputVersion` for schema stability and can be validated with:
+
+- `depbrain.output.schema.json`
+
 ## Markdown Output
 
 ```bash
@@ -105,7 +110,9 @@ Create a `depbrain.config.json` file in the project root:
 {
   "ignore": {
     "unused": ["eslint"],
-    "outdated": ["typescript"]
+    "outdated": ["typescript"],
+    "prefixes": ["@nestjs/"],
+    "patterns": ["^@aws-sdk/"]
   },
   "policy": {
     "minScore": 90,
@@ -120,6 +127,9 @@ Create a `depbrain.config.json` file in the project root:
     "outdatedWeight": 1,
     "unusedWeight": 2,
     "riskWeight": 6
+  },
+  "scan": {
+    "excludePaths": ["node_modules", "dist", "build", "coverage", ".git"]
   }
 }
 ```
@@ -142,11 +152,15 @@ Supported sections:
 - `scoring.outdatedWeight`
 - `scoring.unusedWeight`
 - `scoring.riskWeight`
+- `ignore.prefixes`
+- `ignore.patterns`
+- `scan.excludePaths`
 
 Sample config file:
 
 - `depbrain.config.json`
 - `depbrain.config.schema.json`
+- `depbrain.output.schema.json`
 
 ## CI Behavior
 

package/depbrain.config.json

@@ -5,7 +5,9 @@
     "duplicates": [],
     "risks": [],
     "dependencies": [],
-    "devDependencies": []
+    "devDependencies": [],
+    "prefixes": [],
+    "patterns": []
   },
   "policy": {
     "minScore": 85,
@@ -22,5 +24,8 @@
     "outdatedWeight": 3,
     "unusedWeight": 4,
     "riskWeight": 10
+  },
+  "scan": {
+    "excludePaths": ["node_modules", "dist", "build", "coverage", ".git"]
   }
 }

package/depbrain.config.schema.json

@@ -13,7 +13,9 @@
         "unused": { "type": "array", "items": { "type": "string" } },
         "duplicates": { "type": "array", "items": { "type": "string" } },
         "outdated": { "type": "array", "items": { "type": "string" } },
-        "risks": { "type": "array", "items": { "type": "string" } }
+        "risks": { "type": "array", "items": { "type": "string" } },
+        "prefixes": { "type": "array", "items": { "type": "string" } },
+        "patterns": { "type": "array", "items": { "type": "string" } }
       }
     },
     "policy": {
@@ -43,6 +45,13 @@
         "unusedWeight": { "type": "number" },
         "riskWeight": { "type": "number" }
       }
+    },
+    "scan": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "excludePaths": { "type": "array", "items": { "type": "string" } }
+      }
     }
   }
 }

package/depbrain.output.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Dependency Brain Analysis Output",
+  "type": "object",
+  "required": ["outputVersion", "rootDir", "score", "scoreBreakdown", "policy", "duplicates", "unused", "outdated", "risks", "suggestions", "config"],
+  "additionalProperties": false,
+  "properties": {
+    "outputVersion": { "type": "string" },
+    "rootDir": { "type": "string" },
+    "score": { "type": "number" },
+    "scoreBreakdown": {
+      "type": "object",
+      "required": ["baseScore", "duplicates", "outdated", "unused", "risks", "weights"],
+      "additionalProperties": false,
+      "properties": {
+        "baseScore": { "type": "number" },
+        "duplicates": { "type": "number" },
+        "outdated": { "type": "number" },
+        "unused": { "type": "number" },
+        "risks": { "type": "number" },
+        "weights": {
+          "type": "object",
+          "required": ["duplicateWeight", "outdatedWeight", "unusedWeight", "riskWeight"],
+          "additionalProperties": false,
+          "properties": {
+            "duplicateWeight": { "type": "number" },
+            "outdatedWeight": { "type": "number" },
+            "unusedWeight": { "type": "number" },
+            "riskWeight": { "type": "number" }
+          }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "required": ["passed", "reasons"],
+      "additionalProperties": false,
+      "properties": {
+        "passed": { "type": "boolean" },
+        "reasons": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "duplicates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "versions", "instances"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "versions": { "type": "array", "items": { "type": "string" } },
+          "instances": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["path", "version"],
+              "additionalProperties": false,
+              "properties": {
+                "path": { "type": "string" },
+                "version": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "unused": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "section"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "section": { "type": "string", "enum": ["dependencies", "devDependencies"] },
+          "package": { "type": "string" }
+        }
+      }
+    },
+    "outdated": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "current", "latest", "updateType"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "current": { "type": "string" },
+          "latest": { "type": "string" },
+          "updateType": { "type": "string" },
+          "package": { "type": "string" }
+        }
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "reasons"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "reasons": { "type": "array", "items": { "type": "string" } },
+          "package": { "type": "string" }
+        }
+      }
+    },
+    "suggestions": { "type": "array", "items": { "type": "string" } },
+    "config": { "type": "object" },
+    "packages": { "type": "array" }
+  }
+}

package/dist/checks/unused.d.ts

@@ -1,3 +1,5 @@
 import type { UnusedDependency } from "../core/analyzer.js";
 import type { DependencyGraph } from "../core/graph-builder.js";
-export declare function findUnusedDependencies(rootDir: string, graph: DependencyGraph): Promise<UnusedDependency[]>;
+export declare function findUnusedDependencies(rootDir: string, graph: DependencyGraph, options?: {
+    excludePaths?: string[];
+}): Promise<UnusedDependency[]>;

package/dist/checks/unused.js

@@ -4,8 +4,8 @@ const SOURCE_FILE_PATTERN = /\.(c|m)?(t|j)sx?$/;
 const CONFIG_FILE_PATTERN = /(^|[\\/])(vite|vitest|jest|eslint|prettier|rollup|webpack|babel|tsup|eslint\.config|commitlint|playwright|storybook|tailwind|postcss)\.config\.(c|m)?(t|j)s$/;
 const TEST_FILE_PATTERN = /(^|[\\/])(__tests__|test|tests|spec|specs)([\\/]|$)|\.(test|spec)\.(c|m)?(t|j)sx?$/;
 const RUNTIME_DIR_PATTERN = /(^|[\\/])(src|app|lib|server|client|pages|components)([\\/]|$)/;
-export async function findUnusedDependencies(rootDir, graph) {
-    const files = await collectProjectFiles(rootDir, SOURCE_FILE_PATTERN);
+export async function findUnusedDependencies(rootDir, graph, options = {}) {
+    const files = await collectProjectFiles(rootDir, SOURCE_FILE_PATTERN, options.excludePaths ?? []);
     const projectFiles = files.filter((filePath) => !filePath.includes(`${path.sep}node_modules${path.sep}`));
     const runtimeUsed = new Set();
     const devUsed = new Set();

package/dist/core/analyzer.d.ts

@@ -31,6 +31,7 @@ export interface RiskDependency {
     package?: string;
 }
 export interface AnalysisResult {
+    outputVersion: string;
     rootDir: string;
     score: number;
     scoreBreakdown: ScoreBreakdown;
@@ -59,6 +60,7 @@ export interface PackageAnalysisResult {
     risks: RiskDependency[];
     suggestions: string[];
 }
+export declare const OUTPUT_VERSION = "1.0";
 export interface ScoreBreakdown {
     baseScore: number;
     duplicates: number;

package/dist/core/analyzer.js

@@ -7,6 +7,7 @@ import { loadDepBrainConfig } from "../utils/config.js";
 import { findWorkspacePackages } from "../utils/workspaces.js";
 import { buildDependencyGraph } from "./graph-builder.js";
 import { calculateHealthScore } from "./scorer.js";
+export const OUTPUT_VERSION = "1.0";
 export async function analyzeProject(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
     const loadedConfig = await loadDepBrainConfig(rootDir, options.configPath);
@@ -17,7 +18,7 @@ export async function analyzeProject(options = {}) {
     }
     const rootGraph = await buildDependencyGraph(rootDir);
     const rawDuplicates = await findDuplicateDependencies(rootGraph);
-    const duplicates = rawDuplicates.filter((item) => !config.ignore.duplicates.includes(item.name));
+    const duplicates = rawDuplicates.filter((item) => !shouldIgnorePackage(item.name, "duplicates", config));
     const packages = [];
     for (const workspace of workspaces) {
         const result = await analyzeSingleProject(workspace.rootDir, config, {
@@ -55,6 +56,7 @@ export async function analyzeProject(options = {}) {
         risks: risks.length
     }, config);
     return {
+        outputVersion: OUTPUT_VERSION,
         rootDir,
         score,
         scoreBreakdown,
@@ -79,7 +81,9 @@ function mergeConfig(base, overrides) {
             duplicates: overrides.ignore?.duplicates ?? base.ignore.duplicates,
             outdated: overrides.ignore?.outdated ?? base.ignore.outdated,
             risks: overrides.ignore?.risks ?? base.ignore.risks,
-            unused: overrides.ignore?.unused ?? base.ignore.unused
+            unused: overrides.ignore?.unused ?? base.ignore.unused,
+            prefixes: overrides.ignore?.prefixes ?? base.ignore.prefixes,
+            patterns: overrides.ignore?.patterns ?? base.ignore.patterns
         },
         policy: {
             minScore: overrides.policy?.minScore ?? base.policy.minScore,
@@ -96,6 +100,9 @@ function mergeConfig(base, overrides) {
             outdatedWeight: overrides.scoring?.outdatedWeight ?? base.scoring.outdatedWeight,
             unusedWeight: overrides.scoring?.unusedWeight ?? base.scoring.unusedWeight,
             riskWeight: overrides.scoring?.riskWeight ?? base.scoring.riskWeight
+        },
+        scan: {
+            excludePaths: overrides.scan?.excludePaths ?? base.scan.excludePaths
         }
     };
 }
@@ -125,15 +132,17 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
     const graph = await buildDependencyGraph(rootDir);
     const [rawDuplicates, rawUnused, rawOutdated, rawRisks] = await Promise.all([
         findDuplicateDependencies(graph),
-        findUnusedDependencies(rootDir, graph),
+        findUnusedDependencies(rootDir, graph, {
+            excludePaths: config.scan.excludePaths
+        }),
         findOutdatedDependencies(graph),
         findRiskDependencies(graph)
     ]);
-    const duplicates = rawDuplicates.filter((item) => !config.ignore.duplicates.includes(item.name));
-    const unused = rawUnused.filter((item) => !config.ignore.unused.includes(item.name) &&
-        !config.ignore[item.section].includes(item.name));
-    const outdated = rawOutdated.filter((item) => !config.ignore.outdated.includes(item.name));
-    const risks = rawRisks.filter((item) => !config.ignore.risks.includes(item.name));
+    const duplicates = rawDuplicates.filter((item) => !shouldIgnorePackage(item.name, "duplicates", config));
+    const unused = rawUnused.filter((item) => !shouldIgnorePackage(item.name, "unused", config) &&
+        !shouldIgnorePackage(item.name, item.section, config));
+    const outdated = rawOutdated.filter((item) => !shouldIgnorePackage(item.name, "outdated", config));
+    const risks = rawRisks.filter((item) => !shouldIgnorePackage(item.name, "risks", config));
     const score = calculateHealthScore({
         duplicates: duplicates.length,
         unused: unused.length,
@@ -172,6 +181,7 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
         ? risks.map((item) => ({ ...item, package: options.packageName }))
         : risks;
     return {
+        outputVersion: OUTPUT_VERSION,
         rootDir,
         score,
         scoreBreakdown,
@@ -184,6 +194,23 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
         config
     };
 }
+function shouldIgnorePackage(name, bucket, config) {
+    if (config.ignore[bucket].includes(name)) {
+        return true;
+    }
+    if (config.ignore.prefixes.some((prefix) => name.startsWith(prefix))) {
+        return true;
+    }
+    return config.ignore.patterns.some((pattern) => {
+        try {
+            const regex = new RegExp(pattern);
+            return regex.test(name);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 function buildScoreBreakdown(counts, config) {
     return {
         baseScore: 100,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { analyzeProject } from "./core/analyzer.js";
 export type { AnalysisOptions, AnalysisResult, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, ScoreBreakdown, RiskDependency, UnusedDependency } from "./core/analyzer.js";
+export { OUTPUT_VERSION } from "./core/analyzer.js";
 export type { DepBrainConfig, DepBrainConfigOverrides } from "./utils/config.js";
 export type { WorkspacePackage } from "./utils/workspaces.js";

package/dist/index.js

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

package/dist/utils/config.d.ts

@@ -6,6 +6,8 @@ export interface DepBrainConfig {
         outdated: string[];
         risks: string[];
         unused: string[];
+        prefixes: string[];
+        patterns: string[];
     };
     policy: {
         minScore: number;
@@ -23,12 +25,16 @@ export interface DepBrainConfig {
         unusedWeight: number;
         riskWeight: number;
     };
+    scan: {
+        excludePaths: string[];
+    };
 }
 export interface DepBrainConfigOverrides {
     ignore?: Partial<DepBrainConfig["ignore"]>;
     policy?: Partial<DepBrainConfig["policy"]>;
     report?: Partial<DepBrainConfig["report"]>;
     scoring?: Partial<DepBrainConfig["scoring"]>;
+    scan?: Partial<DepBrainConfig["scan"]>;
 }
 export declare const defaultConfig: DepBrainConfig;
 export declare function loadDepBrainConfig(rootDir: string, configPath?: string): Promise<DepBrainConfig>;

package/dist/utils/config.js

@@ -7,7 +7,9 @@ export const defaultConfig = {
         duplicates: [],
         outdated: [],
         risks: [],
-        unused: []
+        unused: [],
+        prefixes: [],
+        patterns: []
     },
     policy: {
         minScore: 0,
@@ -24,6 +26,9 @@ export const defaultConfig = {
         outdatedWeight: 3,
         unusedWeight: 4,
         riskWeight: 10
+    },
+    scan: {
+        excludePaths: ["node_modules", "dist", "build", "coverage", ".git"]
     }
 };
 export async function loadDepBrainConfig(rootDir, configPath) {
@@ -44,7 +49,9 @@ function normalizeConfig(loaded) {
             duplicates: normalizeStringArray(loaded.ignore?.duplicates, defaultConfig.ignore.duplicates),
             outdated: normalizeStringArray(loaded.ignore?.outdated, defaultConfig.ignore.outdated),
             risks: normalizeStringArray(loaded.ignore?.risks, defaultConfig.ignore.risks),
-            unused: normalizeStringArray(loaded.ignore?.unused, defaultConfig.ignore.unused)
+            unused: normalizeStringArray(loaded.ignore?.unused, defaultConfig.ignore.unused),
+            prefixes: normalizeStringArray(loaded.ignore?.prefixes, defaultConfig.ignore.prefixes),
+            patterns: normalizeStringArray(loaded.ignore?.patterns, defaultConfig.ignore.patterns)
         },
         policy: {
             minScore: normalizeNumber(loaded.policy?.minScore, defaultConfig.policy.minScore),
@@ -61,6 +68,9 @@ function normalizeConfig(loaded) {
             outdatedWeight: normalizeNumber(loaded.scoring?.outdatedWeight, defaultConfig.scoring.outdatedWeight),
             unusedWeight: normalizeNumber(loaded.scoring?.unusedWeight, defaultConfig.scoring.unusedWeight),
             riskWeight: normalizeNumber(loaded.scoring?.riskWeight, defaultConfig.scoring.riskWeight)
+        },
+        scan: {
+            excludePaths: normalizeStringArray(loaded.scan?.excludePaths, defaultConfig.scan.excludePaths)
         }
     };
 }

package/dist/utils/file-parser.d.ts

@@ -1,3 +1,3 @@
 export declare function readJsonFile<T>(filePath: string): Promise<T>;
 export declare function readTextFile(filePath: string): Promise<string>;
-export declare function collectProjectFiles(rootDir: string, pattern: RegExp): Promise<string[]>;
+export declare function collectProjectFiles(rootDir: string, pattern: RegExp, excludePaths?: string[]): Promise<string[]>;

package/dist/utils/file-parser.js

@@ -7,16 +7,23 @@ export async function readJsonFile(filePath) {
 export async function readTextFile(filePath) {
     return fs.readFile(filePath, "utf8");
 }
-export async function collectProjectFiles(rootDir, pattern) {
-    const entries = await fs.readdir(rootDir, { withFileTypes: true });
+export async function collectProjectFiles(rootDir, pattern, excludePaths = []) {
+    return collectProjectFilesInternal(rootDir, rootDir, pattern, excludePaths);
+}
+async function collectProjectFilesInternal(currentDir, baseDir, pattern, excludePaths) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
-        const fullPath = path.join(rootDir, entry.name);
+        const fullPath = path.join(currentDir, entry.name);
+        const relPath = path.relative(baseDir, fullPath);
+        if (matchesAnyPattern(relPath, excludePaths)) {
+            continue;
+        }
         if (entry.isDirectory()) {
             if (entry.name === ".git") {
                 continue;
             }
-            files.push(...(await collectProjectFiles(fullPath, pattern)));
+            files.push(...(await collectProjectFilesInternal(fullPath, baseDir, pattern, excludePaths)));
             continue;
         }
         if (pattern.test(entry.name)) {
@@ -25,3 +32,26 @@ export async function collectProjectFiles(rootDir, pattern) {
     }
     return files;
 }
+function matchesAnyPattern(value, patterns) {
+    if (patterns.length === 0) {
+        return false;
+    }
+    const normalized = normalizePath(value);
+    return patterns.some((pattern) => {
+        const regex = globToRegExp(pattern);
+        return regex.test(normalized);
+    });
+}
+function globToRegExp(pattern) {
+    const normalized = normalizePath(pattern)
+        .replace(/\/+$/, "")
+        .replace(/^\//, "")
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "___DEPBRAIN_GLOBSTAR___")
+        .replace(/\*/g, "[^/]*")
+        .replace(/___DEPBRAIN_GLOBSTAR___/g, ".*");
+    return new RegExp(`(^|.*/)${normalized}($|/.*)`);
+}
+function normalizePath(value) {
+    return value.split(path.sep).join("/");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dep-brain",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "CLI and library for dependency health analysis",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
     "LICENSE",
     "CHANGELOG.md",
     "depbrain.config.json",
-    "depbrain.config.schema.json"
+    "depbrain.config.schema.json",
+    "depbrain.output.schema.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",