dep-brain 1.3.0 → 1.5.0

package/dist/checks/risk.js

@@ -1,11 +1,14 @@
 import { getPackageMetadata } from "../utils/npm-api.js";
 export async function findRiskDependencies(graph, options = {}) {
     const resolvePackageMetadata = options.resolvePackageMetadata ?? getPackageMetadata;
-    const names = Object.keys({
+    const thresholds = options.thresholds;
+    const allNames = Object.keys({
         ...graph.dependencies,
-        ...graph.devDependencies
+        ...graph.devDependencies,
+        ...(graph.lockPackages ?? {})
     });
-    const results = await mapWithConcurrency(names, 8, async (name) => {
+    const assessments = new Map();
+    const results = await mapWithConcurrency(allNames, 8, async (name) => {
         const metadata = await resolvePackageMetadata(name);
         if (!metadata) {
             return null;
@@ -15,24 +18,25 @@ export async function findRiskDependencies(graph, options = {}) {
             : graph.devDependencies[name]
                 ? "devDependencies"
                 : "unknown";
-        const assessment = assessRisk(metadata, dependencyType, options.thresholds);
-        if (!shouldReportRisk(assessment.trustScore, dependencyType)) {
-            return null;
-        }
+        const assessment = assessRisk(metadata, dependencyType, thresholds, 0);
         return {
             name,
-            reasons: assessment.reasons,
-            confidence: assessment.confidence,
-            reasonCodes: assessment.reasonCodes,
-            explanation: assessment.reasons,
-            trustScore: assessment.trustScore,
-            riskFactors: assessment.riskFactors,
-            recommendation: buildRiskRecommendation(assessment.reasons, assessment.confidence, assessment.trustScore)
+            assessment
         };
     });
-    return results
-        .filter((item) => item !== null)
-        .sort((left, right) => left.name.localeCompare(right.name));
+    for (const result of results) {
+        if (result) {
+            assessments.set(result.name, result.assessment);
+        }
+    }
+    const directNames = Object.keys({
+        ...graph.dependencies,
+        ...graph.devDependencies
+    }).sort((left, right) => left.localeCompare(right));
+    const risks = directNames
+        .map((name) => buildDirectRiskEntry(name, graph, assessments, thresholds))
+        .filter((item) => item !== null);
+    return risks.sort((left, right) => left.name.localeCompare(right.name));
 }
 async function mapWithConcurrency(items, limit, mapper) {
     const results = new Array(items.length);
@@ -68,12 +72,120 @@ export async function runRiskCheck(graph, options = {}) {
                 name: item.name,
                 reasons: item.reasons,
                 trustScore: item.trustScore,
-                riskFactors: item.riskFactors
+                riskFactors: item.riskFactors,
+                transitiveRiskScore: item.transitiveRiskScore,
+                riskyTransitiveDeps: item.riskyTransitiveDeps
             }
         }))
     };
 }
-function assessRisk(metadata, dependencyType, thresholds) {
+function buildDirectRiskEntry(name, graph, assessments, thresholds) {
+    const dependencyType = graph.dependencies[name]
+        ? "dependencies"
+        : graph.devDependencies[name]
+            ? "devDependencies"
+            : "unknown";
+    const selfAssessment = assessments.get(name) ?? buildUnknownAssessment(name, dependencyType);
+    const transitive = collectTransitiveRisks(name, graph, assessments);
+    const reasonCodes = [...selfAssessment.reasonCodes];
+    const reasons = [...selfAssessment.reasons];
+    const explanation = [...selfAssessment.reasons];
+    if (transitive.riskyTransitiveDeps.length > 0) {
+        reasons.push(`Introduces ${transitive.riskyTransitiveDeps.length} risky transitive dependenc${transitive.riskyTransitiveDeps.length === 1 ? "y" : "ies"}`);
+        reasonCodes.push("risky_transitive_dependencies");
+        explanation.push(`Transitive paths: ${transitive.riskyTransitiveDeps
+            .flatMap((item) => item.introducedByPaths)
+            .slice(0, 3)
+            .join("; ")}`);
+    }
+    if (transitive.transitiveDependencyCount > (thresholds?.transitiveBloatThreshold ?? 50)) {
+        reasons.push("Large transitive dependency tree");
+        reasonCodes.push("dependency_bloat");
+        explanation.push(`${name} introduces ${transitive.transitiveDependencyCount} transitive dependencies.`);
+    }
+    const transitiveRiskScore = transitive.riskyTransitiveDeps.reduce((total, item) => total + trustScoreWeight(item.trustScore), 0);
+    const combinedConfidence = Math.min(0.99, Math.max(selfAssessment.confidence, transitive.riskyTransitiveDeps.reduce((maxConfidence, item) => Math.max(maxConfidence, item.confidence), 0.5)));
+    const trustScore = combineTrustScores(selfAssessment.trustScore, transitive.highestTrustScore);
+    const shouldReport = shouldReportRisk(selfAssessment.trustScore, dependencyType) ||
+        transitive.riskyTransitiveDeps.length > 0 ||
+        transitive.transitiveDependencyCount > (thresholds?.transitiveBloatThreshold ?? 50);
+    if (!shouldReport || reasons.length === 0) {
+        return null;
+    }
+    return {
+        name,
+        reasons,
+        confidence: combinedConfidence,
+        reasonCodes: dedupeStrings(reasonCodes),
+        explanation: dedupeStrings(explanation),
+        trustScore,
+        riskFactors: {
+            ...selfAssessment.riskFactors,
+            dependencyType,
+            transitiveDependencyCount: transitive.transitiveDependencyCount,
+            riskyTransitiveCount: transitive.riskyTransitiveDeps.length
+        },
+        transitiveRiskScore,
+        riskyTransitiveDeps: transitive.riskyTransitiveDeps,
+        recommendation: buildRiskRecommendation(reasons, combinedConfidence, trustScore, transitive.riskyTransitiveDeps.length)
+    };
+}
+function collectTransitiveRisks(directName, graph, assessments) {
+    const visited = new Set();
+    const queue = (graph.lockDependencies?.[directName] ?? []).map((name) => ({
+        name,
+        path: [directName, name]
+    }));
+    const riskyByName = new Map();
+    let highestTrustScore = "high";
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current || visited.has(current.name)) {
+            continue;
+        }
+        visited.add(current.name);
+        const assessment = assessments.get(current.name);
+        if (assessment && shouldReportRisk(assessment.trustScore, assessment.riskFactors.dependencyType)) {
+            highestTrustScore = combineTrustScores(highestTrustScore, assessment.trustScore);
+            const existing = riskyByName.get(current.name);
+            const pathTrace = current.path.join(" -> ");
+            if (existing) {
+                existing.introducedByPaths.push(pathTrace);
+            }
+            else {
+                riskyByName.set(current.name, {
+                    name: current.name,
+                    trustScore: assessment.trustScore,
+                    confidence: assessment.confidence,
+                    reasons: assessment.reasons,
+                    introducedByPaths: [pathTrace]
+                });
+            }
+        }
+        const nextDependencies = graph.lockDependencies?.[current.name] ?? [];
+        for (const dependency of nextDependencies) {
+            if (!visited.has(dependency)) {
+                queue.push({
+                    name: dependency,
+                    path: [...current.path, dependency]
+                });
+            }
+        }
+    }
+    return {
+        transitiveDependencyCount: visited.size,
+        riskyTransitiveDeps: Array.from(riskyByName.values())
+            .map((item) => ({
+            ...item,
+            introducedByPaths: dedupeStrings(item.introducedByPaths).slice(0, 3)
+        }))
+            .sort((left, right) => trustScoreWeight(right.trustScore) - trustScoreWeight(left.trustScore) ||
+            right.confidence - left.confidence ||
+            left.name.localeCompare(right.name)),
+        highestTrustScore
+    };
+}
+function assessRisk(metadata, dependencyType, thresholds, transitiveDependencyCount) {
     const reasons = [];
     const reasonCodes = [];
     let weight = 0;
@@ -127,6 +239,7 @@ function assessRisk(metadata, dependencyType, thresholds) {
             ? "medium"
             : "high";
     return {
+        name: "",
         confidence,
         trustScore,
         reasons,
@@ -138,7 +251,29 @@ function assessRisk(metadata, dependencyType, thresholds) {
             versionCount: metadata.versionCount,
             recentReleaseCount: metadata.recentReleaseCount,
             hasRepository: Boolean(metadata.repository),
-            dependencyType
+            dependencyType,
+            transitiveDependencyCount,
+            riskyTransitiveCount: 0
+        }
+    };
+}
+function buildUnknownAssessment(name, dependencyType) {
+    return {
+        name,
+        confidence: 0.5,
+        trustScore: "high",
+        reasons: [],
+        reasonCodes: [],
+        riskFactors: {
+            daysSincePublish: null,
+            downloads: null,
+            maintainersCount: null,
+            versionCount: null,
+            recentReleaseCount: null,
+            hasRepository: false,
+            dependencyType,
+            transitiveDependencyCount: 0,
+            riskyTransitiveCount: 0
         }
     };
 }
@@ -160,14 +295,33 @@ function shouldReportRisk(trustScore, dependencyType) {
     }
     return true;
 }
-function buildRiskRecommendation(reasons, confidence, trustScore) {
+function buildRiskRecommendation(reasons, confidence, trustScore, riskyTransitiveCount) {
     return {
         action: "review",
-        priority: trustScore === "low" || confidence >= 0.8 ? "high" : "medium",
+        priority: trustScore === "low" || confidence >= 0.8 || riskyTransitiveCount >= 2
+            ? "high"
+            : "medium",
         safety: "caution",
-        summary: trustScore === "low"
-            ? "Low trust package; review whether to replace, pin, or monitor it closely."
-            : "Review package trust signals and decide whether to keep, replace, or monitor it.",
+        summary: riskyTransitiveCount > 0
+            ? `Review this direct dependency and its transitive chain before upgrading or keeping it.`
+            : trustScore === "low"
+                ? "Low trust package; review whether to replace, pin, or monitor it closely."
+                : "Review package trust signals and decide whether to keep, replace, or monitor it.",
         reasons
     };
 }
+function trustScoreWeight(value) {
+    if (value === "low") {
+        return 3;
+    }
+    if (value === "medium") {
+        return 2;
+    }
+    return 1;
+}
+function combineTrustScores(left, right) {
+    return trustScoreWeight(left) >= trustScoreWeight(right) ? left : right;
+}
+function dedupeStrings(values) {
+    return Array.from(new Set(values));
+}

package/dist/cli.js

@@ -56,13 +56,15 @@ async function main() {
                 const reportData = JSON.parse(raw);
                 const output = flags.has("--top")
                     ? renderTopIssuesReport(reportData)
-                    : flags.has("--json")
-                        ? JSON.stringify(reportData, null, 2)
-                        : flags.has("--sarif")
-                            ? renderSarifReport(reportData)
-                            : flags.has("--dashboard")
-                                ? renderDashboardReport(reportData)
-                                : renderMarkdownReport(reportData);
+                    : flags.has("--advise")
+                        ? renderUpgradeAdviceReport(reportData)
+                        : flags.has("--json")
+                            ? JSON.stringify(reportData, null, 2)
+                            : flags.has("--sarif")
+                                ? renderSarifReport(reportData)
+                                : flags.has("--dashboard")
+                                    ? renderDashboardReport(reportData)
+                                    : renderMarkdownReport(reportData);
                 await writeOutput(output, optionValues.get("--out"));
                 return;
             }
@@ -141,6 +143,9 @@ async function main() {
         else if (flags.has("--top")) {
             output = renderTopIssuesReport(result);
         }
+        else if (flags.has("--advise")) {
+            output = renderUpgradeAdviceReport(result);
+        }
         else if (flags.has("--md")) {
             output = renderMarkdownReport(result);
         }
@@ -216,7 +221,7 @@ function printHelp() {
     console.log("");
     console.log("Usage:");
     console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--dashboard] [--focus kind] [--ci] [--out path] [--config path] [--baseline path] [--min-score n] [--fail-on-risks]");
-    console.log("  dep-brain report --from <file> [--md] [--json] [--sarif] [--top] [--dashboard] [--out path]");
+    console.log("  dep-brain report --from <file> [--md] [--json] [--sarif] [--top] [--advise] [--dashboard] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain init [--out depbrain.config.json]");
     console.log("  dep-brain help");
@@ -227,6 +232,7 @@ function printHelp() {
     console.log("  --md                Output Markdown report");
     console.log("  --sarif             Output SARIF format for Code Scanning");
     console.log("  --top               Output the ranked top issues only");
+    console.log("  --advise            Output upgrade advice for outdated dependencies");
     console.log("  --dashboard         Write an HTML dashboard");
     console.log("  --dashboard-out <path> Write dashboard HTML to a custom path");
     console.log("  --focus <kind>      Run all, health, duplicates, unused, outdated, or risks");
@@ -336,3 +342,29 @@ function renderTopIssuesReport(result) {
     }
     return lines.join("\n");
 }
+function renderUpgradeAdviceReport(result) {
+    const lines = [];
+    lines.push("Upgrade Advice");
+    lines.push("");
+    if (!Array.isArray(result.outdated) || result.outdated.length === 0) {
+        lines.push("No outdated dependencies found.");
+        return lines.join("\n");
+    }
+    const sorted = [...result.outdated].sort((left, right) => compareAdviceRisk(right.advice.risk, left.advice.risk) ||
+        left.name.localeCompare(right.name));
+    for (const item of sorted) {
+        lines.push(`- ${item.name}: ${item.current} -> ${item.latest} [${item.updateType}] [${item.advice.risk.toUpperCase()}]`);
+        lines.push(`  Target: ${item.advice.recommendedTarget}`);
+        if (item.advice.intermediateSteps.length > 1) {
+            lines.push(`  Steps: ${item.advice.intermediateSteps.join(" -> ")}`);
+        }
+        if (item.advice.releaseNotes[0]) {
+            lines.push(`  Notes: ${item.advice.releaseNotes[0]}`);
+        }
+    }
+    return lines.join("\n");
+}
+function compareAdviceRisk(left, right) {
+    const rank = { high: 3, medium: 2, low: 1 };
+    return rank[left] - rank[right];
+}

package/dist/core/analyzer.d.ts

@@ -43,8 +43,17 @@ export interface RiskFactors {
     recentReleaseCount: number | null;
     hasRepository: boolean;
     dependencyType: "dependencies" | "devDependencies" | "unknown";
+    transitiveDependencyCount: number;
+    riskyTransitiveCount: number;
 }
 export type TrustScore = "high" | "medium" | "low";
+export interface RiskTransitiveDependency {
+    name: string;
+    trustScore: TrustScore;
+    confidence: number;
+    reasons: string[];
+    introducedByPaths: string[];
+}
 export interface DuplicateDependency {
     name: string;
     versions: string[];
@@ -74,8 +83,18 @@ export interface OutdatedDependency {
     confidence: number;
     reasonCodes: string[];
     explanation: string[];
+    advice: OutdatedDependencyAdvice;
     recommendation: Recommendation;
 }
+export interface OutdatedDependencyAdvice {
+    risk: "low" | "medium" | "high";
+    recommendedTarget: string;
+    latestEvaluatedVersion: string;
+    intermediateSteps: string[];
+    releaseNotes: string[];
+    signals: Array<"semver_major" | "breaking_keyword" | "missing_changelog">;
+    currentRange: string;
+}
 export interface RiskDependency {
     name: string;
     reasons: string[];
@@ -85,6 +104,8 @@ export interface RiskDependency {
     explanation: string[];
     trustScore: TrustScore;
     riskFactors: RiskFactors;
+    transitiveRiskScore: number;
+    riskyTransitiveDeps: RiskTransitiveDependency[];
     recommendation: Recommendation;
 }
 export interface TopIssue {
@@ -133,7 +154,7 @@ export interface PackageAnalysisResult {
     topIssues: TopIssue[];
     extensions: Record<string, unknown>;
 }
-export declare const OUTPUT_VERSION = "1.4";
+export declare const OUTPUT_VERSION = "1.6";
 export interface ScoreBreakdown {
     baseScore: number;
     duplicates: number;

package/dist/core/analyzer.js

@@ -9,7 +9,7 @@ import { buildDependencyGraph } from "./graph-builder.js";
 import { PluginManager } from "./plugin-manager.js";
 import { calculateHealthScore, calculateScoreDeductions } from "./scorer.js";
 import { buildAnalysisContext } from "./context.js";
-export const OUTPUT_VERSION = "1.4";
+export const OUTPUT_VERSION = "1.6";
 export async function analyzeProject(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
     const loadedConfig = await loadDepBrainConfig(rootDir, options.configPath);
@@ -384,6 +384,7 @@ function mapOutdatedIssues(issues) {
         confidence: normalizeConfidence(issue.confidence),
         reasonCodes: normalizeStringArray(issue.reasonCodes),
         explanation: normalizeStringArray(issue.explanation),
+        advice: normalizeOutdatedAdvice(issue.meta?.advice, issue.meta?.current, issue.meta?.latest),
         recommendation: buildOutdatedRecommendation(issue)
     }));
 }
@@ -396,6 +397,10 @@ function mapRiskIssues(issues) {
         explanation: normalizeStringArray(issue.explanation),
         trustScore: normalizeTrustScore(issue.meta?.trustScore),
         riskFactors: normalizeRiskFactors(issue.meta?.riskFactors),
+        transitiveRiskScore: typeof issue.meta?.transitiveRiskScore === "number"
+            ? issue.meta.transitiveRiskScore
+            : 0,
+        riskyTransitiveDeps: normalizeRiskTransitiveDependencies(issue.meta?.riskyTransitiveDeps),
         recommendation: buildRiskRecommendation(issue)
     }));
 }
@@ -439,19 +444,30 @@ function buildOutdatedRecommendation(issue) {
         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";
+    const advice = normalizeOutdatedAdvice(issue.meta?.advice, issue.meta?.current, issue.meta?.latest);
+    const priority = advice.risk === "high"
+        ? "high"
+        : updateType === "major"
+            ? "high"
+            : updateType === "minor"
+                ? "medium"
+                : "low";
+    const safety = advice.risk === "high"
+        ? "unknown"
+        : 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.",
+        summary: advice.risk === "high"
+            ? `Upgrade in steps toward ${advice.recommendedTarget}; review breaking signals first.`
+            : advice.risk === "medium"
+                ? `Upgrade toward ${advice.recommendedTarget} after reviewing release notes.`
+                : `Upgrade toward ${advice.recommendedTarget}.`,
         reasons: normalizeStringArray(issue.explanation)
     };
 }
@@ -459,13 +475,18 @@ function buildRiskRecommendation(issue) {
     const reasons = normalizeStringArray(issue.explanation);
     const confidence = normalizeConfidence(issue.confidence);
     const trustScore = normalizeTrustScore(issue.meta?.trustScore);
+    const riskyTransitiveDeps = normalizeRiskTransitiveDependencies(issue.meta?.riskyTransitiveDeps);
     return {
         action: "review",
-        priority: trustScore === "low" || confidence >= 0.79 ? "high" : "medium",
+        priority: trustScore === "low" || confidence >= 0.79 || riskyTransitiveDeps.length >= 2
+            ? "high"
+            : "medium",
         safety: "caution",
-        summary: trustScore === "low"
-            ? "Low trust package; review whether to replace, pin, or monitor it closely."
-            : "Review package trust signals and decide whether to keep, replace, or monitor it.",
+        summary: riskyTransitiveDeps.length > 0
+            ? "Review this direct dependency and its transitive chain before upgrading or keeping it."
+            : trustScore === "low"
+                ? "Low trust package; review whether to replace, pin, or monitor it closely."
+                : "Review package trust signals and decide whether to keep, replace, or monitor it.",
         reasons
     };
 }
@@ -604,7 +625,9 @@ function normalizeRiskFactors(value) {
             versionCount: null,
             recentReleaseCount: null,
             hasRepository: false,
-            dependencyType: "unknown"
+            dependencyType: "unknown",
+            transitiveDependencyCount: 0,
+            riskyTransitiveCount: 0
         };
     }
     const factors = value;
@@ -617,7 +640,75 @@ function normalizeRiskFactors(value) {
         hasRepository: factors.hasRepository === true,
         dependencyType: factors.dependencyType === "dependencies" || factors.dependencyType === "devDependencies"
             ? factors.dependencyType
-            : "unknown"
+            : "unknown",
+        transitiveDependencyCount: typeof factors.transitiveDependencyCount === "number" ? factors.transitiveDependencyCount : 0,
+        riskyTransitiveCount: typeof factors.riskyTransitiveCount === "number" ? factors.riskyTransitiveCount : 0
+    };
+}
+function normalizeRiskTransitiveDependencies(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+            return null;
+        }
+        const item = entry;
+        if (typeof item.name !== "string" ||
+            (item.trustScore !== "high" && item.trustScore !== "medium" && item.trustScore !== "low") ||
+            typeof item.confidence !== "number" ||
+            !Array.isArray(item.reasons) ||
+            !Array.isArray(item.introducedByPaths)) {
+            return null;
+        }
+        return {
+            name: item.name,
+            trustScore: item.trustScore,
+            confidence: normalizeConfidence(item.confidence),
+            reasons: item.reasons.filter((reason) => typeof reason === "string"),
+            introducedByPaths: item.introducedByPaths.filter((trace) => typeof trace === "string")
+        };
+    })
+        .filter((entry) => entry !== null);
+}
+function normalizeOutdatedAdvice(value, current, latest) {
+    const fallbackLatest = typeof latest === "string" ? latest : "";
+    const fallbackCurrent = typeof current === "string" ? current : "";
+    if (!value || typeof value !== "object") {
+        return {
+            risk: "medium",
+            recommendedTarget: fallbackLatest,
+            latestEvaluatedVersion: fallbackLatest,
+            intermediateSteps: fallbackLatest ? [fallbackLatest] : [],
+            releaseNotes: [],
+            signals: [],
+            currentRange: fallbackCurrent
+        };
+    }
+    const advice = value;
+    return {
+        risk: advice.risk === "low" || advice.risk === "medium" || advice.risk === "high"
+            ? advice.risk
+            : "medium",
+        recommendedTarget: typeof advice.recommendedTarget === "string" ? advice.recommendedTarget : fallbackLatest,
+        latestEvaluatedVersion: typeof advice.latestEvaluatedVersion === "string"
+            ? advice.latestEvaluatedVersion
+            : fallbackLatest,
+        intermediateSteps: Array.isArray(advice.intermediateSteps)
+            ? advice.intermediateSteps.filter((step) => typeof step === "string")
+            : fallbackLatest
+                ? [fallbackLatest]
+                : [],
+        releaseNotes: Array.isArray(advice.releaseNotes)
+            ? advice.releaseNotes.filter((url) => typeof url === "string")
+            : [],
+        signals: Array.isArray(advice.signals)
+            ? advice.signals.filter((signal) => signal === "semver_major" ||
+                signal === "breaking_keyword" ||
+                signal === "missing_changelog")
+            : [],
+        currentRange: typeof advice.currentRange === "string" ? advice.currentRange : fallbackCurrent
     };
 }
 function normalizeWorkspaceUsage(value) {

package/dist/core/graph-builder.d.ts

@@ -11,5 +11,6 @@ export interface DependencyGraph {
     overrides: Record<string, unknown>;
     scripts: Record<string, string>;
     lockPackages: Record<string, LockPackageInstance[]>;
+    lockDependencies: Record<string, string[]>;
 }
 export declare function buildDependencyGraph(rootDir: string): Promise<DependencyGraph>;