dep-brain 0.5.2 → 0.6.0

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
@@ -225,14 +236,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

@@ -44,11 +44,14 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "versions", "instances"],
+        "required": ["name", "versions", "instances", "confidence", "reasonCodes", "explanation"],
         "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" } },
           "instances": {
             "type": "array",
             "items": {
@@ -68,12 +71,15 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "section"],
+        "required": ["name", "section", "confidence", "reasonCodes", "explanation"],
         "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" } }
         }
       }
     },
@@ -81,14 +87,17 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "current", "latest", "updateType"],
+        "required": ["name", "current", "latest", "updateType", "confidence", "reasonCodes", "explanation"],
         "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" } }
         }
       }
     },
@@ -96,12 +105,15 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "reasons"],
+        "required": ["name", "reasons", "confidence", "reasonCodes", "explanation"],
         "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" } }
         }
       }
     },

package/dist/checks/duplicate.js

@@ -3,7 +3,16 @@ 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."
+        ]
     }))
         .filter((dependency) => dependency.versions.length > 1)
         .sort((left, right) => left.name.localeCompare(right.name));
@@ -17,6 +26,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

@@ -15,7 +15,16 @@ export async function findOutdatedDependencies(graph, options = {}) {
             name,
             current,
             latest,
-            updateType: classifyUpdateType(normalized, latest)
+            updateType: classifyUpdateType(normalized, latest),
+            confidence: 0.97,
+            reasonCodes: [
+                "latest_registry_version_newer",
+                `update_type_${classifyUpdateType(normalized, latest)}`
+            ],
+            explanation: [
+                "The npm registry reports a newer published version than the one declared in this project.",
+                `The change is classified as a ${classifyUpdateType(normalized, latest)} update.`
+            ]
         };
     }));
     return results
@@ -31,6 +40,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,7 +23,13 @@ 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
+        };
     }));
     return results
         .filter((item) => item !== null)
@@ -38,6 +44,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 +54,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,20 @@ 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."
+        ]
+    };
+}

package/dist/core/analyzer.d.ts

@@ -12,11 +12,17 @@ export interface DuplicateDependency {
     name: string;
     versions: string[];
     instances: DuplicateInstance[];
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
 }
 export interface UnusedDependency {
     name: string;
     section: "dependencies" | "devDependencies";
     package?: string;
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
 }
 export interface OutdatedDependency {
     name: string;
@@ -24,11 +30,17 @@ export interface OutdatedDependency {
     latest: string;
     updateType: "major" | "minor" | "patch" | "unknown";
     package?: string;
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
 }
 export interface RiskDependency {
     name: string;
     reasons: string[];
     package?: string;
+    confidence: number;
+    reasonCodes: string[];
+    explanation: string[];
 }
 export interface AnalysisResult {
     outputVersion: string;
@@ -60,7 +72,7 @@ export interface PackageAnalysisResult {
     risks: RiskDependency[];
     suggestions: string[];
 }
-export declare const OUTPUT_VERSION = "1.0";
+export declare const OUTPUT_VERSION = "1.1";
 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.1";
 export async function analyzeProject(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
     const loadedConfig = await loadDepBrainConfig(rootDir, options.configPath);
@@ -264,13 +264,19 @@ 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)
     }));
 }
 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)
     }));
 }
 function mapOutdatedIssues(issues) {
@@ -280,15 +286,33 @@ 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)
     }));
 }
 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)
     }));
 }
+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/reporters/console.js

@@ -16,16 +16,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)));
+    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)));
+    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)));
+    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)));
     appendSection(lines, "Policy reasons", result.policy.reasons);
     if (result.suggestions.length > 0) {
         lines.push("");
@@ -50,3 +50,7 @@ function appendSection(lines, title, entries) {
         lines.push(`- ${entry}`);
     }
 }
+function formatEntry(label, confidence, explanation) {
+    const reasonSummary = explanation.length > 0 ? ` | why: ${explanation.join("; ")}` : "";
+    return `${label} | confidence ${Math.round(confidence * 100)}%${reasonSummary}`;
+}

package/dist/reporters/markdown.js

@@ -20,16 +20,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)));
+    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)));
+    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)));
+    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)));
     appendSection(lines, "Policy reasons", result.policy.reasons);
     if (result.suggestions.length > 0) {
         lines.push("## Suggestions");
@@ -50,3 +50,7 @@ function appendSection(lines, title, items) {
     }
     lines.push("");
 }
+function formatEntry(label, confidence, explanation) {
+    const reasonSummary = explanation.length > 0 ? ` | why: ${explanation.join("; ")}` : "";
+    return `${label} | confidence ${Math.round(confidence * 100)}%${reasonSummary}`;
+}

package/package.json

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