dep-brain 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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`.
+- Added `--comment-on` trigger support for `always`, `failure`, and `new-findings`.
+- Added PR comment markdown renderer with top issues, policy reasons, upgrade priorities, and baseline delta counts.
+- Added GitHub Action inputs for PR comment runs.
+- Kept analysis output contract at `1.6` because no JSON result fields changed.
+
 ## 1.6.0
 
 - Added Slack and Discord webhook notification summaries.

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.6.0` adds Slack and Discord notification summaries 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
 
@@ -29,6 +29,8 @@ Current release `1.6.0` adds Slack and Discord notification summaries while keep
 - Output reports in console, JSON, Markdown, SARIF, dashboard, and top-issues formats
 - 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
 
@@ -38,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.6 Highlights
+## 1.8 Highlights
 
 - Duplicate dependency detection with lockfile instance tracking
 - Unused dependency detection with runtime vs dev-tool heuristics
@@ -57,6 +59,8 @@ The long-term goal is not just to list problems, but to answer:
 - Static HTML dashboard via `--dashboard`
 - 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`
@@ -88,6 +92,11 @@ npx dep-brain analyze --dashboard
 npx dep-brain analyze --dashboard --dashboard-out reports/depbrain.html
 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
@@ -173,7 +182,7 @@ Suggestions:
 dep-brain analyze --json
 ```
 
-Output includes `outputVersion` for schema stability. `dep-brain@1.6.0` writes contract version `1.6`.
+Output includes `outputVersion` for schema stability. `dep-brain@1.8.0` writes contract version `1.6`.
 
 Validate against:
 
@@ -219,6 +228,25 @@ DEPBRAIN_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... dep-brain anal
 
 `--notify` sends compact summaries to configured Slack and Discord webhook URLs. Default trigger is `failure`, so passing runs stay quiet unless `--notify-on always` is set.
 
+## PR Comments
+
+```bash
+dep-brain analyze --ci --pr-comment
+dep-brain analyze --ci --baseline depbrain-baseline.json --pr-comment --comment-on new-findings
+```
+
+`--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
@@ -360,6 +388,7 @@ dep-brain analyze --min-score 85 --fail-on-risks
 dep-brain analyze --config depbrain.config.json
 dep-brain analyze --baseline depbrain-baseline.json --fail-on-unused
 dep-brain analyze --ci --notify
+dep-brain analyze --ci --pr-comment
 ```
 
 ## Config Debugging
@@ -406,7 +435,7 @@ src/
 
 ## Product Direction
 
-`dep-brain` is in `v1.6.0` production CLI stage, with current focus on actionable dependency decisions and CI 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:
 
@@ -415,6 +444,8 @@ Recent releases added:
 - baseline, focus, and CI workflows
 - 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/action.yml

@@ -59,6 +59,18 @@ inputs:
     description: Notification trigger. Use always, failure, or never.
     required: false
     default: "failure"
+  pr-comment:
+    description: Create or update a GitHub PR comment.
+    required: false
+    default: "false"
+  comment-on:
+    description: PR comment trigger. Use always, failure, or new-findings.
+    required: false
+    default: "failure"
+  github-token:
+    description: GitHub token for PR comments.
+    required: false
+    default: ""
 
 runs:
   using: composite
@@ -80,6 +92,9 @@ runs:
         INPUT_FAIL_ON_RISKS: ${{ inputs.fail-on-risks }}
         INPUT_NOTIFY: ${{ inputs.notify }}
         INPUT_NOTIFY_ON: ${{ inputs.notify-on }}
+        INPUT_PR_COMMENT: ${{ inputs.pr-comment }}
+        INPUT_COMMENT_ON: ${{ inputs.comment-on }}
+        GITHUB_TOKEN: ${{ inputs.github-token || github.token }}
       run: |
         set -euo pipefail
 
@@ -141,6 +156,10 @@ runs:
           args+=("--notify" "--notify-on" "$INPUT_NOTIFY_ON")
         fi
 
+        if [ "$INPUT_PR_COMMENT" = "true" ]; then
+          args+=("--pr-comment" "--comment-on" "$INPUT_COMMENT_ON")
+        fi
+
         node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
 
 branding:

package/dist/cli.js

@@ -1,10 +1,13 @@
 #!/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";
+import { renderPrCommentReport } from "./reporters/pr-comment.js";
 import { renderSarifReport } from "./reporters/sarif.js";
 import { renderDashboardReport } from "./reporters/dashboard.js";
+import { shouldPostPrComment, upsertGitHubPrComment } from "./utils/github.js";
 import { sendConfiguredNotifications } from "./utils/notifications.js";
 import { defaultConfig } from "./utils/config.js";
 import { promises as fs } from "node:fs";
@@ -43,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) {
@@ -175,6 +216,28 @@ async function main() {
                 }
             }
         }
+        if (flags.has("--pr-comment")) {
+            const trigger = parsePrCommentTrigger(optionValues.get("--comment-on"));
+            const newFindingsCount = countFindings(result);
+            if (shouldPostPrComment({
+                trigger,
+                policyPassed: result.policy.passed,
+                newFindingsCount
+            })) {
+                const commentResult = await upsertGitHubPrComment({
+                    body: renderPrCommentReport(result, { hasBaseline: Boolean(baseline) })
+                });
+                if (commentResult.status === "created" || commentResult.status === "updated") {
+                    console.error(`PR comment ${commentResult.status}.`);
+                }
+                else {
+                    console.error(`PR comment skipped: ${commentResult.reason ?? "unknown reason"}`);
+                }
+            }
+            else {
+                console.error(`PR comment skipped: ${trigger} trigger did not match.`);
+            }
+        }
         if (!result.policy.passed) {
             process.exitCode = 1;
         }
@@ -246,8 +309,9 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--dashboard] [--notify] [--notify-on kind] [--focus kind] [--ci] [--out path] [--config path] [--baseline path] [--min-score n] [--fail-on-risks]");
+    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");
@@ -263,12 +327,17 @@ function printHelp() {
     console.log("  --dashboard-out <path> Write dashboard HTML to a custom path");
     console.log("  --notify            Send Slack or Discord webhook summaries");
     console.log("  --notify-on <kind>  Send notifications on always, failure, or never");
+    console.log("  --pr-comment        Create or update a GitHub PR comment");
+    console.log("  --comment-on <kind> Post PR comment on always, failure, or new-findings");
     console.log("  --focus <kind>      Run all, health, duplicates, unused, outdated, or risks");
     console.log("  --ci                Apply low-noise CI defaults");
     console.log("  --config <path>     Path to depbrain.config.json");
     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");
@@ -396,3 +465,15 @@ function compareAdviceRisk(left, right) {
     const rank = { high: 3, medium: 2, low: 1 };
     return rank[left] - rank[right];
 }
+function parsePrCommentTrigger(value) {
+    if (value === "always" || value === "failure" || value === "new-findings") {
+        return value;
+    }
+    return "failure";
+}
+function countFindings(result) {
+    return (result.duplicates.length +
+        result.unused.length +
+        result.outdated.length +
+        result.risks.length);
+}

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,10 +1,15 @@
 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";
+export { PR_COMMENT_MARKER, renderPrCommentReport } from "./reporters/pr-comment.js";
 export type { NotificationChannel, NotificationResult, NotificationSendInput, NotificationSender } from "./utils/notifications.js";
+export type { GitHubPrCommentInput, GitHubPrCommentResult, GitHubRequest, PrCommentTrigger } from "./utils/github.js";
 export type { WorkspacePackage } from "./utils/workspaces.js";

package/dist/index.js

@@ -1,4 +1,7 @@
 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";
+export { shouldPostPrComment, upsertGitHubPrComment } from "./utils/github.js";
+export { PR_COMMENT_MARKER, renderPrCommentReport } from "./reporters/pr-comment.js";

package/dist/reporters/pr-comment.d.ts

@@ -0,0 +1,6 @@
+import type { AnalysisResult } from "../core/analyzer.js";
+export declare const PR_COMMENT_MARKER = "<!-- dep-brain-report -->";
+export interface PrCommentOptions {
+    hasBaseline?: boolean;
+}
+export declare function renderPrCommentReport(result: AnalysisResult, options?: PrCommentOptions): string;

package/dist/reporters/pr-comment.js

@@ -0,0 +1,46 @@
+export const PR_COMMENT_MARKER = "<!-- dep-brain-report -->";
+export function renderPrCommentReport(result, options = {}) {
+    const lines = [
+        PR_COMMENT_MARKER,
+        "## Dependency Brain",
+        "",
+        `**Policy:** ${result.policy.passed ? "PASS" : "FAIL"}`,
+        `**Project Health:** ${result.score}/100`,
+        `**Findings:** duplicates ${result.duplicates.length}, unused ${result.unused.length}, outdated ${result.outdated.length}, risks ${result.risks.length}`
+    ];
+    if (options.hasBaseline) {
+        lines.push(`**New since baseline:** duplicates ${result.duplicates.length}, unused ${result.unused.length}, outdated ${result.outdated.length}, risks ${result.risks.length}`);
+    }
+    if (result.policy.reasons.length > 0) {
+        lines.push("");
+        lines.push("### Policy Reasons");
+        for (const reason of result.policy.reasons) {
+            lines.push(`- ${reason}`);
+        }
+    }
+    if (result.topIssues.length > 0) {
+        lines.push("");
+        lines.push("### Top Issues");
+        for (const item of result.topIssues.slice(0, 5)) {
+            lines.push(`- **${item.priority.toUpperCase()}** ${item.kind} \`${item.name}\`${item.package ? ` [${item.package}]` : ""}: ${item.summary}`);
+        }
+    }
+    const upgradePriorities = summarizeUpgradePriorities(result);
+    if (upgradePriorities) {
+        lines.push("");
+        lines.push("### Upgrade Priorities");
+        lines.push(upgradePriorities);
+    }
+    lines.push("");
+    lines.push("_Generated by dep-brain._");
+    return lines.join("\n");
+}
+function summarizeUpgradePriorities(result) {
+    const counts = result.outdated.reduce((acc, item) => {
+        acc[item.advice.risk] += 1;
+        return acc;
+    }, { high: 0, medium: 0, low: 0 });
+    return [`high ${counts.high}`, `medium ${counts.medium}`, `low ${counts.low}`]
+        .filter((entry) => !entry.endsWith(" 0"))
+        .join(", ");
+}

package/dist/utils/github.d.ts

@@ -0,0 +1,25 @@
+export type PrCommentTrigger = "always" | "failure" | "new-findings";
+export interface GitHubPrCommentInput {
+    body: string;
+    env?: Record<string, string | undefined>;
+    request?: GitHubRequest;
+}
+export interface GitHubPrCommentResult {
+    status: "created" | "updated" | "skipped";
+    reason?: string;
+}
+export type GitHubRequest = (url: string, init: {
+    method: "GET" | "POST" | "PATCH";
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export declare function upsertGitHubPrComment(input: GitHubPrCommentInput): Promise<GitHubPrCommentResult>;
+export declare function shouldPostPrComment(input: {
+    trigger: PrCommentTrigger;
+    policyPassed: boolean;
+    newFindingsCount: number;
+}): boolean;

package/dist/utils/github.js

@@ -0,0 +1,112 @@
+import { promises as fs } from "node:fs";
+import { PR_COMMENT_MARKER } from "../reporters/pr-comment.js";
+export async function upsertGitHubPrComment(input) {
+    const env = input.env ?? process.env;
+    const token = env.GITHUB_TOKEN;
+    const repository = env.GITHUB_REPOSITORY;
+    const eventPath = env.GITHUB_EVENT_PATH;
+    if (!token) {
+        return { status: "skipped", reason: "GITHUB_TOKEN is not set" };
+    }
+    if (!repository) {
+        return { status: "skipped", reason: "GITHUB_REPOSITORY is not set" };
+    }
+    if (!eventPath) {
+        return { status: "skipped", reason: "GITHUB_EVENT_PATH is not set" };
+    }
+    const pullNumber = await readPullNumber(eventPath);
+    if (!pullNumber) {
+        return { status: "skipped", reason: "pull request event not found" };
+    }
+    const request = input.request ?? defaultGitHubRequest;
+    const commentsUrl = `https://api.github.com/repos/${repository}/issues/${pullNumber}/comments`;
+    const headers = buildHeaders(token);
+    const existingResponse = await request(commentsUrl, {
+        method: "GET",
+        headers
+    });
+    if (!existingResponse.ok) {
+        return {
+            status: "skipped",
+            reason: `failed to list comments: HTTP ${existingResponse.status}`
+        };
+    }
+    const comments = normalizeComments(await existingResponse.json());
+    const existing = comments.find((comment) => typeof comment.body === "string" && comment.body.includes(PR_COMMENT_MARKER));
+    if (existing) {
+        const updateResponse = await request(`https://api.github.com/repos/${repository}/issues/comments/${existing.id}`, {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify({ body: input.body })
+        });
+        return updateResponse.ok
+            ? { status: "updated" }
+            : {
+                status: "skipped",
+                reason: `failed to update comment: HTTP ${updateResponse.status}`
+            };
+    }
+    const createResponse = await request(commentsUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ body: input.body })
+    });
+    return createResponse.ok
+        ? { status: "created" }
+        : {
+            status: "skipped",
+            reason: `failed to create comment: HTTP ${createResponse.status}`
+        };
+}
+export function shouldPostPrComment(input) {
+    if (input.trigger === "always") {
+        return true;
+    }
+    if (input.trigger === "failure") {
+        return !input.policyPassed;
+    }
+    return input.newFindingsCount > 0;
+}
+async function readPullNumber(eventPath) {
+    try {
+        const raw = await fs.readFile(eventPath, "utf8");
+        const event = JSON.parse(raw);
+        const value = event.pull_request?.number ?? event.number;
+        return typeof value === "number" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultGitHubRequest(url, init) {
+    const response = await fetch(url, init);
+    return {
+        ok: response.ok,
+        status: response.status,
+        json: () => response.json()
+    };
+}
+function buildHeaders(token) {
+    return {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "x-github-api-version": "2022-11-28"
+    };
+}
+function normalizeComments(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => {
+        if (!item || typeof item !== "object") {
+            return null;
+        }
+        const comment = item;
+        return typeof comment.id === "number"
+            ? { id: comment.id, body: comment.body }
+            : null;
+    })
+        .filter((item) => item !== null);
+}

package/package.json

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