dep-brain 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
+- Changed risk analysis from direct-package-only output to direct-owner risk summaries with `transitiveRiskScore` and `riskyTransitiveDeps`.
+- Added transitive dependency counts and risky transitive counts to `riskFactors`.
+- Updated console, markdown, and dashboard reports to highlight transitive risk hotspots.
+- Bumped analysis output contract to `1.5` and added regression coverage for transitive risk propagation.
+
 ## 1.3.0
 
 - Added plugin diagnostics under `extensions.depBrain.plugins` for failed plugin loads and hook errors.

package/README.md

@@ -21,9 +21,11 @@
 - Detect likely unused dependencies from source imports and scripts
 - Detect outdated packages
 - Highlight dependency risk signals
+- Show which direct dependency introduces risky transitive packages
 - 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
 
@@ -39,6 +41,7 @@ The long-term goal is not just to list problems, but to answer:
 - Unused dependency detection with runtime vs dev-tool heuristics
 - Outdated dependency reporting with `major`, `minor`, and `patch` classification
 - Risk analysis based on npm package metadata
+- Transitive risk ownership and path tracing for direct dependencies
 - Confidence scores, reason codes, explanations, and recommendations for findings
 - Config loading from `depbrain.config.json`
 - Ignore rules for noisy dependencies and checks
@@ -49,6 +52,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`
@@ -68,6 +72,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
@@ -180,6 +185,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
@@ -202,6 +215,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
@@ -379,7 +394,7 @@ src/
 
 The project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
 
-Risk findings now include a `trustScore` plus structured `riskFactors` such as publish recency, maintainer count, and repository presence.
+Risk findings now include a `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,9 +17,26 @@
         "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"],
+      "required": ["daysSincePublish", "downloads", "maintainersCount", "versionCount", "recentReleaseCount", "hasRepository", "dependencyType", "transitiveDependencyCount", "riskyTransitiveCount"],
       "additionalProperties": false,
       "properties": {
         "daysSincePublish": { "type": ["number", "null"] },
@@ -28,7 +45,21 @@
         "versionCount": { "type": ["number", "null"] },
         "recentReleaseCount": { "type": ["number", "null"] },
         "hasRepository": { "type": "boolean" },
-        "dependencyType": { "type": "string", "enum": ["dependencies", "devDependencies", "unknown"] }
+        "dependencyType": { "type": "string", "enum": ["dependencies", "devDependencies", "unknown"] },
+        "transitiveDependencyCount": { "type": "number" },
+        "riskyTransitiveCount": { "type": "number" }
+      }
+    },
+    "riskTransitiveDependency": {
+      "type": "object",
+      "required": ["name", "trustScore", "confidence", "reasons", "introducedByPaths"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "trustScore": { "type": "string", "enum": ["high", "medium", "low"] },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "reasons": { "type": "array", "items": { "type": "string" } },
+        "introducedByPaths": { "type": "array", "items": { "type": "string" } }
       }
     },
     "ownershipSummary": {
@@ -140,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" },
@@ -151,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" }
         }
       }
@@ -159,7 +191,7 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "reasons", "confidence", "reasonCodes", "explanation", "trustScore", "riskFactors", "recommendation"],
+        "required": ["name", "reasons", "confidence", "reasonCodes", "explanation", "trustScore", "riskFactors", "transitiveRiskScore", "riskyTransitiveDeps", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
@@ -170,6 +202,11 @@
           "explanation": { "type": "array", "items": { "type": "string" } },
           "trustScore": { "type": "string", "enum": ["high", "medium", "low"] },
           "riskFactors": { "$ref": "#/properties/riskFactors" },
+          "transitiveRiskScore": { "type": "number" },
+          "riskyTransitiveDeps": {
+            "type": "array",
+            "items": { "$ref": "#/properties/riskTransitiveDependency" }
+          },
           "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;
+    }
+}