dep-brain 0.4.0 → 0.5.0

package/README.md

@@ -46,7 +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 --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
@@ -102,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:

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,5 +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, options?: {
-    excludePaths?: string[];
+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, options = {}) {
-    const files = await collectProjectFiles(rootDir, SOURCE_FILE_PATTERN, options.excludePaths ?? []);
-    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, options = {}) {
         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, options = {}) {
         .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) => !shouldIgnorePackage(item.name, "duplicates", config));
+    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, {
@@ -129,20 +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, {
-            excludePaths: config.scan.excludePaths
-        }),
-        findOutdatedDependencies(graph),
-        findRiskDependencies(graph)
-    ]);
-    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 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,
@@ -211,6 +206,89 @@ function shouldIgnorePackage(name, bucket, config) {
         }
     });
 }
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dep-brain",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI and library for dependency health analysis",
   "type": "module",
   "main": "dist/index.js",