dep-brain 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -7,3 +7,5 @@ All notable changes to this project will be documented in this file.
 - Workspace-aware analysis for npm workspaces.
 - Config loading and CI policy controls.
 - Improved duplicate detection and unused dependency heuristics.
+- Actionable recommendations for unused, duplicate, outdated, and risk findings.
+- Ranked top-issues summary output with `--top`.

package/README.md

@@ -4,11 +4,16 @@
 [![npm downloads](https://img.shields.io/npm/dm/dep-brain)](https://www.npmjs.com/package/dep-brain)
 [![license](https://img.shields.io/npm/l/dep-brain)](LICENSE)
 
-`dep-brain` is a CLI and library for analyzing dependency health in JavaScript and TypeScript projects.
+`dep-brain` is a CLI and library for explainable dependency intelligence in JavaScript and TypeScript projects.
 
 ## Vision
 
-`npm audit + depcheck + dedupe + intelligence = one tool`
+`dep-brain` aims to become a dependency decision engine:
+
+- Explain why a dependency matters
+- Evaluate how safe, risky, or necessary it is
+- Recommend what to do next
+- Enforce decisions in CI workflows
 
 ## What It Does
 
@@ -19,6 +24,12 @@
 - Generate a simple project health score
 - Output reports in human-readable or JSON format
 
+The long-term goal is not just to list problems, but to answer:
+
+- Why is this dependency here?
+- Can I remove it safely?
+- What should I fix first?
+
 ## Current MVP Features
 
 - Duplicate dependency detection with lockfile instance tracking
@@ -42,6 +53,7 @@ dep-brain analyze
 npx dep-brain analyze
 npx dep-brain analyze --json
 npx dep-brain analyze --md
+npx dep-brain analyze --top
 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
@@ -104,6 +116,14 @@ Output includes `outputVersion` for schema stability and can be validated with:
 dep-brain analyze --md
 ```
 
+## Top Issues Output
+
+```bash
+dep-brain analyze --top
+```
+
+Shows the highest-priority actionable findings first, including confidence and next-step guidance.
+
 ## Report From JSON
 
 ```bash
@@ -225,14 +245,20 @@ src/
     `-- config.ts
 ```
 
-## Roadmap Direction
+## Product Direction
+
+`dep-brain` is currently in the `v0.5.x` foundation stage. The next roadmap is:
+
+- `v0.6`: explainability and confidence scoring
+- `v0.7`: safe removal guidance and actionable recommendations
+- `v0.8`: supply-chain trust and risk intelligence
+- `v0.9`: deeper monorepo and ownership intelligence
+- `v1.0`: stable CI, ecosystem exports, and production readiness
 
-- Improve false-positive reduction for unused dependency detection
-- Improve monorepo and workspace support
-- Strengthen risk scoring and suggestions
-- Add CI and GitHub Action support in later releases
+The project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
 
 ## Repository Notes
 
 - Project brief: [docs/project-brief.md](./docs/project-brief.md)
+- Product roadmap: [docs/product-roadmap.md](./docs/product-roadmap.md)
 - Implementation history: [docs/implementation-log.md](./docs/implementation-log.md)

package/depbrain.output.schema.json

@@ -2,9 +2,21 @@
   "$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"],
+  "required": ["outputVersion", "rootDir", "score", "scoreBreakdown", "policy", "duplicates", "unused", "outdated", "risks", "suggestions", "topIssues", "config"],
   "additionalProperties": false,
   "properties": {
+    "recommendation": {
+      "type": "object",
+      "required": ["action", "priority", "safety", "summary", "reasons"],
+      "additionalProperties": false,
+      "properties": {
+        "action": { "type": "string", "enum": ["remove", "consolidate", "upgrade", "review"] },
+        "priority": { "type": "string", "enum": ["high", "medium", "low"] },
+        "safety": { "type": "string", "enum": ["safe", "caution", "unknown"] },
+        "summary": { "type": "string" },
+        "reasons": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "outputVersion": { "type": "string" },
     "rootDir": { "type": "string" },
     "score": { "type": "number" },
@@ -44,11 +56,15 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "versions", "instances"],
+        "required": ["name", "versions", "instances", "confidence", "reasonCodes", "explanation", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "versions": { "type": "array", "items": { "type": "string" } },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "reasonCodes": { "type": "array", "items": { "type": "string" } },
+          "explanation": { "type": "array", "items": { "type": "string" } },
+          "recommendation": { "$ref": "#/properties/recommendation" },
           "instances": {
             "type": "array",
             "items": {
@@ -68,12 +84,16 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "section"],
+        "required": ["name", "section", "confidence", "reasonCodes", "explanation", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "section": { "type": "string", "enum": ["dependencies", "devDependencies"] },
-          "package": { "type": "string" }
+          "package": { "type": "string" },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "reasonCodes": { "type": "array", "items": { "type": "string" } },
+          "explanation": { "type": "array", "items": { "type": "string" } },
+          "recommendation": { "$ref": "#/properties/recommendation" }
         }
       }
     },
@@ -81,14 +101,18 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "current", "latest", "updateType"],
+        "required": ["name", "current", "latest", "updateType", "confidence", "reasonCodes", "explanation", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "current": { "type": "string" },
           "latest": { "type": "string" },
           "updateType": { "type": "string" },
-          "package": { "type": "string" }
+          "package": { "type": "string" },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "reasonCodes": { "type": "array", "items": { "type": "string" } },
+          "explanation": { "type": "array", "items": { "type": "string" } },
+          "recommendation": { "$ref": "#/properties/recommendation" }
         }
       }
     },
@@ -96,16 +120,37 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "reasons"],
+        "required": ["name", "reasons", "confidence", "reasonCodes", "explanation", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "reasons": { "type": "array", "items": { "type": "string" } },
-          "package": { "type": "string" }
+          "package": { "type": "string" },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "reasonCodes": { "type": "array", "items": { "type": "string" } },
+          "explanation": { "type": "array", "items": { "type": "string" } },
+          "recommendation": { "$ref": "#/properties/recommendation" }
         }
       }
     },
     "suggestions": { "type": "array", "items": { "type": "string" } },
+    "topIssues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "name", "priority", "confidence", "summary", "recommendation"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "type": "string", "enum": ["unused", "duplicate", "outdated", "risk"] },
+          "name": { "type": "string" },
+          "package": { "type": "string" },
+          "priority": { "type": "string", "enum": ["high", "medium", "low"] },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "summary": { "type": "string" },
+          "recommendation": { "$ref": "#/properties/recommendation" }
+        }
+      }
+    },
     "config": { "type": "object" },
     "packages": { "type": "array" }
   }

package/dist/checks/duplicate.js

@@ -3,11 +3,36 @@ export async function findDuplicateDependencies(graph) {
         .map(([name, instances]) => ({
         name,
         versions: Array.from(new Set(instances.map((instance) => instance.version))).sort(),
-        instances
+        instances,
+        confidence: 0.98,
+        reasonCodes: [
+            "multiple_lockfile_versions",
+            "multiple_installation_paths"
+        ],
+        explanation: [
+            `Multiple versions of ${name} were found in the lockfile.`,
+            "The package is installed from more than one dependency path."
+        ],
+        recommendation: buildDuplicateRecommendation(Array.from(new Set(instances.map((instance) => instance.version))).sort(), instances.length)
     }))
         .filter((dependency) => dependency.versions.length > 1)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+function buildDuplicateRecommendation(versions, instanceCount) {
+    const targetVersion = versions[versions.length - 1];
+    return {
+        action: "consolidate",
+        priority: versions.length >= 3 ? "high" : "medium",
+        safety: "caution",
+        summary: targetVersion
+            ? `Consolidate toward ${targetVersion}; ${instanceCount} installation paths are affected.`
+            : "Consolidate duplicate versions to a single target version.",
+        reasons: [
+            "Multiple versions of the same package were detected in the lockfile.",
+            "Consolidating versions can reduce drift and simplify upgrades."
+        ]
+    };
+}
 export async function runDuplicateCheck(graph) {
     const duplicates = await findDuplicateDependencies(graph);
     return {
@@ -17,6 +42,9 @@ export async function runDuplicateCheck(graph) {
             id: `duplicate:${item.name}`,
             message: `${item.name} has ${item.versions.length} versions`,
             severity: "warning",
+            confidence: item.confidence,
+            reasonCodes: item.reasonCodes,
+            explanation: item.explanation,
             meta: {
                 name: item.name,
                 versions: item.versions,

package/dist/checks/outdated.js

@@ -11,17 +11,45 @@ export async function findOutdatedDependencies(graph, options = {}) {
         if (!latest || latest === normalized) {
             return null;
         }
+        const updateType = classifyUpdateType(normalized, latest);
         return {
             name,
             current,
             latest,
-            updateType: classifyUpdateType(normalized, latest)
+            updateType,
+            confidence: 0.97,
+            reasonCodes: [
+                "latest_registry_version_newer",
+                `update_type_${updateType}`
+            ],
+            explanation: [
+                "The npm registry reports a newer published version than the one declared in this project.",
+                `The change is classified as a ${updateType} update.`
+            ],
+            recommendation: buildOutdatedRecommendation(updateType)
         };
     }));
     return results
         .filter((item) => item !== null)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+function buildOutdatedRecommendation(updateType) {
+    return {
+        action: "upgrade",
+        priority: updateType === "major" ? "high" : updateType === "minor" ? "medium" : "low",
+        safety: updateType === "patch" ? "safe" : updateType === "minor" ? "caution" : "unknown",
+        summary: updateType === "major"
+            ? "New major version available; review breaking changes before upgrading."
+            : updateType === "minor"
+                ? "New minor version available; review release notes before upgrading."
+                : updateType === "patch"
+                    ? "Routine patch update available."
+                    : "Newer version available; review upgrade impact.",
+        reasons: [
+            "A newer published version is available in the registry."
+        ]
+    };
+}
 export async function runOutdatedCheck(graph) {
     const outdated = await findOutdatedDependencies(graph);
     return {
@@ -31,6 +59,9 @@ export async function runOutdatedCheck(graph) {
             id: `outdated:${item.name}`,
             message: `${item.name} ${item.current} -> ${item.latest}`,
             severity: item.updateType === "major" ? "critical" : "warning",
+            confidence: item.confidence,
+            reasonCodes: item.reasonCodes,
+            explanation: item.explanation,
             meta: {
                 name: item.name,
                 current: item.current,

package/dist/checks/risk.js

@@ -23,12 +23,28 @@ export async function findRiskDependencies(graph) {
         if (reasons.length === 0) {
             return null;
         }
-        return { name, reasons };
+        return {
+            name,
+            reasons,
+            confidence: calculateRiskConfidence(reasons),
+            reasonCodes: reasons.map(toRiskReasonCode),
+            explanation: reasons,
+            recommendation: buildRiskRecommendation(reasons, calculateRiskConfidence(reasons))
+        };
     }));
     return results
         .filter((item) => item !== null)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+function buildRiskRecommendation(reasons, confidence) {
+    return {
+        action: "review",
+        priority: confidence >= 0.79 ? "high" : "medium",
+        safety: "caution",
+        summary: "Review package trust signals and decide whether to keep, replace, or monitor it.",
+        reasons
+    };
+}
 export async function runRiskCheck(graph) {
     const risks = await findRiskDependencies(graph);
     return {
@@ -38,6 +54,9 @@ export async function runRiskCheck(graph) {
             id: `risk:${item.name}`,
             message: `${item.name}: ${item.reasons.join("; ")}`,
             severity: "warning",
+            confidence: item.confidence,
+            reasonCodes: item.reasonCodes,
+            explanation: item.explanation,
             meta: {
                 name: item.name,
                 reasons: item.reasons
@@ -45,3 +64,13 @@ export async function runRiskCheck(graph) {
         }))
     };
 }
+function calculateRiskConfidence(reasons) {
+    return Math.min(0.99, 0.55 + reasons.length * 0.12);
+}
+function toRiskReasonCode(reason) {
+    const normalized = reason
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return normalized || "risk_signal_detected";
+}

package/dist/checks/unused.js

@@ -33,11 +33,11 @@ export async function findUnusedDependencies(rootDir, graph, fileEntries, option
     }
     const unusedDependencies = Object.keys(graph.dependencies)
         .filter((name) => !runtimeUsed.has(name))
-        .map((name) => ({ name, section: "dependencies" }));
+        .map((name) => buildUnusedDependency(name, "dependencies"));
     const unusedDevDependencies = Object.keys(graph.devDependencies)
         .filter((name) => !devUsed.has(name) && !runtimeUsed.has(name))
         .filter((name) => !isImplicitlyUsedDevDependency(name, hasTypeScriptSources, options.hasTypeScriptConfig))
-        .map((name) => ({ name, section: "devDependencies" }));
+        .map((name) => buildUnusedDependency(name, "devDependencies"));
     return [...unusedDependencies, ...unusedDevDependencies].sort((left, right) => left.name.localeCompare(right.name));
 }
 export async function runUnusedCheck(context) {
@@ -49,6 +49,9 @@ export async function runUnusedCheck(context) {
             id: `unused:${item.section}:${item.name}`,
             message: `${item.name} appears unused`,
             severity: "warning",
+            confidence: item.confidence,
+            reasonCodes: item.reasonCodes,
+            explanation: item.explanation,
             meta: {
                 name: item.name,
                 section: item.section
@@ -127,3 +130,36 @@ function isImplicitlyUsedDevDependency(name, hasTypeScriptSources, hasTypeScript
     }
     return false;
 }
+function buildUnusedDependency(name, section) {
+    return {
+        name,
+        section,
+        confidence: section === "dependencies" ? 0.9 : 0.82,
+        reasonCodes: [
+            "no_source_import_found",
+            "no_config_reference_found",
+            "no_script_reference_found"
+        ],
+        explanation: [
+            "No import or require usage was found in scanned source files.",
+            "No matching reference was found in recognized config files.",
+            "No matching binary or package reference was found in package scripts."
+        ],
+        recommendation: buildUnusedRecommendation(section)
+    };
+}
+function buildUnusedRecommendation(section) {
+    const safety = section === "devDependencies" ? "safe" : "caution";
+    return {
+        action: "remove",
+        priority: section === "dependencies" ? "high" : "medium",
+        safety,
+        summary: safety === "safe"
+            ? `Safe to remove from ${section}.`
+            : `Likely removable from ${section}, but review before deleting.`,
+        reasons: [
+            "No code usage was found in scanned files.",
+            "No config or script reference was detected."
+        ]
+    };
+}

package/dist/cli.js

@@ -51,9 +51,11 @@ async function main() {
                 const resolvedFrom = resolveUserPath(fromPath);
                 const raw = await fs.readFile(resolvedFrom, "utf8");
                 const reportData = JSON.parse(raw);
-                const output = flags.has("--json")
-                    ? JSON.stringify(reportData, null, 2)
-                    : renderMarkdownReport(reportData);
+                const output = flags.has("--top")
+                    ? renderTopIssuesReport(reportData)
+                    : flags.has("--json")
+                        ? JSON.stringify(reportData, null, 2)
+                        : renderMarkdownReport(reportData);
                 await writeOutput(output, optionValues.get("--out"));
                 return;
             }
@@ -107,6 +109,9 @@ async function main() {
         if (flags.has("--json")) {
             output = renderJsonReport(result);
         }
+        else if (flags.has("--top")) {
+            output = renderTopIssuesReport(result);
+        }
         else if (flags.has("--md")) {
             output = renderMarkdownReport(result);
         }
@@ -173,8 +178,8 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    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 analyze [path] [--json] [--md] [--top] [--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] [--top] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain help");
     console.log("  dep-brain --version");
@@ -182,6 +187,7 @@ function printHelp() {
     console.log("Options:");
     console.log("  --json              Output JSON for analysis");
     console.log("  --md                Output Markdown report");
+    console.log("  --top               Output the ranked top issues only");
     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");
@@ -218,3 +224,18 @@ function sanitizeForLog(value) {
 function resolveUserPath(value) {
     return path.resolve(process.cwd(), value);
 }
+function renderTopIssuesReport(result) {
+    const lines = [];
+    lines.push("Top Issues");
+    lines.push("");
+    if (!Array.isArray(result.topIssues) || result.topIssues.length === 0) {
+        lines.push("No actionable issues found.");
+        return lines.join("\n");
+    }
+    for (const [index, item] of result.topIssues.entries()) {
+        lines.push(`${index + 1}. [${item.priority.toUpperCase()}] ${item.kind} ${item.name}${item.package ? ` [${item.package}]` : ""}`);
+        lines.push(`   Confidence: ${Math.round(item.confidence * 100)}%`);
+        lines.push(`   Next: ${item.recommendation.summary}`);
+    }
+    return lines.join("\n");
+}

package/dist/core/analyzer.d.ts

@@ -8,15 +8,30 @@ export interface DuplicateInstance {
     path: string;
     version: string;
 }
+export interface Recommendation {
+    action: "remove" | "consolidate" | "upgrade" | "review";
+    priority: "high" | "medium" | "low";
+    safety: "safe" | "caution" | "unknown";
+    summary: string;
+    reasons: string[];
+}
 export interface DuplicateDependency {
     name: string;
     versions: string[];
     instances: DuplicateInstance[];
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
+    recommendation: Recommendation;
 }
 export interface UnusedDependency {
     name: string;
     section: "dependencies" | "devDependencies";
     package?: string;
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
+    recommendation: Recommendation;
 }
 export interface OutdatedDependency {
     name: string;
@@ -24,11 +39,28 @@ export interface OutdatedDependency {
     latest: string;
     updateType: "major" | "minor" | "patch" | "unknown";
     package?: string;
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
+    recommendation: Recommendation;
 }
 export interface RiskDependency {
     name: string;
     reasons: string[];
     package?: string;
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
+    recommendation: Recommendation;
+}
+export interface TopIssue {
+    kind: "unused" | "duplicate" | "outdated" | "risk";
+    name: string;
+    package?: string;
+    priority: "high" | "medium" | "low";
+    confidence: number;
+    summary: string;
+    recommendation: Recommendation;
 }
 export interface AnalysisResult {
     outputVersion: string;
@@ -41,6 +73,7 @@ export interface AnalysisResult {
     outdated: OutdatedDependency[];
     risks: RiskDependency[];
     suggestions: string[];
+    topIssues: TopIssue[];
     config: DepBrainConfig;
     packages?: PackageAnalysisResult[];
 }
@@ -59,8 +92,9 @@ export interface PackageAnalysisResult {
     outdated: OutdatedDependency[];
     risks: RiskDependency[];
     suggestions: string[];
+    topIssues: TopIssue[];
 }
-export declare const OUTPUT_VERSION = "1.0";
+export declare const OUTPUT_VERSION = "1.2";
 export interface ScoreBreakdown {
     baseScore: number;
     duplicates: number;

package/dist/core/analyzer.js

@@ -8,7 +8,7 @@ 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 const OUTPUT_VERSION = "1.2";
 export async function analyzeProject(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
     const loadedConfig = await loadDepBrainConfig(rootDir, options.configPath);
@@ -68,6 +68,7 @@ export async function analyzeProject(options = {}) {
         outdated,
         risks,
         suggestions,
+        topIssues: buildTopIssues({ duplicates, unused, outdated, risks }),
         config,
         packages
     };
@@ -186,6 +187,12 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
         outdated: scopedOutdated,
         risks: scopedRisks,
         suggestions,
+        topIssues: buildTopIssues({
+            duplicates,
+            unused: scopedUnused,
+            outdated: scopedOutdated,
+            risks: scopedRisks
+        }),
         config
     };
 }
@@ -264,13 +271,21 @@ function mapDuplicateIssues(issues) {
         versions: Array.isArray(issue.meta?.versions) ? issue.meta?.versions : [],
         instances: Array.isArray(issue.meta?.instances)
             ? issue.meta?.instances
-            : []
+            : [],
+        confidence: normalizeConfidence(issue.confidence),
+        reasonCodes: normalizeStringArray(issue.reasonCodes),
+        explanation: normalizeStringArray(issue.explanation),
+        recommendation: buildDuplicateRecommendation(issue)
     }));
 }
 function mapUnusedIssues(issues) {
     return issues.map((issue) => ({
         name: String(issue.meta?.name ?? issue.package ?? "unknown"),
-        section: issue.meta?.section === "devDependencies" ? "devDependencies" : "dependencies"
+        section: issue.meta?.section === "devDependencies" ? "devDependencies" : "dependencies",
+        confidence: normalizeConfidence(issue.confidence),
+        reasonCodes: normalizeStringArray(issue.reasonCodes),
+        explanation: normalizeStringArray(issue.explanation),
+        recommendation: buildUnusedRecommendation(issue)
     }));
 }
 function mapOutdatedIssues(issues) {
@@ -280,15 +295,148 @@ function mapOutdatedIssues(issues) {
         latest: String(issue.meta?.latest ?? ""),
         updateType: issue.meta?.updateType === "major" || issue.meta?.updateType === "minor" || issue.meta?.updateType === "patch"
             ? issue.meta.updateType
-            : "unknown"
+            : "unknown",
+        confidence: normalizeConfidence(issue.confidence),
+        reasonCodes: normalizeStringArray(issue.reasonCodes),
+        explanation: normalizeStringArray(issue.explanation),
+        recommendation: buildOutdatedRecommendation(issue)
     }));
 }
 function mapRiskIssues(issues) {
     return issues.map((issue) => ({
         name: String(issue.meta?.name ?? issue.package ?? "unknown"),
-        reasons: Array.isArray(issue.meta?.reasons) ? issue.meta?.reasons : []
+        reasons: Array.isArray(issue.meta?.reasons) ? issue.meta?.reasons : [],
+        confidence: normalizeConfidence(issue.confidence),
+        reasonCodes: normalizeStringArray(issue.reasonCodes),
+        explanation: normalizeStringArray(issue.explanation),
+        recommendation: buildRiskRecommendation(issue)
     }));
 }
+function buildUnusedRecommendation(issue) {
+    const confidence = normalizeConfidence(issue.confidence);
+    const section = issue.meta?.section === "devDependencies" ? "devDependencies" : "dependencies";
+    const safety = section === "devDependencies" || confidence >= 0.88
+        ? "safe"
+        : confidence >= 0.7
+            ? "caution"
+            : "unknown";
+    return {
+        action: "remove",
+        priority: confidence >= 0.88 ? "high" : "medium",
+        safety,
+        summary: safety === "safe"
+            ? `Safe to remove from ${section}.`
+            : safety === "caution"
+                ? `Likely removable from ${section}, but review before deleting.`
+                : `Potentially removable from ${section}, but evidence is limited.`,
+        reasons: normalizeStringArray(issue.explanation)
+    };
+}
+function buildDuplicateRecommendation(issue) {
+    const versions = Array.isArray(issue.meta?.versions) ? issue.meta.versions : [];
+    const targetVersion = versions[versions.length - 1];
+    const instances = Array.isArray(issue.meta?.instances) ? issue.meta.instances.length : 0;
+    return {
+        action: "consolidate",
+        priority: versions.length >= 3 ? "high" : "medium",
+        safety: "caution",
+        summary: targetVersion
+            ? `Consolidate toward ${targetVersion}; ${instances} installation paths are affected.`
+            : "Consolidate duplicate versions to a single target version.",
+        reasons: normalizeStringArray(issue.explanation)
+    };
+}
+function buildOutdatedRecommendation(issue) {
+    const updateType = issue.meta?.updateType === "major" ||
+        issue.meta?.updateType === "minor" ||
+        issue.meta?.updateType === "patch"
+        ? issue.meta.updateType
+        : "unknown";
+    const priority = updateType === "major" ? "high" : updateType === "minor" ? "medium" : "low";
+    const safety = updateType === "patch" ? "safe" : updateType === "minor" ? "caution" : "unknown";
+    return {
+        action: "upgrade",
+        priority,
+        safety,
+        summary: updateType === "major"
+            ? "New major version available; review breaking changes before upgrading."
+            : updateType === "minor"
+                ? "New minor version available; review release notes before upgrading."
+                : updateType === "patch"
+                    ? "Routine patch update available."
+                    : "Newer version available; review upgrade impact.",
+        reasons: normalizeStringArray(issue.explanation)
+    };
+}
+function buildRiskRecommendation(issue) {
+    const reasons = normalizeStringArray(issue.explanation);
+    const confidence = normalizeConfidence(issue.confidence);
+    return {
+        action: "review",
+        priority: confidence >= 0.79 ? "high" : "medium",
+        safety: "caution",
+        summary: "Review package trust signals and decide whether to keep, replace, or monitor it.",
+        reasons
+    };
+}
+function buildTopIssues(input) {
+    const issues = [
+        ...input.unused.map((item) => ({
+            kind: "unused",
+            name: item.name,
+            package: item.package,
+            priority: item.recommendation.priority,
+            confidence: item.confidence,
+            summary: item.recommendation.summary,
+            recommendation: item.recommendation
+        })),
+        ...input.duplicates.map((item) => ({
+            kind: "duplicate",
+            name: item.name,
+            priority: item.recommendation.priority,
+            confidence: item.confidence,
+            summary: item.recommendation.summary,
+            recommendation: item.recommendation
+        })),
+        ...input.outdated.map((item) => ({
+            kind: "outdated",
+            name: item.name,
+            package: item.package,
+            priority: item.recommendation.priority,
+            confidence: item.confidence,
+            summary: item.recommendation.summary,
+            recommendation: item.recommendation
+        })),
+        ...input.risks.map((item) => ({
+            kind: "risk",
+            name: item.name,
+            package: item.package,
+            priority: item.recommendation.priority,
+            confidence: item.confidence,
+            summary: item.recommendation.summary,
+            recommendation: item.recommendation
+        }))
+    ];
+    return issues
+        .sort((left, right) => comparePriority(right.priority, left.priority) || right.confidence - left.confidence)
+        .slice(0, 5);
+}
+function comparePriority(left, right) {
+    const rank = { high: 3, medium: 2, low: 1 };
+    return rank[left] - rank[right];
+}
+function normalizeConfidence(value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return 0.5;
+    }
+    return Math.min(0.99, Math.max(0, Number(value.toFixed(2))));
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string");
+}
 function buildScoreBreakdown(counts, config) {
     return {
         baseScore: 100,

package/dist/core/types.d.ts

@@ -1,9 +1,13 @@
 export type IssueSeverity = "info" | "warning" | "critical";
+export type ReasonCode = string;
 export type Issue = {
     id: string;
     message: string;
     package?: string;
     severity: IssueSeverity;
+    confidence?: number;
+    reasonCodes?: ReasonCode[];
+    explanation?: string[];
     meta?: Record<string, unknown>;
 };
 export type CheckResult = {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { analyzeProject } from "./core/analyzer.js";
-export type { AnalysisOptions, AnalysisResult, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, ScoreBreakdown, RiskDependency, UnusedDependency } from "./core/analyzer.js";
+export type { AnalysisOptions, AnalysisResult, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, Recommendation, ScoreBreakdown, RiskDependency, TopIssue, 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";

package/dist/reporters/console.js

@@ -1,5 +1,12 @@
 export function renderConsoleReport(result) {
     const lines = [];
+    if (result.topIssues.length > 0) {
+        lines.push("Top Issues:");
+        for (const item of result.topIssues) {
+            lines.push(`- [${item.priority.toUpperCase()}] ${item.kind} ${item.name}${item.package ? ` [${item.package}]` : ""} | confidence ${Math.round(item.confidence * 100)}% | ${item.summary}`);
+        }
+        lines.push("");
+    }
     lines.push(`Project Health: ${result.score}/100`);
     lines.push(`Path: ${result.rootDir}`);
     lines.push(`Policy: ${result.policy.passed ? "PASS" : "FAIL"}`);
@@ -16,16 +23,16 @@ export function renderConsoleReport(result) {
             lines.push(`- ${pkg.name}: ${pkg.score}/100, D:${pkg.duplicates.length} U:${pkg.unused.length} O:${pkg.outdated.length} R:${pkg.risks.length}`);
         }
     }
-    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => `${item.name}: ${item.versions.join(", ")}`));
-    appendSection(lines, "Unused dependencies", result.unused.map((item) => item.package
+    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => formatEntry(`${item.name}: ${item.versions.join(", ")}`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Unused dependencies", result.unused.map((item) => formatEntry(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.section})`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Outdated dependencies", result.outdated.map((item) => formatEntry(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.current} -> ${item.latest} [${item.updateType}]`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Risky dependencies", result.risks.map((item) => formatEntry(item.package
         ? `${item.name}: ${item.reasons.join("; ")} [${item.package}]`
-        : `${item.name}: ${item.reasons.join("; ")}`));
+        : `${item.name}: ${item.reasons.join("; ")}`, item.confidence, item.explanation, item.recommendation)));
     appendSection(lines, "Policy reasons", result.policy.reasons);
     if (result.suggestions.length > 0) {
         lines.push("");
@@ -50,3 +57,10 @@ function appendSection(lines, title, entries) {
         lines.push(`- ${entry}`);
     }
 }
+function formatEntry(label, confidence, explanation, recommendation) {
+    const reasonSummary = explanation.length > 0 ? ` | why: ${explanation.join("; ")}` : "";
+    const recommendationSummary = recommendation
+        ? ` | next: ${recommendation.summary}`
+        : "";
+    return `${label} | confidence ${Math.round(confidence * 100)}%${recommendationSummary}${reasonSummary}`;
+}

package/dist/reporters/markdown.js

@@ -2,6 +2,13 @@ export function renderMarkdownReport(result) {
     const lines = [];
     lines.push(`# Dependency Brain Report`);
     lines.push("");
+    if (result.topIssues.length > 0) {
+        lines.push("## Top Issues");
+        for (const item of result.topIssues) {
+            lines.push(`- **${item.priority.toUpperCase()}** ${item.kind} \`${item.name}\`${item.package ? ` [${item.package}]` : ""} | confidence ${Math.round(item.confidence * 100)}% | ${item.summary}`);
+        }
+        lines.push("");
+    }
     lines.push(`- **Project Health:** ${result.score}/100`);
     lines.push(`- **Path:** ${result.rootDir}`);
     lines.push(`- **Policy:** ${result.policy.passed ? "PASS" : "FAIL"}`);
@@ -20,16 +27,16 @@ export function renderMarkdownReport(result) {
     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
+    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => formatEntry(`${item.name}: ${item.versions.join(", ")}`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Unused dependencies", result.unused.map((item) => formatEntry(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.section})`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Outdated dependencies", result.outdated.map((item) => formatEntry(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.current} -> ${item.latest} [${item.updateType}]`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Risky dependencies", result.risks.map((item) => formatEntry(item.package
         ? `${item.name}: ${item.reasons.join("; ")} [${item.package}]`
-        : `${item.name}: ${item.reasons.join("; ")}`));
+        : `${item.name}: ${item.reasons.join("; ")}`, item.confidence, item.explanation, item.recommendation)));
     appendSection(lines, "Policy reasons", result.policy.reasons);
     if (result.suggestions.length > 0) {
         lines.push("## Suggestions");
@@ -50,3 +57,10 @@ function appendSection(lines, title, items) {
     }
     lines.push("");
 }
+function formatEntry(label, confidence, explanation, recommendation) {
+    const reasonSummary = explanation.length > 0 ? ` | why: ${explanation.join("; ")}` : "";
+    const recommendationSummary = recommendation
+        ? ` | next: ${recommendation.summary}`
+        : "";
+    return `${label} | confidence ${Math.round(confidence * 100)}%${recommendationSummary}${reasonSummary}`;
+}

package/package.json

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