dep-brain 0.2.0 → 0.3.0

package/README.md

@@ -41,6 +41,7 @@ dep-brain analyze
 
 npx dep-brain analyze
 npx dep-brain analyze --json
+npx dep-brain analyze --md
 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
@@ -90,6 +91,16 @@ Suggestions:
 dep-brain analyze --json
 ```
 
+Output includes `outputVersion` for schema stability and can be validated with:
+
+- `depbrain.output.schema.json`
+
+## Markdown Output
+
+```bash
+dep-brain analyze --md
+```
+
 ## Config File
 
 Create a `depbrain.config.json` file in the project root:
@@ -140,6 +151,7 @@ Sample config file:
 
 - `depbrain.config.json`
 - `depbrain.config.schema.json`
+- `depbrain.output.schema.json`
 
 ## CI Behavior
 

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/cli.js

@@ -2,6 +2,7 @@
 import { analyzeProject } from "./core/analyzer.js";
 import { renderConsoleReport } from "./reporters/console.js";
 import { renderJsonReport } from "./reporters/json.js";
+import { renderMarkdownReport } from "./reporters/markdown.js";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 async function main() {
@@ -80,6 +81,9 @@ async function main() {
         if (flags.has("--json")) {
             process.stdout.write(`${renderJsonReport(result)}\n`);
         }
+        else if (flags.has("--md")) {
+            process.stdout.write(`${renderMarkdownReport(result)}\n`);
+        }
         else {
             const output = renderConsoleReport(result);
             if (!output || output.trim().length === 0) {
@@ -144,13 +148,14 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    console.log("  dep-brain analyze [path] [--json] [--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] [--config path] [--min-score n] [--fail-on-risks] [--fail-on-outdated] [--fail-on-unused] [--fail-on-duplicates]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain help");
     console.log("  dep-brain --version");
     console.log("");
     console.log("Options:");
     console.log("  --json              Output JSON for analysis");
+    console.log("  --md                Output Markdown report");
     console.log("  --config <path>     Path to depbrain.config.json");
     console.log("  --min-score <n>     Minimum score required to pass");
     console.log("  --fail-on-risks     Fail when risky dependencies exist");

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);
@@ -55,6 +56,7 @@ export async function analyzeProject(options = {}) {
         risks: risks.length
     }, config);
     return {
+        outputVersion: OUTPUT_VERSION,
         rootDir,
         score,
         scoreBreakdown,
@@ -172,6 +174,7 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
         ? risks.map((item) => ({ ...item, package: options.packageName }))
         : risks;
     return {
+        outputVersion: OUTPUT_VERSION,
         rootDir,
         score,
         scoreBreakdown,

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/reporters/markdown.d.ts

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

package/dist/reporters/markdown.js

@@ -0,0 +1,52 @@
+export function renderMarkdownReport(result) {
+    const lines = [];
+    lines.push(`# Dependency Brain Report`);
+    lines.push("");
+    lines.push(`- **Project Health:** ${result.score}/100`);
+    lines.push(`- **Path:** ${result.rootDir}`);
+    lines.push(`- **Policy:** ${result.policy.passed ? "PASS" : "FAIL"}`);
+    lines.push(`- **Score Breakdown:** base ${result.scoreBreakdown.baseScore} - dup ${result.scoreBreakdown.duplicates} - outdated ${result.scoreBreakdown.outdated} - unused ${result.scoreBreakdown.unused} - risk ${result.scoreBreakdown.risks}`);
+    lines.push("");
+    if (result.packages && result.packages.length > 0) {
+        lines.push("## Packages");
+        for (const pkg of result.packages) {
+            lines.push(`- ${pkg.name}: ${pkg.score}/100 (D:${pkg.duplicates.length} U:${pkg.unused.length} O:${pkg.outdated.length} R:${pkg.risks.length})`);
+        }
+        lines.push("");
+    }
+    lines.push("## Summary");
+    lines.push(`- Duplicates: ${result.duplicates.length}`);
+    lines.push(`- Unused: ${result.unused.length}`);
+    lines.push(`- Outdated: ${result.outdated.length}`);
+    lines.push(`- Risks: ${result.risks.length}`);
+    lines.push("");
+    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => `${item.name}: ${item.versions.join(", ")}`));
+    appendSection(lines, "Unused dependencies", result.unused.map((item) => item.package
+        ? `${item.name} (${item.section}) [${item.package}]`
+        : `${item.name} (${item.section})`));
+    appendSection(lines, "Outdated dependencies", result.outdated.map((item) => item.package
+        ? `${item.name}: ${item.current} -> ${item.latest} [${item.updateType}] [${item.package}]`
+        : `${item.name}: ${item.current} -> ${item.latest} [${item.updateType}]`));
+    appendSection(lines, "Risky dependencies", result.risks.map((item) => item.package
+        ? `${item.name}: ${item.reasons.join("; ")} [${item.package}]`
+        : `${item.name}: ${item.reasons.join("; ")}`));
+    appendSection(lines, "Policy reasons", result.policy.reasons);
+    if (result.suggestions.length > 0) {
+        lines.push("## Suggestions");
+        for (const suggestion of result.suggestions) {
+            lines.push(`- ${suggestion}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function appendSection(lines, title, items) {
+    if (items.length === 0) {
+        return;
+    }
+    lines.push(`## ${title}`);
+    for (const item of items) {
+        lines.push(`- ${item}`);
+    }
+    lines.push("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dep-brain",
-  "version": "0.2.0",
+  "version": "0.3.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",