dep-brain 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.5.0
+
+- Added structured upgrade advisor data under `outdated[].advice`.
+- Added `--advise` report mode for upgrade guidance output.
+- Added stepped major-upgrade recommendations, release-note links, and breaking-change signals.
+- Updated dashboard, console, and markdown outputs with upgrade-priority guidance.
+- Bumped analysis output contract to `1.6` and added regression coverage for update advice.
+
 ## 1.4.0
 
 - Added lockfile dependency-edge parsing so transitive relationships are available from npm, pnpm, and yarn lockfiles.

package/README.md

@@ -6,6 +6,8 @@
 
 `dep-brain` is a CLI and library for explainable dependency intelligence in JavaScript and TypeScript projects.
 
+Current release `1.5.1` adds upgrade-advice output, stepped major-version guidance, release-note links, and analysis output contract `1.6`.
+
 ## Vision
 
 `dep-brain` aims to become a dependency decision engine:
@@ -25,6 +27,7 @@
 - Score package trust using supply-chain metadata
 - Generate a simple project health score
 - Output reports in console, JSON, Markdown, SARIF, dashboard, and top-issues formats
+- Output upgrade-advice reports via `--advise`
 - Gate CI with score and finding policies
 - Compare new findings against a baseline report
 
@@ -34,7 +37,7 @@ The long-term goal is not just to list problems, but to answer:
 - Can I remove it safely?
 - What should I fix first?
 
-## v1 Features
+## 1.5 Highlights
 
 - Duplicate dependency detection with lockfile instance tracking
 - Unused dependency detection with runtime vs dev-tool heuristics
@@ -51,6 +54,7 @@ The long-term goal is not just to list problems, but to answer:
 - Markdown output via `--md`
 - SARIF output via `--sarif`
 - Static HTML dashboard via `--dashboard`
+- Upgrade advisor output via `--advise`
 - Ranked top issues via `--top`
 - Baseline mode via `--baseline`
 - Focused analysis via `--focus`
@@ -70,6 +74,7 @@ npx dep-brain analyze
 npx dep-brain analyze --json
 npx dep-brain analyze --md
 npx dep-brain analyze --top
+npx dep-brain analyze --advise
 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
@@ -164,7 +169,9 @@ Suggestions:
 dep-brain analyze --json
 ```
 
-Output includes `outputVersion` for schema stability and can be validated with:
+Output includes `outputVersion` for schema stability. `dep-brain@1.5.1` writes contract version `1.6`.
+
+Validate against:
 
 - `depbrain.output.schema.json`
 
@@ -182,6 +189,14 @@ dep-brain analyze --top
 
 Shows the highest-priority actionable findings first, including confidence and next-step guidance.
 
+## Upgrade Advice Output
+
+```bash
+dep-brain analyze --advise
+```
+
+Shows recommended upgrade targets, stepped major-version paths, and release-note links when available.
+
 ## Dashboard Output
 
 ```bash
@@ -204,6 +219,8 @@ Writes a static HTML dashboard. Default path comes from `dashboard.outputPath`.
 
 Built-in `license` plugin adds license counts under `extensions.license`. Failed plugin loads and hook errors are reported under `extensions.depBrain.plugins`.
 
+Outdated results now include `advice` with `risk`, `recommendedTarget`, `intermediateSteps`, `releaseNotes`, and upgrade signals such as `semver_major`.
+
 ## Report From JSON
 
 ```bash
@@ -371,17 +388,18 @@ src/
 
 ## Product Direction
 
-`dep-brain` is in its `v1.0.0` production-ready CLI stage. The roadmap delivered through v1:
+`dep-brain` is in `v1.5.1` production CLI stage, with current focus on actionable dependency decisions instead of raw issue lists.
+
+Recent releases added:
 
-- `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
+- transitive risk ownership and path tracing
+- dashboard and plugin support
+- baseline, focus, and CI workflows
+- structured upgrade advice with release-note links
 
-The project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
+Project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
 
-Risk findings now include a `trustScore`, structured `riskFactors`, `transitiveRiskScore`, and `riskyTransitiveDeps` path traces so teams can see which direct package introduces supply-chain risk.
+Risk findings include `trustScore`, structured `riskFactors`, `transitiveRiskScore`, and `riskyTransitiveDeps` path traces so teams can see which direct package introduces supply-chain risk.
 
 ## Repository Notes
 

package/depbrain.output.schema.json

@@ -17,6 +17,23 @@
         "reasons": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "outdatedAdvice": {
+      "type": "object",
+      "required": ["risk", "recommendedTarget", "latestEvaluatedVersion", "intermediateSteps", "releaseNotes", "signals", "currentRange"],
+      "additionalProperties": false,
+      "properties": {
+        "risk": { "type": "string", "enum": ["low", "medium", "high"] },
+        "recommendedTarget": { "type": "string" },
+        "latestEvaluatedVersion": { "type": "string" },
+        "intermediateSteps": { "type": "array", "items": { "type": "string" } },
+        "releaseNotes": { "type": "array", "items": { "type": "string" } },
+        "signals": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["semver_major", "breaking_keyword", "missing_changelog"] }
+        },
+        "currentRange": { "type": "string" }
+      }
+    },
     "riskFactors": {
       "type": "object",
       "required": ["daysSincePublish", "downloads", "maintainersCount", "versionCount", "recentReleaseCount", "hasRepository", "dependencyType", "transitiveDependencyCount", "riskyTransitiveCount"],
@@ -154,7 +171,7 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "current", "latest", "updateType", "confidence", "reasonCodes", "explanation", "recommendation"],
+        "required": ["name", "current", "latest", "updateType", "confidence", "reasonCodes", "explanation", "advice", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
@@ -165,6 +182,7 @@
           "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
           "reasonCodes": { "type": "array", "items": { "type": "string" } },
           "explanation": { "type": "array", "items": { "type": "string" } },
+          "advice": { "$ref": "#/properties/outdatedAdvice" },
           "recommendation": { "$ref": "#/properties/recommendation" }
         }
       }

package/dist/checks/outdated.d.ts

@@ -1,8 +1,11 @@
 import type { OutdatedDependency } from "../core/analyzer.js";
 import type { DependencyGraph } from "../core/graph-builder.js";
 import type { CheckResult } from "../core/types.js";
+import { type PackageMetadata } from "../utils/npm-api.js";
 export interface OutdatedOptions {
     resolveLatestVersion?: (name: string) => Promise<string | null>;
+    resolvePackageMetadata?: (name: string) => Promise<PackageMetadata | null>;
+    resolveReleaseNotesText?: (url: string) => Promise<string | null>;
 }
 export declare function findOutdatedDependencies(graph: DependencyGraph, options?: OutdatedOptions): Promise<OutdatedDependency[]>;
-export declare function runOutdatedCheck(graph: DependencyGraph): Promise<CheckResult>;
+export declare function runOutdatedCheck(graph: DependencyGraph, options?: OutdatedOptions): Promise<CheckResult>;

package/dist/checks/outdated.js

@@ -1,32 +1,36 @@
-import { getLatestVersion } from "../utils/npm-api.js";
+import { getLatestVersion, getPackageMetadata } from "../utils/npm-api.js";
 export async function findOutdatedDependencies(graph, options = {}) {
-    const resolveLatestVersion = options.resolveLatestVersion ?? getLatestVersion;
+    const resolveLatestVersion = options.resolveLatestVersion;
+    const resolvePackageMetadata = options.resolvePackageMetadata;
     const combined = {
         ...graph.dependencies,
         ...graph.devDependencies
     };
     const results = await mapWithConcurrency(Object.entries(combined), 8, async ([name, current]) => {
         const normalized = normalizeVersion(current);
-        const latest = await resolveLatestVersion(name);
+        const metadata = resolvePackageMetadata
+            ? await resolvePackageMetadata(name)
+            : resolveLatestVersion
+                ? null
+                : await getPackageMetadata(name);
+        const latest = resolveLatestVersion
+            ? await resolveLatestVersion(name)
+            : metadata?.latestVersion ?? await getLatestVersion(name);
         if (!latest || latest === normalized) {
             return null;
         }
         const updateType = classifyUpdateType(normalized, latest);
+        const advice = await buildAdvice(name, current, normalized, latest, updateType, metadata, options.resolveReleaseNotesText);
         return {
             name,
             current,
             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)
+            confidence: advice.risk === "high" ? 0.98 : 0.97,
+            reasonCodes: buildReasonCodes(updateType, advice),
+            explanation: buildExplanation(updateType, advice),
+            advice,
+            recommendation: buildOutdatedRecommendation(updateType, advice)
         };
     });
     return results
@@ -47,32 +51,43 @@ async function mapWithConcurrency(items, limit, mapper) {
     await Promise.all(workers);
     return results;
 }
-function buildOutdatedRecommendation(updateType) {
+function buildOutdatedRecommendation(updateType, advice) {
     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.",
+        priority: advice.risk === "high"
+            ? "high"
+            : updateType === "major"
+                ? "high"
+                : updateType === "minor"
+                    ? "medium"
+                    : "low",
+        safety: advice.risk === "high"
+            ? "unknown"
+            : updateType === "patch"
+                ? "safe"
+                : updateType === "minor"
+                    ? "caution"
+                    : "unknown",
+        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: [
-            "A newer published version is available in the registry."
+            `Latest registry version is ${advice.latestEvaluatedVersion}.`,
+            ...advice.signals.map((signal) => formatAdviceSignal(signal))
         ]
     };
 }
-export async function runOutdatedCheck(graph) {
-    const outdated = await findOutdatedDependencies(graph);
+export async function runOutdatedCheck(graph, options = {}) {
+    const outdated = await findOutdatedDependencies(graph, options);
     return {
         name: "outdated",
         summary: `${outdated.length} outdated dependencies found`,
         issues: outdated.map((item) => ({
             id: `outdated:${item.name}`,
             message: `${item.name} ${item.current} -> ${item.latest}`,
-            severity: item.updateType === "major" ? "critical" : "warning",
+            severity: item.advice.risk === "high" || item.updateType === "major" ? "critical" : "warning",
             confidence: item.confidence,
             reasonCodes: item.reasonCodes,
             explanation: item.explanation,
@@ -80,11 +95,90 @@ export async function runOutdatedCheck(graph) {
                 name: item.name,
                 current: item.current,
                 latest: item.latest,
-                updateType: item.updateType
+                updateType: item.updateType,
+                advice: item.advice
             }
         }))
     };
 }
+async function buildAdvice(name, currentRange, normalizedCurrent, latest, updateType, metadata, resolveReleaseNotesText) {
+    const versions = (metadata?.versions ?? []).filter((version) => parseVersion(version) !== null);
+    const repositoryUrl = normalizeRepositoryUrl(metadata?.repository ?? null);
+    const releaseNotes = buildReleaseNoteUrls(repositoryUrl, latest, versions);
+    const currentParsed = parseVersion(normalizedCurrent);
+    const latestParsed = parseVersion(latest);
+    const signals = [];
+    let recommendedTarget = latest;
+    let intermediateSteps = [];
+    if (updateType === "major" && currentParsed && latestParsed) {
+        const stableTarget = findHighestVersionInMajor(versions, currentParsed[0]);
+        if (stableTarget && stableTarget !== normalizedCurrent && stableTarget !== latest) {
+            recommendedTarget = stableTarget;
+            intermediateSteps = [stableTarget, latest];
+            signals.push("semver_major");
+        }
+        else {
+            intermediateSteps = [latest];
+            signals.push("semver_major");
+        }
+    }
+    else if (updateType !== "unknown") {
+        intermediateSteps = [latest];
+    }
+    let hasBreakingKeyword = false;
+    if (resolveReleaseNotesText && releaseNotes.length > 0) {
+        const notesText = await resolveReleaseNotesText(releaseNotes[0]);
+        if (notesText && /\bBREAKING\b/i.test(notesText)) {
+            hasBreakingKeyword = true;
+            signals.push("breaking_keyword");
+        }
+    }
+    if (releaseNotes.length === 0) {
+        signals.push("missing_changelog");
+    }
+    const risk = hasBreakingKeyword || updateType === "major"
+        ? "high"
+        : updateType === "minor"
+            ? "medium"
+            : "low";
+    return {
+        risk,
+        recommendedTarget,
+        latestEvaluatedVersion: latest,
+        intermediateSteps: intermediateSteps.length > 0 ? intermediateSteps : [latest],
+        releaseNotes,
+        signals: dedupeSignals(signals),
+        currentRange
+    };
+}
+function buildReasonCodes(updateType, advice) {
+    const codes = [
+        "latest_registry_version_newer",
+        `update_type_${updateType}`,
+        `advice_risk_${advice.risk}`
+    ];
+    for (const signal of advice.signals) {
+        codes.push(`advice_signal_${signal}`);
+    }
+    return codes;
+}
+function buildExplanation(updateType, advice) {
+    const explanation = [
+        "The npm registry reports a newer published version than the one declared in this project.",
+        `The change is classified as a ${updateType} update.`,
+        `Recommended target is ${advice.recommendedTarget}.`
+    ];
+    if (advice.intermediateSteps.length > 1) {
+        explanation.push(`Suggested upgrade path: ${advice.intermediateSteps.join(" -> ")}.`);
+    }
+    if (advice.releaseNotes.length > 0) {
+        explanation.push(`Release notes available at ${advice.releaseNotes[0]}.`);
+    }
+    for (const signal of advice.signals) {
+        explanation.push(formatAdviceSignal(signal));
+    }
+    return explanation;
+}
 function normalizeVersion(versionRange) {
     return versionRange.trim().replace(/^[~^><=\s]+/, "");
 }
@@ -112,3 +206,61 @@ function parseVersion(version) {
     }
     return [Number(match[1]), Number(match[2]), Number(match[3])];
 }
+function normalizeRepositoryUrl(value) {
+    if (!value) {
+        return null;
+    }
+    return value
+        .replace(/^git\+/, "")
+        .replace(/^git:\/\/github\.com\//, "https://github.com/")
+        .replace(/^git@github\.com:/, "https://github.com/")
+        .replace(/\.git$/, "");
+}
+function buildReleaseNoteUrls(repositoryUrl, latestVersion, versions) {
+    if (!repositoryUrl) {
+        return [];
+    }
+    const urls = [];
+    if (/github\.com\//.test(repositoryUrl)) {
+        urls.push(`${repositoryUrl}/releases/tag/v${latestVersion}`);
+        urls.push(`${repositoryUrl}/releases`);
+    }
+    else {
+        urls.push(repositoryUrl);
+    }
+    if (versions.length === 0 && urls.length === 0) {
+        return [];
+    }
+    return Array.from(new Set(urls));
+}
+function findHighestVersionInMajor(versions, major) {
+    const matching = versions
+        .map((version) => ({ version, parsed: parseVersion(version) }))
+        .filter((entry) => entry.parsed !== null && entry.parsed[0] === major)
+        .sort((left, right) => compareParsedVersions(right.parsed, left.parsed));
+    return matching[0]?.version ?? null;
+}
+function compareParsedVersions(left, right) {
+    if (left[0] !== right[0]) {
+        return left[0] - right[0];
+    }
+    if (left[1] !== right[1]) {
+        return left[1] - right[1];
+    }
+    return left[2] - right[2];
+}
+function dedupeSignals(values) {
+    return Array.from(new Set(values));
+}
+function formatAdviceSignal(signal) {
+    switch (signal) {
+        case "semver_major":
+            return "Major version gap detected.";
+        case "breaking_keyword":
+            return "Release notes include BREAKING markers.";
+        case "missing_changelog":
+            return "Release notes were not discovered automatically.";
+        default:
+            return signal;
+    }
+}

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

@@ -83,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[];
@@ -144,7 +154,7 @@ export interface PackageAnalysisResult {
     topIssues: TopIssue[];
     extensions: Record<string, unknown>;
 }
-export declare const OUTPUT_VERSION = "1.5";
+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.5";
+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)
     }));
 }
@@ -443,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)
     };
 }
@@ -660,6 +672,45 @@ function normalizeRiskTransitiveDependencies(value) {
     })
         .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) {
     if (!Array.isArray(value)) {
         return [];

package/dist/reporters/console.js

@@ -28,8 +28,8 @@ export function renderConsoleReport(result) {
         ? `${item.name} (${item.section}) [${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}]`, item.confidence, item.explanation, item.recommendation)));
+        ? `${item.name}: ${item.current} -> ${item.latest} [${item.updateType}] [${item.package}]${formatOutdatedAdviceSuffix(item)}`
+        : `${item.name}: ${item.current} -> ${item.latest} [${item.updateType}]${formatOutdatedAdviceSuffix(item)}`, item.confidence, item.explanation, item.recommendation)));
     appendSection(lines, "Risky dependencies", result.risks.map((item) => formatEntry(item.package
         ? `${item.name}: ${item.reasons.join("; ")} [${item.package}] [trust ${item.trustScore.toUpperCase()}]${formatTransitiveRiskSuffix(item)}`
         : `${item.name}: ${item.reasons.join("; ")} [trust ${item.trustScore.toUpperCase()}]${formatTransitiveRiskSuffix(item)}`, item.confidence, item.explanation, item.recommendation)));
@@ -71,3 +71,12 @@ function formatEntry(label, confidence, explanation, recommendation) {
         : "";
     return `${label} | confidence ${Math.round(confidence * 100)}%${recommendationSummary}${reasonSummary}`;
 }
+function formatOutdatedAdviceSuffix(item) {
+    if (!item.advice.recommendedTarget) {
+        return "";
+    }
+    const steps = item.advice.intermediateSteps.length > 1
+        ? ` steps ${item.advice.intermediateSteps.join(" -> ")}`
+        : "";
+    return ` [advice ${item.advice.risk.toUpperCase()} target ${item.advice.recommendedTarget}${steps}]`;
+}

package/dist/reporters/dashboard.js

@@ -6,6 +6,12 @@ export function renderDashboardReport(result) {
         .sort((left, right) => right.transitiveRiskScore - left.transitiveRiskScore)
         .map(renderTransitiveHotspot)
         .join("");
+    const upgradeAdvice = result.outdated
+        .filter((item) => item.advice.risk !== "low" || item.updateType === "major")
+        .sort((left, right) => compareAdviceRisk(right.advice.risk, left.advice.risk) ||
+        left.name.localeCompare(right.name))
+        .map(renderUpgradeAdvice)
+        .join("");
     return [
         "<!doctype html>",
         '<html lang="en">',
@@ -77,6 +83,12 @@ export function renderDashboardReport(result) {
         "</div>",
         "</section>",
         '<section class="panel">',
+        "<h2>Upgrade Priorities</h2>",
+        upgradeAdvice.length > 0
+            ? `<ul>${upgradeAdvice}</ul>`
+            : '<p class="muted">No high-risk upgrades found.</p>',
+        "</section>",
+        '<section class="panel">',
         "<h2>Transitive Risk Hotspots</h2>",
         transitiveHotspots.length > 0
             ? transitiveHotspots
@@ -113,6 +125,24 @@ function renderTransitiveHotspot(item) {
         "</div>"
     ].join("");
 }
+function renderUpgradeAdvice(item) {
+    return [
+        "<li>",
+        `<strong>${escapeHtml(item.name)}</strong> <span class="muted">[${escapeHtml(item.advice.risk.toUpperCase())}]</span>`,
+        `<div>${escapeHtml(item.current)} -> ${escapeHtml(item.latest)} | target ${escapeHtml(item.advice.recommendedTarget)}</div>`,
+        item.advice.intermediateSteps.length > 1
+            ? `<div class="path">${escapeHtml(item.advice.intermediateSteps.join(" -> "))}</div>`
+            : "",
+        item.advice.releaseNotes[0]
+            ? `<div class="muted">${escapeHtml(item.advice.releaseNotes[0])}</div>`
+            : "",
+        "</li>"
+    ].join("");
+}
+function compareAdviceRisk(left, right) {
+    const rank = { high: 3, medium: 2, low: 1 };
+    return rank[left] - rank[right];
+}
 function escapeHtml(value) {
     return value
         .replace(/&/g, "&amp;")

package/dist/reporters/markdown.js

@@ -32,8 +32,8 @@ export function renderMarkdownReport(result) {
         ? `${item.name} (${item.section}) [${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}]`, item.confidence, item.explanation, item.recommendation)));
+        ? `${item.name}: ${item.current} -> ${item.latest} [${item.updateType}] [${item.package}]${formatOutdatedAdviceSuffix(item)}`
+        : `${item.name}: ${item.current} -> ${item.latest} [${item.updateType}]${formatOutdatedAdviceSuffix(item)}`, item.confidence, item.explanation, item.recommendation)));
     appendSection(lines, "Risky dependencies", result.risks.map((item) => formatEntry(item.package
         ? `${item.name}: ${item.reasons.join("; ")} [${item.package}] [trust ${item.trustScore.toUpperCase()}]${formatTransitiveRiskSuffix(item)}`
         : `${item.name}: ${item.reasons.join("; ")} [trust ${item.trustScore.toUpperCase()}]${formatTransitiveRiskSuffix(item)}`, item.confidence, item.explanation, item.recommendation)));
@@ -71,3 +71,12 @@ function formatEntry(label, confidence, explanation, recommendation) {
         : "";
     return `${label} | confidence ${Math.round(confidence * 100)}%${recommendationSummary}${reasonSummary}`;
 }
+function formatOutdatedAdviceSuffix(item) {
+    if (!item.advice.recommendedTarget) {
+        return "";
+    }
+    const steps = item.advice.intermediateSteps.length > 1
+        ? ` steps ${item.advice.intermediateSteps.join(" -> ")}`
+        : "";
+    return ` [advice ${item.advice.risk.toUpperCase()} target ${item.advice.recommendedTarget}${steps}]`;
+}

package/dist/utils/npm-api.d.ts

@@ -1,11 +1,13 @@
 export interface PackageMetadata {
     latestVersion: string | null;
     repository: string | null;
+    homepage: string | null;
     downloads: number | null;
     daysSincePublish: number | null;
     maintainersCount: number | null;
     versionCount: number | null;
     recentReleaseCount: number | null;
+    versions: string[];
 }
 export declare function getLatestVersion(name: string): Promise<string | null>;
 export declare function getPackageMetadata(name: string): Promise<PackageMetadata | null>;

package/dist/utils/npm-api.js

@@ -49,11 +49,13 @@ async function fetchPackageMetadata(name) {
         return {
             latestVersion,
             repository,
+            homepage: typeof packageJson.homepage === "string" ? packageJson.homepage : null,
             downloads: downloadsJson.downloads ?? null,
             daysSincePublish,
             maintainersCount,
             versionCount,
-            recentReleaseCount
+            recentReleaseCount,
+            versions: Object.keys(packageJson.versions ?? {})
         };
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dep-brain",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "CLI and library for explainable dependency intelligence",
   "type": "module",
   "main": "dist/index.js",