dep-brain 0.3.0 → 0.5.0

package/README.md

@@ -46,6 +46,9 @@ 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
+npx dep-brain analyze --json --out depbrain.json
+npx dep-brain report --from depbrain.json --md --out depbrain.md
 
 dep-brain config
 dep-brain config --config depbrain.config.json
@@ -101,6 +104,13 @@ Output includes `outputVersion` for schema stability and can be validated with:
 dep-brain analyze --md
 ```
 
+## Report From JSON
+
+```bash
+dep-brain analyze --json --out depbrain.json
+dep-brain report --from depbrain.json --md --out depbrain.md
+```
+
 ## Config File
 
 Create a `depbrain.config.json` file in the project root:
@@ -109,7 +119,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,
@@ -124,6 +136,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"]
   }
 }
 ```
@@ -146,6 +161,9 @@ Supported sections:
 - `scoring.outdatedWeight`
 - `scoring.unusedWeight`
 - `scoring.riskWeight`
+- `ignore.prefixes`
+- `ignore.patterns`
+- `scan.excludePaths`
 
 Sample config file:
 

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/dist/checks/duplicate.d.ts

@@ -1,3 +1,5 @@
 import type { DuplicateDependency } from "../core/analyzer.js";
 import type { DependencyGraph } from "../core/graph-builder.js";
+import type { CheckResult } from "../core/types.js";
 export declare function findDuplicateDependencies(graph: DependencyGraph): Promise<DuplicateDependency[]>;
+export declare function runDuplicateCheck(graph: DependencyGraph): Promise<CheckResult>;

package/dist/checks/duplicate.js

@@ -8,3 +8,20 @@ export async function findDuplicateDependencies(graph) {
         .filter((dependency) => dependency.versions.length > 1)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+export async function runDuplicateCheck(graph) {
+    const duplicates = await findDuplicateDependencies(graph);
+    return {
+        name: "duplicate",
+        summary: `${duplicates.length} duplicate dependencies found`,
+        issues: duplicates.map((item) => ({
+            id: `duplicate:${item.name}`,
+            message: `${item.name} has ${item.versions.length} versions`,
+            severity: "warning",
+            meta: {
+                name: item.name,
+                versions: item.versions,
+                instances: item.instances
+            }
+        }))
+    };
+}

package/dist/checks/outdated.d.ts

@@ -1,6 +1,8 @@
 import type { OutdatedDependency } from "../core/analyzer.js";
 import type { DependencyGraph } from "../core/graph-builder.js";
+import type { CheckResult } from "../core/types.js";
 export interface OutdatedOptions {
     resolveLatestVersion?: (name: string) => Promise<string | null>;
 }
 export declare function findOutdatedDependencies(graph: DependencyGraph, options?: OutdatedOptions): Promise<OutdatedDependency[]>;
+export declare function runOutdatedCheck(graph: DependencyGraph): Promise<CheckResult>;

package/dist/checks/outdated.js

@@ -22,6 +22,24 @@ export async function findOutdatedDependencies(graph, options = {}) {
         .filter((item) => item !== null)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+export async function runOutdatedCheck(graph) {
+    const outdated = await findOutdatedDependencies(graph);
+    return {
+        name: "outdated",
+        summary: `${outdated.length} outdated dependencies found`,
+        issues: outdated.map((item) => ({
+            id: `outdated:${item.name}`,
+            message: `${item.name} ${item.current} -> ${item.latest}`,
+            severity: item.updateType === "major" ? "critical" : "warning",
+            meta: {
+                name: item.name,
+                current: item.current,
+                latest: item.latest,
+                updateType: item.updateType
+            }
+        }))
+    };
+}
 function normalizeVersion(versionRange) {
     return versionRange.trim().replace(/^[~^><=\s]+/, "");
 }

package/dist/checks/risk.d.ts

@@ -1,3 +1,5 @@
 import type { DependencyGraph } from "../core/graph-builder.js";
 import type { RiskDependency } from "../core/analyzer.js";
+import type { CheckResult } from "../core/types.js";
 export declare function findRiskDependencies(graph: DependencyGraph): Promise<RiskDependency[]>;
+export declare function runRiskCheck(graph: DependencyGraph): Promise<CheckResult>;

package/dist/checks/risk.js

@@ -29,3 +29,19 @@ export async function findRiskDependencies(graph) {
         .filter((item) => item !== null)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+export async function runRiskCheck(graph) {
+    const risks = await findRiskDependencies(graph);
+    return {
+        name: "risk",
+        summary: `${risks.length} risky dependencies found`,
+        issues: risks.map((item) => ({
+            id: `risk:${item.name}`,
+            message: `${item.name}: ${item.reasons.join("; ")}`,
+            severity: "warning",
+            meta: {
+                name: item.name,
+                reasons: item.reasons
+            }
+        }))
+    };
+}

package/dist/checks/unused.d.ts

@@ -1,3 +1,10 @@
 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[]>;
+import type { AnalysisContext, CheckResult } from "../core/types.js";
+export declare function findUnusedDependencies(rootDir: string, graph: DependencyGraph, fileEntries: {
+    path: string;
+    content: string;
+}[], options: {
+    hasTypeScriptConfig: boolean;
+}): Promise<UnusedDependency[]>;
+export declare function runUnusedCheck(context: AnalysisContext): Promise<CheckResult>;

package/dist/checks/unused.js

@@ -1,17 +1,20 @@
 import path from "node:path";
-import { collectProjectFiles, readTextFile } from "../utils/file-parser.js";
 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);
-    const projectFiles = files.filter((filePath) => !filePath.includes(`${path.sep}node_modules${path.sep}`));
+export async function findUnusedDependencies(rootDir, graph, fileEntries, options) {
+    const projectFiles = fileEntries
+        .map((entry) => entry.path)
+        .filter((filePath) => !filePath.includes(`${path.sep}node_modules${path.sep}`));
     const runtimeUsed = new Set();
     const devUsed = new Set();
-    for (const filePath of projectFiles) {
-        const content = await readTextFile(filePath);
-        const imports = extractImportedPackages(content);
+    for (const entry of fileEntries) {
+        if (!SOURCE_FILE_PATTERN.test(entry.path)) {
+            continue;
+        }
+        const imports = extractImportedPackages(entry.content);
+        const filePath = entry.path;
         const isDevOnlyFile = isDevelopmentOnlyFile(rootDir, filePath);
         const target = isDevOnlyFile ? devUsed : runtimeUsed;
         for (const importedPackage of imports) {
@@ -25,8 +28,7 @@ export async function findUnusedDependencies(rootDir, graph) {
         devUsed.add(referencedBinary);
     }
     const hasTypeScriptSources = projectFiles.some((filePath) => /\.(c|m)?tsx?$/.test(filePath));
-    const hasTypeScriptConfig = await hasFile(rootDir, "tsconfig.json");
-    if (hasTypeScriptConfig) {
+    if (options.hasTypeScriptConfig) {
         devUsed.add("typescript");
     }
     const unusedDependencies = Object.keys(graph.dependencies)
@@ -34,10 +36,26 @@ export async function findUnusedDependencies(rootDir, graph) {
         .map((name) => ({ name, section: "dependencies" }));
     const unusedDevDependencies = Object.keys(graph.devDependencies)
         .filter((name) => !devUsed.has(name) && !runtimeUsed.has(name))
-        .filter((name) => !isImplicitlyUsedDevDependency(name, hasTypeScriptSources, hasTypeScriptConfig))
+        .filter((name) => !isImplicitlyUsedDevDependency(name, hasTypeScriptSources, options.hasTypeScriptConfig))
         .map((name) => ({ name, section: "devDependencies" }));
     return [...unusedDependencies, ...unusedDevDependencies].sort((left, right) => left.name.localeCompare(right.name));
 }
+export async function runUnusedCheck(context) {
+    const unused = await findUnusedDependencies(context.rootDir, context.graph, context.fileEntries, { hasTypeScriptConfig: context.hasTypeScriptConfig });
+    return {
+        name: "unused",
+        summary: `${unused.length} unused dependencies found`,
+        issues: unused.map((item) => ({
+            id: `unused:${item.section}:${item.name}`,
+            message: `${item.name} appears unused`,
+            severity: "warning",
+            meta: {
+                name: item.name,
+                section: item.section
+            }
+        }))
+    };
+}
 function extractImportedPackages(content) {
     const imports = new Set();
     const patterns = [
@@ -109,12 +127,3 @@ function isImplicitlyUsedDevDependency(name, hasTypeScriptSources, hasTypeScript
     }
     return false;
 }
-async function hasFile(rootDir, fileName) {
-    try {
-        await readTextFile(path.join(rootDir, fileName));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/cli.js

@@ -39,6 +39,30 @@ async function main() {
         return;
     }
     if (command !== "analyze") {
+        if (command === "report") {
+            const fromPath = optionValues.get("--from") ?? positionals[0];
+            if (!fromPath) {
+                console.error("Missing --from <file> for report");
+                printHelp();
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const raw = await fs.readFile(fromPath, "utf8");
+                const reportData = JSON.parse(raw);
+                const output = flags.has("--json")
+                    ? JSON.stringify(reportData, null, 2)
+                    : renderMarkdownReport(reportData);
+                await writeOutput(output, optionValues.get("--out"));
+                return;
+            }
+            catch (error) {
+                console.error("Failed to render report.");
+                console.error(error);
+                process.exitCode = 1;
+                return;
+            }
+        }
         if (command === "config") {
             if (!(await hasPackageJson(targetPath))) {
                 console.error(`No package.json found at ${targetPath}`);
@@ -78,21 +102,21 @@ async function main() {
             configPath: optionValues.get("--config"),
             config: cliConfig
         });
+        let output;
         if (flags.has("--json")) {
-            process.stdout.write(`${renderJsonReport(result)}\n`);
+            output = renderJsonReport(result);
         }
         else if (flags.has("--md")) {
-            process.stdout.write(`${renderMarkdownReport(result)}\n`);
+            output = renderMarkdownReport(result);
         }
         else {
-            const output = renderConsoleReport(result);
-            if (!output || output.trim().length === 0) {
-                process.stdout.write(`${renderJsonReport(result)}\n`);
-            }
-            else {
-                process.stdout.write(`${output}\n`);
-            }
+            const consoleOutput = renderConsoleReport(result);
+            output =
+                !consoleOutput || consoleOutput.trim().length === 0
+                    ? renderJsonReport(result)
+                    : consoleOutput;
         }
+        await writeOutput(output, optionValues.get("--out"));
         if (!result.policy.passed) {
             process.exitCode = 1;
         }
@@ -148,7 +172,8 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    console.log("  dep-brain analyze [path] [--json] [--md] [--config path] [--min-score n] [--fail-on-risks] [--fail-on-outdated] [--fail-on-unused] [--fail-on-duplicates]");
+    console.log("  dep-brain analyze [path] [--json] [--md] [--out path] [--config path] [--min-score n] [--fail-on-risks] [--fail-on-outdated] [--fail-on-unused] [--fail-on-duplicates]");
+    console.log("  dep-brain report --from <file> [--md] [--json] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain help");
     console.log("  dep-brain --version");
@@ -157,6 +182,8 @@ function printHelp() {
     console.log("  --json              Output JSON for analysis");
     console.log("  --md                Output Markdown report");
     console.log("  --config <path>     Path to depbrain.config.json");
+    console.log("  --from <file>       Read analysis JSON from file");
+    console.log("  --out <path>        Write output to a file");
     console.log("  --min-score <n>     Minimum score required to pass");
     console.log("  --fail-on-risks     Fail when risky dependencies exist");
     console.log("  --fail-on-outdated  Fail when outdated dependencies exist");
@@ -176,3 +203,10 @@ async function loadPackageVersion() {
         return null;
     }
 }
+async function writeOutput(output, outPath) {
+    if (outPath) {
+        await fs.writeFile(outPath, `${output}\n`, "utf8");
+        return;
+    }
+    process.stdout.write(`${output}\n`);
+}

package/dist/core/analyzer.js

@@ -1,12 +1,13 @@
 import path from "node:path";
-import { findDuplicateDependencies } from "../checks/duplicate.js";
-import { findOutdatedDependencies } from "../checks/outdated.js";
-import { findRiskDependencies } from "../checks/risk.js";
-import { findUnusedDependencies } from "../checks/unused.js";
+import { runDuplicateCheck } from "../checks/duplicate.js";
+import { runOutdatedCheck } from "../checks/outdated.js";
+import { runRiskCheck } from "../checks/risk.js";
+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 { calculateHealthScore } from "./scorer.js";
+import { buildAnalysisContext } from "./context.js";
 export const OUTPUT_VERSION = "1.0";
 export async function analyzeProject(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
@@ -17,8 +18,9 @@ export async function analyzeProject(options = {}) {
         return analyzeSingleProject(rootDir, config);
     }
     const rootGraph = await buildDependencyGraph(rootDir);
-    const rawDuplicates = await findDuplicateDependencies(rootGraph);
-    const duplicates = rawDuplicates.filter((item) => !config.ignore.duplicates.includes(item.name));
+    const duplicateCheck = await runDuplicateCheck(rootGraph);
+    const filteredDuplicateIssues = filterIssues(duplicateCheck.issues, "duplicates", config);
+    const duplicates = mapDuplicateIssues(filteredDuplicateIssues);
     const packages = [];
     for (const workspace of workspaces) {
         const result = await analyzeSingleProject(workspace.rootDir, config, {
@@ -81,7 +83,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,
@@ -98,6 +102,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
         }
     };
 }
@@ -124,18 +131,13 @@ function evaluatePolicy(summary, config) {
     };
 }
 async function analyzeSingleProject(rootDir, config, options = {}) {
-    const graph = await buildDependencyGraph(rootDir);
-    const [rawDuplicates, rawUnused, rawOutdated, rawRisks] = await Promise.all([
-        findDuplicateDependencies(graph),
-        findUnusedDependencies(rootDir, graph),
-        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 context = await buildAnalysisContext(rootDir, config);
+    const results = await runChecks(context);
+    const issueGroups = normalizeIssues(results, config);
+    const duplicates = mapDuplicateIssues(issueGroups.duplicates);
+    const unused = mapUnusedIssues(issueGroups.unused);
+    const outdated = mapOutdatedIssues(issueGroups.outdated);
+    const risks = mapRiskIssues(issueGroups.risks);
     const score = calculateHealthScore({
         duplicates: duplicates.length,
         unused: unused.length,
@@ -187,6 +189,106 @@ 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;
+        }
+    });
+}
+async function runChecks(context) {
+    const checks = [
+        {
+            name: "duplicate",
+            run: () => runDuplicateCheck(context.graph)
+        },
+        {
+            name: "unused",
+            run: () => runUnusedCheck(context)
+        },
+        {
+            name: "outdated",
+            run: () => runOutdatedCheck(context.graph)
+        },
+        {
+            name: "risk",
+            run: () => runRiskCheck(context.graph)
+        }
+    ];
+    const results = [];
+    for (const check of checks) {
+        results.push(await check.run());
+    }
+    return results;
+}
+function normalizeIssues(results, config) {
+    const map = new Map();
+    for (const result of results) {
+        map.set(result.name, result.issues);
+    }
+    return {
+        duplicates: filterIssues(map.get("duplicate") ?? [], "duplicates", config),
+        unused: filterIssues(map.get("unused") ?? [], "unused", config),
+        outdated: filterIssues(map.get("outdated") ?? [], "outdated", config),
+        risks: filterIssues(map.get("risk") ?? [], "risks", config)
+    };
+}
+function filterIssues(issues, bucket, config) {
+    return issues.filter((issue) => {
+        const name = typeof issue.meta?.name === "string" ? issue.meta.name : issue.package ?? "";
+        if (!name) {
+            return true;
+        }
+        if (bucket === "unused") {
+            const section = issue.meta?.section === "devDependencies" ? "devDependencies" : "dependencies";
+            if (shouldIgnorePackage(name, section, config)) {
+                return false;
+            }
+        }
+        return !shouldIgnorePackage(name, bucket, config);
+    });
+}
+function mapDuplicateIssues(issues) {
+    return issues.map((issue) => ({
+        name: String(issue.meta?.name ?? issue.package ?? "unknown"),
+        versions: Array.isArray(issue.meta?.versions) ? issue.meta?.versions : [],
+        instances: Array.isArray(issue.meta?.instances)
+            ? issue.meta?.instances
+            : []
+    }));
+}
+function mapUnusedIssues(issues) {
+    return issues.map((issue) => ({
+        name: String(issue.meta?.name ?? issue.package ?? "unknown"),
+        section: issue.meta?.section === "devDependencies" ? "devDependencies" : "dependencies"
+    }));
+}
+function mapOutdatedIssues(issues) {
+    return issues.map((issue) => ({
+        name: String(issue.meta?.name ?? issue.package ?? "unknown"),
+        current: String(issue.meta?.current ?? ""),
+        latest: String(issue.meta?.latest ?? ""),
+        updateType: issue.meta?.updateType === "major" || issue.meta?.updateType === "minor" || issue.meta?.updateType === "patch"
+            ? issue.meta.updateType
+            : "unknown"
+    }));
+}
+function mapRiskIssues(issues) {
+    return issues.map((issue) => ({
+        name: String(issue.meta?.name ?? issue.package ?? "unknown"),
+        reasons: Array.isArray(issue.meta?.reasons) ? issue.meta?.reasons : []
+    }));
+}
 function buildScoreBreakdown(counts, config) {
     return {
         baseScore: 100,

package/dist/core/context.d.ts

@@ -0,0 +1,3 @@
+import type { AnalysisContext } from "./types.js";
+import type { DepBrainConfig } from "../utils/config.js";
+export declare function buildAnalysisContext(rootDir: string, config: DepBrainConfig): Promise<AnalysisContext>;

package/dist/core/context.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { buildDependencyGraph } from "./graph-builder.js";
+import { collectProjectFiles, readTextFile } from "../utils/file-parser.js";
+const SOURCE_FILE_PATTERN = /\.(c|m)?(t|j)sx?$/;
+export async function buildAnalysisContext(rootDir, config) {
+    const graph = await buildDependencyGraph(rootDir);
+    const projectFiles = await collectProjectFiles(rootDir, SOURCE_FILE_PATTERN, config.scan.excludePaths);
+    const fileEntries = await Promise.all(projectFiles.map(async (filePath) => ({
+        path: filePath,
+        content: await readTextFile(filePath)
+    })));
+    const sourceText = fileEntries.map((entry) => entry.content).join("\n");
+    const hasTypeScriptConfig = await hasFile(rootDir, "tsconfig.json");
+    return {
+        rootDir,
+        graph,
+        sourceText,
+        projectFiles,
+        fileEntries,
+        hasTypeScriptConfig
+    };
+}
+async function hasFile(rootDir, fileName) {
+    try {
+        await readTextFile(path.join(rootDir, fileName));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,28 @@
+export type IssueSeverity = "info" | "warning" | "critical";
+export type Issue = {
+    id: string;
+    message: string;
+    package?: string;
+    severity: IssueSeverity;
+    meta?: Record<string, unknown>;
+};
+export type CheckResult = {
+    name: string;
+    issues: Issue[];
+    summary: string;
+};
+export type AnalysisContext = {
+    rootDir: string;
+    graph: import("./graph-builder.js").DependencyGraph;
+    sourceText: string;
+    projectFiles: string[];
+    fileEntries: {
+        path: string;
+        content: string;
+    }[];
+    hasTypeScriptConfig: boolean;
+};
+export type CheckRunner = {
+    name: string;
+    run: (context: AnalysisContext) => Promise<CheckResult>;
+};

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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 { AnalysisContext, CheckResult, Issue } from "./core/types.js";
 export type { DepBrainConfig, DepBrainConfigOverrides } from "./utils/config.js";
 export type { WorkspacePackage } from "./utils/workspaces.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.3.0",
+  "version": "0.5.0",
   "description": "CLI and library for dependency health analysis",
   "type": "module",
   "main": "dist/index.js",