dep-brain 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.8.0
+
+- Added `dep-brain fix --unused --dry-run` for safe unused dependency removal previews.
+- Added package-manager command rendering for npm, pnpm, and yarn.
+- Added `--include-caution` to include caution-level unused dependency removals.
+- Added JSON output for fix plans with commands, included items, and skipped items.
+- Kept analysis output contract at `1.6` because no analysis JSON result fields changed.
+
 ## 1.7.0
 
 - Added idempotent GitHub PR comments with `--pr-comment`.

package/README.md

@@ -6,7 +6,7 @@
 
 `dep-brain` is a CLI and library for explainable dependency intelligence in JavaScript and TypeScript projects.
 
-Current release `1.7.0` adds idempotent GitHub PR comments while keeping analysis output contract `1.6`.
+Current release `1.8.0` adds unused dependency fix-plan dry runs while keeping analysis output contract `1.6`.
 
 ## Vision
 
@@ -30,6 +30,7 @@ Current release `1.7.0` adds idempotent GitHub PR comments while keeping analysi
 - Output upgrade-advice reports via `--advise`
 - Send Slack and Discord webhook summaries for CI runs
 - Create or update GitHub PR comments for pull request checks
+- Preview safe unused dependency removal commands
 - Gate CI with score and finding policies
 - Compare new findings against a baseline report
 
@@ -39,7 +40,7 @@ The long-term goal is not just to list problems, but to answer:
 - Can I remove it safely?
 - What should I fix first?
 
-## 1.7 Highlights
+## 1.8 Highlights
 
 - Duplicate dependency detection with lockfile instance tracking
 - Unused dependency detection with runtime vs dev-tool heuristics
@@ -59,6 +60,7 @@ The long-term goal is not just to list problems, but to answer:
 - Upgrade advisor output via `--advise`
 - Slack and Discord notification summaries via `--notify`
 - GitHub PR comments via `--pr-comment`
+- Safe unused dependency fix plans via `dep-brain fix --unused --dry-run`
 - Ranked top issues via `--top`
 - Baseline mode via `--baseline`
 - Focused analysis via `--focus`
@@ -92,6 +94,9 @@ npx dep-brain analyze --notify
 npx dep-brain analyze --notify --notify-on always
 npx dep-brain analyze --pr-comment
 npx dep-brain analyze --pr-comment --comment-on new-findings
+npx dep-brain fix --unused --dry-run
+npx dep-brain fix --unused --dry-run --include-caution
+npx dep-brain fix --unused --dry-run --json
 npx dep-brain analyze --focus duplicates
 npx dep-brain analyze --ci
 npx dep-brain analyze --baseline depbrain-baseline.json
@@ -177,7 +182,7 @@ Suggestions:
 dep-brain analyze --json
 ```
 
-Output includes `outputVersion` for schema stability. `dep-brain@1.7.0` writes contract version `1.6`.
+Output includes `outputVersion` for schema stability. `dep-brain@1.8.0` writes contract version `1.6`.
 
 Validate against:
 
@@ -232,6 +237,16 @@ dep-brain analyze --ci --baseline depbrain-baseline.json --pr-comment --comment-
 
 `--pr-comment` creates or updates one GitHub pull request comment using `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, and `GITHUB_EVENT_PATH`. The comment includes policy status, health score, top issues, upgrade priorities, and baseline delta counts when `--baseline` is used.
 
+## Fix Plans
+
+```bash
+dep-brain fix --unused --dry-run
+dep-brain fix --unused --dry-run --include-caution
+dep-brain fix --unused --dry-run --json
+```
+
+Fix plans print package-manager-specific uninstall commands without changing files. `dep-brain` detects npm, pnpm, or yarn lockfiles and skips caution-level removals unless `--include-caution` is set.
+
 ## Plugins
 
 ```json
@@ -420,7 +435,7 @@ src/
 
 ## Product Direction
 
-`dep-brain` is in `v1.7.0` production CLI stage, with current focus on actionable dependency decisions and PR workflow integration.
+`dep-brain` is in `v1.8.0` production CLI stage, with current focus on safe dependency removal previews and PR workflow integration.
 
 Recent releases added:
 
@@ -430,6 +445,7 @@ Recent releases added:
 - structured upgrade advice with release-note links
 - Slack and Discord notification summaries
 - idempotent GitHub PR comments
+- unused dependency fix-plan dry runs
 
 Project should optimize for trust, clarity, and actionability over flashy UI, generic graphs, or simply adding more checks.
 

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { analyzeProject } from "./core/analyzer.js";
+import { buildUnusedFixPlan, renderFixPlan } from "./core/fix-plan.js";
 import { renderConsoleReport } from "./reporters/console.js";
 import { renderJsonReport } from "./reporters/json.js";
 import { renderMarkdownReport } from "./reporters/markdown.js";
@@ -45,6 +46,44 @@ async function main() {
         return;
     }
     if (command !== "analyze") {
+        if (command === "fix") {
+            if (!flags.has("--unused")) {
+                console.error("Missing --unused for fix");
+                printHelp();
+                process.exitCode = 1;
+                return;
+            }
+            if (!flags.has("--dry-run")) {
+                console.error("Fix currently supports --dry-run only.");
+                process.exitCode = 1;
+                return;
+            }
+            if (!(await hasPackageJson(targetPath))) {
+                console.error(`No package.json found at ${sanitizeForLog(targetPath)}`);
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const cliConfig = buildCliConfig(flags, optionValues);
+                const result = await analyzeProject({
+                    rootDir: targetPath,
+                    configPath: optionValues.get("--config"),
+                    config: cliConfig,
+                    focus: "unused"
+                });
+                const plan = await buildUnusedFixPlan(result, {
+                    includeCaution: flags.has("--include-caution")
+                });
+                await writeOutput(flags.has("--json") ? JSON.stringify(plan, null, 2) : renderFixPlan(plan), optionValues.get("--out"));
+                return;
+            }
+            catch (error) {
+                console.error("Failed to build fix plan.");
+                console.error(error);
+                process.exitCode = 1;
+                return;
+            }
+        }
         if (command === "report") {
             const fromPath = optionValues.get("--from") ?? positionals[0];
             if (!fromPath) {
@@ -272,6 +311,7 @@ function printHelp() {
     console.log("Usage:");
     console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--dashboard] [--notify] [--pr-comment] [--comment-on kind] [--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] [--advise] [--dashboard] [--out path]");
+    console.log("  dep-brain fix [path] --unused --dry-run [--include-caution] [--json] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain init [--out depbrain.config.json]");
     console.log("  dep-brain help");
@@ -295,6 +335,9 @@ function printHelp() {
     console.log("  --baseline <path>   Ignore findings already present in a baseline JSON report");
     console.log("  --from <file>       Read analysis JSON from file");
     console.log("  --out <path>        Write output to a file");
+    console.log("  --unused            Build an unused dependency fix plan");
+    console.log("  --dry-run           Print fix commands without changing files");
+    console.log("  --include-caution   Include caution-level unused dependency removals");
     console.log("  --min-score <n>     Minimum score required to pass");
     console.log("  --fail-on-risks     Fail when risky dependencies exist");
     console.log("  --fail-on-outdated  Fail when outdated dependencies exist");

package/dist/core/fix-plan.d.ts

@@ -0,0 +1,32 @@
+import type { AnalysisResult } from "./analyzer.js";
+export type PackageManager = "npm" | "pnpm" | "yarn";
+export interface FixPlanOptions {
+    includeCaution?: boolean;
+}
+export interface FixPlanItem {
+    name: string;
+    section: "dependencies" | "devDependencies";
+    package?: string;
+    confidence: number;
+    safety: "safe" | "caution" | "unknown";
+    command: string;
+    args: string[];
+}
+export interface SkippedFixItem {
+    name: string;
+    section: "dependencies" | "devDependencies";
+    package?: string;
+    confidence: number;
+    safety: "safe" | "caution" | "unknown";
+    reason: string;
+}
+export interface FixPlan {
+    packageManager: PackageManager;
+    dryRun: true;
+    commands: string[];
+    items: FixPlanItem[];
+    skipped: SkippedFixItem[];
+}
+export declare function buildUnusedFixPlan(result: AnalysisResult, options?: FixPlanOptions): Promise<FixPlan>;
+export declare function detectPackageManager(rootDir: string): Promise<PackageManager>;
+export declare function renderFixPlan(plan: FixPlan): string;

package/dist/core/fix-plan.js

@@ -0,0 +1,109 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export async function buildUnusedFixPlan(result, options = {}) {
+    const packageManager = await detectPackageManager(result.rootDir);
+    const items = [];
+    const skipped = [];
+    for (const item of result.unused) {
+        const skipReason = getSkipReason(item, options);
+        if (skipReason) {
+            skipped.push({
+                name: item.name,
+                section: item.section,
+                package: item.package,
+                confidence: item.confidence,
+                safety: item.recommendation.safety,
+                reason: skipReason
+            });
+            continue;
+        }
+        const command = buildRemoveCommand(packageManager, item);
+        items.push({
+            name: item.name,
+            section: item.section,
+            package: item.package,
+            confidence: item.confidence,
+            safety: item.recommendation.safety,
+            command: command.join(" "),
+            args: command
+        });
+    }
+    return {
+        packageManager,
+        dryRun: true,
+        commands: items.map((item) => item.command),
+        items,
+        skipped
+    };
+}
+export async function detectPackageManager(rootDir) {
+    if (await fileExists(path.join(rootDir, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (await fileExists(path.join(rootDir, "yarn.lock"))) {
+        return "yarn";
+    }
+    return "npm";
+}
+export function renderFixPlan(plan) {
+    const lines = [
+        "Dependency Brain Fix Plan",
+        "",
+        `Package manager: ${plan.packageManager}`,
+        "Mode: dry-run",
+        ""
+    ];
+    if (plan.commands.length === 0) {
+        lines.push("No safe unused dependency removals found.");
+    }
+    else {
+        lines.push("Commands:");
+        for (const command of plan.commands) {
+            lines.push(`- ${command}`);
+        }
+    }
+    if (plan.skipped.length > 0) {
+        lines.push("");
+        lines.push("Skipped:");
+        for (const item of plan.skipped) {
+            lines.push(`- ${item.name}${item.package ? ` [${item.package}]` : ""}: ${item.reason}`);
+        }
+    }
+    return lines.join("\n");
+}
+function getSkipReason(item, options) {
+    if (item.recommendation.safety !== "safe" &&
+        !(options.includeCaution && item.recommendation.safety === "caution")) {
+        return "requires --include-caution";
+    }
+    if (item.section === "dependencies" &&
+        item.confidence < 0.88 &&
+        !options.includeCaution) {
+        return "runtime dependency confidence below 88%";
+    }
+    return null;
+}
+function buildRemoveCommand(packageManager, item) {
+    if (packageManager === "pnpm") {
+        return item.package
+            ? ["pnpm", "--filter", item.package, "remove", item.name]
+            : ["pnpm", "remove", item.name];
+    }
+    if (packageManager === "yarn") {
+        return item.package
+            ? ["yarn", "workspace", item.package, "remove", item.name]
+            : ["yarn", "remove", item.name];
+    }
+    return item.package
+        ? ["npm", "uninstall", item.name, "--workspace", item.package]
+        : ["npm", "uninstall", item.name];
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { analyzeProject } from "./core/analyzer.js";
+export { buildUnusedFixPlan, detectPackageManager, renderFixPlan } from "./core/fix-plan.js";
 export type { AnalysisOptions, AnalysisFocus, AnalysisResult, DepBrainBaseline, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, Recommendation, RiskFactors, RiskTransitiveDependency, ScoreBreakdown, RiskDependency, TopIssue, TrustScore, UnusedDependency, WorkspaceDependencyUsage, WorkspaceOwnershipSummary } from "./core/analyzer.js";
 export { OUTPUT_VERSION } from "./core/analyzer.js";
 export { PluginManager } from "./core/plugin-manager.js";
 export type { DepBrainPlugin, PluginDiagnostic, ProjectContext } from "./core/plugin-manager.js";
 export type { AnalysisContext, CheckResult, Issue } from "./core/types.js";
+export type { FixPlan, FixPlanItem, FixPlanOptions, PackageManager, SkippedFixItem } from "./core/fix-plan.js";
 export type { DepBrainConfig, DepBrainConfigOverrides } from "./utils/config.js";
 export { renderNotificationMessage, sendConfiguredNotifications, shouldSendNotification } from "./utils/notifications.js";
 export { shouldPostPrComment, upsertGitHubPrComment } from "./utils/github.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { analyzeProject } from "./core/analyzer.js";
+export { buildUnusedFixPlan, detectPackageManager, renderFixPlan } from "./core/fix-plan.js";
 export { OUTPUT_VERSION } from "./core/analyzer.js";
 export { PluginManager } from "./core/plugin-manager.js";
 export { renderNotificationMessage, sendConfiguredNotifications, shouldSendNotification } from "./utils/notifications.js";

package/package.json

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