dep-brain 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -2,7 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## 1.0.0
+
+- Stable v1 CLI and library release for explainable dependency intelligence.
+- Added baseline mode with `--baseline <file>` to ignore existing dependency debt in CI.
+- Added reusable GitHub Action metadata through `action.yml`.
+- Added SARIF export support for code scanning workflows.
+- Added stable JSON output fields for confidence, reason codes, explanations, recommendations, top issues, score breakdown, and workspace ownership summaries.
+- Added bounded registry request parallelism for outdated and risk checks.
+- Documented v1 readiness, release validation, and CI usage.
+
+## 0.9.0
 
 - Workspace-aware analysis for npm workspaces.
 - Config loading and CI policy controls.
@@ -11,3 +21,5 @@ All notable changes to this project will be documented in this file.
 - Ranked top-issues summary output with `--top`.
 - Supply-chain trust scoring for risk findings.
 - Structured risk factors in JSON output.
+- Monorepo ownership summaries for workspace packages.
+- Workspace-level duplicate attribution and root-cause tracing.

package/README.md

@@ -17,13 +17,15 @@
 
 ## What It Does
 
-- Detect duplicate dependencies from `package-lock.json`
+- Detect duplicate dependencies from npm, pnpm, and yarn lockfiles
 - Detect likely unused dependencies from source imports and scripts
 - Detect outdated packages
 - Highlight dependency risk signals
 - Score package trust using supply-chain metadata
 - Generate a simple project health score
-- Output reports in human-readable or JSON format
+- Output reports in console, JSON, Markdown, SARIF, and top-issues formats
+- Gate CI with score and finding policies
+- Compare new findings against a baseline report
 
 The long-term goal is not just to list problems, but to answer:
 
@@ -31,18 +33,24 @@ The long-term goal is not just to list problems, but to answer:
 - Can I remove it safely?
 - What should I fix first?
 
-## Current MVP Features
+## v1 Features
 
 - Duplicate dependency detection with lockfile instance tracking
 - 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
+- Confidence scores, reason codes, explanations, and recommendations for findings
 - Config loading from `depbrain.config.json`
 - Ignore rules for noisy dependencies and checks
 - CI-friendly policy evaluation with non-zero exit codes
 - Workspace-aware analysis for npm workspaces
 - Console reporting
 - JSON output via `--json`
+- Markdown output via `--md`
+- SARIF output via `--sarif`
+- Ranked top issues via `--top`
+- Baseline mode via `--baseline`
+- Reusable GitHub Action via `action.yml`
 - Library entrypoint for programmatic use
 
 ## CLI Usage
@@ -61,6 +69,9 @@ npx dep-brain analyze --min-score 90 --fail-on-risks
 npx dep-brain analyze ./path-to-project --fail-on-unused --json
 npx dep-brain analyze --md > depbrain.md
 npx dep-brain analyze --json --out depbrain.json
+npx dep-brain analyze --sarif --out depbrain.sarif
+npx dep-brain analyze --baseline depbrain-baseline.json
+npx dep-brain analyze --baseline depbrain-baseline.json --min-score 90 --fail-on-risks
 npx dep-brain report --from depbrain.json --md --out depbrain.md
 
 dep-brain config
@@ -75,6 +86,12 @@ dep-brain --version
 
 If the root `package.json` defines `workspaces`, `dep-brain` analyzes each workspace package and reports per-package results. Aggregated counts are still shown at the top-level summary.
 
+Workspace analysis now includes:
+
+- per-workspace ownership summaries
+- root-level duplicate attribution back to contributing workspaces
+- top issues that stay tagged to the workspace that should act
+
 ## Example Output
 
 ```text
@@ -132,6 +149,41 @@ dep-brain analyze --json --out depbrain.json
 dep-brain report --from depbrain.json --md --out depbrain.md
 ```
 
+## Baseline Mode
+
+Baseline mode lets teams adopt `dep-brain` in existing repositories without failing CI for known dependency debt.
+
+```bash
+dep-brain analyze --json --out depbrain-baseline.json
+dep-brain analyze --baseline depbrain-baseline.json --min-score 90 --fail-on-risks
+```
+
+The baseline file is a normal JSON analysis report. Matching entries in `duplicates`, `unused`, `outdated`, and `risks` are ignored before score, policy, suggestions, and top issues are calculated.
+
+## GitHub Action
+
+```yaml
+name: Dependency Brain
+
+on:
+  pull_request:
+
+jobs:
+  dep-brain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: prakashu51/dep-brain@v1
+        with:
+          format: sarif
+          out: depbrain.sarif
+          min-score: 85
+          fail-on-risks: "true"
+```
+
 ## Config File
 
 Create a `depbrain.config.json` file in the project root:
@@ -202,6 +254,7 @@ Examples:
 dep-brain analyze --fail-on-unused
 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
 ```
 
 ## Config Debugging
@@ -248,7 +301,7 @@ src/
 
 ## Product Direction
 
-`dep-brain` is currently in the `v0.5.x` foundation stage. The next roadmap is:
+`dep-brain` is in its `v1.0.0` production-ready CLI stage. The roadmap delivered through v1:
 
 - `v0.6`: explainability and confidence scoring
 - `v0.7`: safe removal guidance and actionable recommendations

package/action.yml

@@ -0,0 +1,116 @@
+name: Dependency Brain
+description: Run dep-brain dependency intelligence checks in GitHub Actions.
+author: dep-brain
+
+inputs:
+  path:
+    description: Project path to analyze.
+    required: false
+    default: "."
+  format:
+    description: Output format. Use console, json, md, sarif, or top.
+    required: false
+    default: "console"
+  out:
+    description: Optional path to write the report.
+    required: false
+    default: ""
+  config:
+    description: Optional path to depbrain.config.json.
+    required: false
+    default: ""
+  baseline:
+    description: Optional baseline JSON report used to ignore existing findings.
+    required: false
+    default: ""
+  min-score:
+    description: Minimum project health score required to pass.
+    required: false
+    default: ""
+  fail-on-unused:
+    description: Fail when unused dependencies are found.
+    required: false
+    default: "false"
+  fail-on-outdated:
+    description: Fail when outdated dependencies are found.
+    required: false
+    default: "false"
+  fail-on-duplicates:
+    description: Fail when duplicate dependencies are found.
+    required: false
+    default: "false"
+  fail-on-risks:
+    description: Fail when risky dependencies are found.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Run dep-brain
+      shell: bash
+      env:
+        INPUT_PATH: ${{ inputs.path }}
+        INPUT_FORMAT: ${{ inputs.format }}
+        INPUT_OUT: ${{ inputs.out }}
+        INPUT_CONFIG: ${{ inputs.config }}
+        INPUT_BASELINE: ${{ inputs.baseline }}
+        INPUT_MIN_SCORE: ${{ inputs.min-score }}
+        INPUT_FAIL_ON_UNUSED: ${{ inputs.fail-on-unused }}
+        INPUT_FAIL_ON_OUTDATED: ${{ inputs.fail-on-outdated }}
+        INPUT_FAIL_ON_DUPLICATES: ${{ inputs.fail-on-duplicates }}
+        INPUT_FAIL_ON_RISKS: ${{ inputs.fail-on-risks }}
+      run: |
+        set -euo pipefail
+
+        args=("analyze" "$INPUT_PATH")
+
+        case "$INPUT_FORMAT" in
+          json) args+=("--json") ;;
+          md) args+=("--md") ;;
+          sarif) args+=("--sarif") ;;
+          top) args+=("--top") ;;
+          console) ;;
+          *)
+            echo "Unsupported format: $INPUT_FORMAT" >&2
+            exit 1
+            ;;
+        esac
+
+        if [ -n "$INPUT_OUT" ]; then
+          args+=("--out" "$INPUT_OUT")
+        fi
+
+        if [ -n "$INPUT_CONFIG" ]; then
+          args+=("--config" "$INPUT_CONFIG")
+        fi
+
+        if [ -n "$INPUT_BASELINE" ]; then
+          args+=("--baseline" "$INPUT_BASELINE")
+        fi
+
+        if [ -n "$INPUT_MIN_SCORE" ]; then
+          args+=("--min-score" "$INPUT_MIN_SCORE")
+        fi
+
+        if [ "$INPUT_FAIL_ON_UNUSED" = "true" ]; then
+          args+=("--fail-on-unused")
+        fi
+
+        if [ "$INPUT_FAIL_ON_OUTDATED" = "true" ]; then
+          args+=("--fail-on-outdated")
+        fi
+
+        if [ "$INPUT_FAIL_ON_DUPLICATES" = "true" ]; then
+          args+=("--fail-on-duplicates")
+        fi
+
+        if [ "$INPUT_FAIL_ON_RISKS" = "true" ]; then
+          args+=("--fail-on-risks")
+        fi
+
+        node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
+
+branding:
+  icon: activity
+  color: blue

package/depbrain.output.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Dependency Brain Analysis Output",
   "type": "object",
-  "required": ["outputVersion", "rootDir", "score", "scoreBreakdown", "policy", "duplicates", "unused", "outdated", "risks", "suggestions", "topIssues", "config"],
+  "required": ["outputVersion", "rootDir", "score", "scoreBreakdown", "policy", "ownershipSummary", "duplicates", "unused", "outdated", "risks", "suggestions", "topIssues", "config"],
   "additionalProperties": false,
   "properties": {
     "recommendation": {
@@ -31,6 +31,17 @@
         "dependencyType": { "type": "string", "enum": ["dependencies", "devDependencies", "unknown"] }
       }
     },
+    "ownershipSummary": {
+      "type": "object",
+      "required": ["duplicates", "unused", "outdated", "risks"],
+      "additionalProperties": false,
+      "properties": {
+        "duplicates": { "type": "number" },
+        "unused": { "type": "number" },
+        "outdated": { "type": "number" },
+        "risks": { "type": "number" }
+      }
+    },
     "outputVersion": { "type": "string" },
     "rootDir": { "type": "string" },
     "score": { "type": "number" },
@@ -70,11 +81,25 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "versions", "instances", "confidence", "reasonCodes", "explanation", "recommendation"],
+        "required": ["name", "versions", "instances", "workspaceUsage", "rootCause", "confidence", "reasonCodes", "explanation", "recommendation"],
         "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "versions": { "type": "array", "items": { "type": "string" } },
+          "workspaceUsage": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["workspace", "section", "declaredVersion"],
+              "additionalProperties": false,
+              "properties": {
+                "workspace": { "type": "string" },
+                "section": { "type": "string", "enum": ["dependencies", "devDependencies"] },
+                "declaredVersion": { "type": "string" }
+              }
+            }
+          },
+          "rootCause": { "type": "array", "items": { "type": "string" } },
           "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
           "reasonCodes": { "type": "array", "items": { "type": "string" } },
           "explanation": { "type": "array", "items": { "type": "string" } },

package/dist/checks/duplicate.js

@@ -4,6 +4,8 @@ export async function findDuplicateDependencies(graph) {
         name,
         versions: Array.from(new Set(instances.map((instance) => instance.version))).sort(),
         instances,
+        workspaceUsage: [],
+        rootCause: [],
         confidence: 0.98,
         reasonCodes: [
             "multiple_lockfile_versions",

package/dist/checks/outdated.js

@@ -5,7 +5,7 @@ export async function findOutdatedDependencies(graph, options = {}) {
         ...graph.dependencies,
         ...graph.devDependencies
     };
-    const results = await Promise.all(Object.entries(combined).map(async ([name, current]) => {
+    const results = await mapWithConcurrency(Object.entries(combined), 8, async ([name, current]) => {
         const normalized = normalizeVersion(current);
         const latest = await resolveLatestVersion(name);
         if (!latest || latest === normalized) {
@@ -28,11 +28,25 @@ export async function findOutdatedDependencies(graph, options = {}) {
             ],
             recommendation: buildOutdatedRecommendation(updateType)
         };
-    }));
+    });
     return results
         .filter((item) => item !== null)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+async function mapWithConcurrency(items, limit, mapper) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await mapper(items[currentIndex]);
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
 function buildOutdatedRecommendation(updateType) {
     return {
         action: "upgrade",

package/dist/checks/risk.js

@@ -7,7 +7,7 @@ export async function findRiskDependencies(graph, options = {}) {
         ...graph.dependencies,
         ...graph.devDependencies
     });
-    const results = await Promise.all(names.map(async (name) => {
+    const results = await mapWithConcurrency(names, 8, async (name) => {
         const metadata = await resolvePackageMetadata(name);
         if (!metadata) {
             return null;
@@ -31,11 +31,25 @@ export async function findRiskDependencies(graph, options = {}) {
             riskFactors: assessment.riskFactors,
             recommendation: buildRiskRecommendation(assessment.reasons, assessment.confidence, assessment.trustScore)
         };
-    }));
+    });
     return results
         .filter((item) => item !== null)
         .sort((left, right) => left.name.localeCompare(right.name));
 }
+async function mapWithConcurrency(items, limit, mapper) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await mapper(items[currentIndex]);
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
 export async function runRiskCheck(graph) {
     const risks = await findRiskDependencies(graph);
     return {

package/dist/cli.js

@@ -3,6 +3,7 @@ import { analyzeProject } from "./core/analyzer.js";
 import { renderConsoleReport } from "./reporters/console.js";
 import { renderJsonReport } from "./reporters/json.js";
 import { renderMarkdownReport } from "./reporters/markdown.js";
+import { renderSarifReport } from "./reporters/sarif.js";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 async function main() {
@@ -55,7 +56,9 @@ async function main() {
                     ? renderTopIssuesReport(reportData)
                     : flags.has("--json")
                         ? JSON.stringify(reportData, null, 2)
-                        : renderMarkdownReport(reportData);
+                        : flags.has("--sarif")
+                            ? renderSarifReport(reportData)
+                            : renderMarkdownReport(reportData);
                 await writeOutput(output, optionValues.get("--out"));
                 return;
             }
@@ -100,15 +103,20 @@ async function main() {
     }
     try {
         const cliConfig = buildCliConfig(flags, optionValues);
+        const baseline = await loadBaseline(optionValues.get("--baseline"));
         const result = await analyzeProject({
             rootDir: targetPath,
             configPath: optionValues.get("--config"),
-            config: cliConfig
+            config: cliConfig,
+            baseline
         });
         let output;
         if (flags.has("--json")) {
             output = renderJsonReport(result);
         }
+        else if (flags.has("--sarif")) {
+            output = renderSarifReport(result);
+        }
         else if (flags.has("--top")) {
             output = renderTopIssuesReport(result);
         }
@@ -178,8 +186,8 @@ function printHelp() {
     console.log("Dependency Brain");
     console.log("");
     console.log("Usage:");
-    console.log("  dep-brain analyze [path] [--json] [--md] [--top] [--out path] [--config path] [--min-score n] [--fail-on-risks] [--fail-on-outdated] [--fail-on-unused] [--fail-on-duplicates]");
-    console.log("  dep-brain report --from <file> [--md] [--json] [--top] [--out path]");
+    console.log("  dep-brain analyze [path] [--json] [--md] [--sarif] [--top] [--out path] [--config path] [--baseline path] [--min-score n] [--fail-on-risks]");
+    console.log("  dep-brain report --from <file> [--md] [--json] [--sarif] [--top] [--out path]");
     console.log("  dep-brain config [path] [--config path]");
     console.log("  dep-brain help");
     console.log("  dep-brain --version");
@@ -187,8 +195,10 @@ function printHelp() {
     console.log("Options:");
     console.log("  --json              Output JSON for analysis");
     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("  --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("  --min-score <n>     Minimum score required to pass");
@@ -210,6 +220,20 @@ async function loadPackageVersion() {
         return null;
     }
 }
+async function loadBaseline(baselinePath) {
+    if (!baselinePath) {
+        return undefined;
+    }
+    const resolved = resolveUserPath(baselinePath);
+    const raw = await fs.readFile(resolved, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        duplicates: Array.isArray(parsed.duplicates) ? parsed.duplicates : [],
+        unused: Array.isArray(parsed.unused) ? parsed.unused : [],
+        outdated: Array.isArray(parsed.outdated) ? parsed.outdated : [],
+        risks: Array.isArray(parsed.risks) ? parsed.risks : []
+    };
+}
 async function writeOutput(output, outPath) {
     if (outPath) {
         const resolved = resolveUserPath(outPath);

package/dist/core/analyzer.d.ts

@@ -3,11 +3,29 @@ export interface AnalysisOptions {
     rootDir?: string;
     configPath?: string;
     config?: DepBrainConfigOverrides;
+    baseline?: DepBrainBaseline;
+}
+export interface DepBrainBaseline {
+    duplicates?: Array<Partial<Pick<DuplicateDependency, "name">>>;
+    unused?: Array<Partial<Pick<UnusedDependency, "name" | "section" | "package">>>;
+    outdated?: Array<Partial<Pick<OutdatedDependency, "name" | "current" | "latest" | "package">>>;
+    risks?: Array<Partial<Pick<RiskDependency, "name" | "package">>>;
 }
 export interface DuplicateInstance {
     path: string;
     version: string;
 }
+export interface WorkspaceDependencyUsage {
+    workspace: string;
+    section: "dependencies" | "devDependencies";
+    declaredVersion: string;
+}
+export interface WorkspaceOwnershipSummary {
+    duplicates: number;
+    unused: number;
+    outdated: number;
+    risks: number;
+}
 export interface Recommendation {
     action: "remove" | "consolidate" | "upgrade" | "review";
     priority: "high" | "medium" | "low";
@@ -29,6 +47,8 @@ export interface DuplicateDependency {
     name: string;
     versions: string[];
     instances: DuplicateInstance[];
+    workspaceUsage: WorkspaceDependencyUsage[];
+    rootCause: string[];
     confidence: number;
     reasonCodes: string[];
     explanation: string[];
@@ -81,6 +101,7 @@ export interface AnalysisResult {
     score: number;
     scoreBreakdown: ScoreBreakdown;
     policy: PolicyResult;
+    ownershipSummary: WorkspaceOwnershipSummary;
     duplicates: DuplicateDependency[];
     unused: UnusedDependency[];
     outdated: OutdatedDependency[];
@@ -100,6 +121,7 @@ export interface PackageAnalysisResult {
     score: number;
     scoreBreakdown: ScoreBreakdown;
     policy: PolicyResult;
+    ownershipSummary: WorkspaceOwnershipSummary;
     duplicates: DuplicateDependency[];
     unused: UnusedDependency[];
     outdated: OutdatedDependency[];
@@ -107,7 +129,7 @@ export interface PackageAnalysisResult {
     suggestions: string[];
     topIssues: TopIssue[];
 }
-export declare const OUTPUT_VERSION = "1.3";
+export declare const OUTPUT_VERSION = "1.4";
 export interface ScoreBreakdown {
     baseScore: number;
     duplicates: number;

package/dist/core/analyzer.js

@@ -8,14 +8,16 @@ import { findWorkspacePackages } from "../utils/workspaces.js";
 import { buildDependencyGraph } from "./graph-builder.js";
 import { calculateHealthScore } from "./scorer.js";
 import { buildAnalysisContext } from "./context.js";
-export const OUTPUT_VERSION = "1.3";
+export const OUTPUT_VERSION = "1.4";
 export async function analyzeProject(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
     const loadedConfig = await loadDepBrainConfig(rootDir, options.configPath);
     const config = mergeConfig(loadedConfig, options.config);
     const workspaces = await findWorkspacePackages(rootDir);
     if (workspaces.length === 0) {
-        return analyzeSingleProject(rootDir, config);
+        return analyzeSingleProject(rootDir, config, {
+            baseline: options.baseline
+        });
     }
     const rootGraph = await buildDependencyGraph(rootDir);
     const duplicateCheck = await runDuplicateCheck(rootGraph);
@@ -28,11 +30,26 @@ export async function analyzeProject(options = {}) {
         });
         packages.push({ ...result, name: workspace.name });
     }
-    const unused = packages.flatMap((pkg) => pkg.unused.map((item) => ({ ...item, package: pkg.name })));
-    const outdated = packages.flatMap((pkg) => pkg.outdated.map((item) => ({ ...item, package: pkg.name })));
-    const risks = packages.flatMap((pkg) => pkg.risks.map((item) => ({ ...item, package: pkg.name })));
+    const workspaceGraphs = await Promise.all(workspaces.map(async (workspace) => ({
+        name: workspace.name,
+        graph: await buildDependencyGraph(workspace.rootDir)
+    })));
+    const attributedDuplicates = addWorkspaceAttribution(duplicates, workspaceGraphs);
+    const rawUnused = packages.flatMap((pkg) => pkg.unused.map((item) => ({ ...item, package: pkg.name })));
+    const rawOutdated = packages.flatMap((pkg) => pkg.outdated.map((item) => ({ ...item, package: pkg.name })));
+    const rawRisks = packages.flatMap((pkg) => pkg.risks.map((item) => ({ ...item, package: pkg.name })));
+    const baselineFiltered = filterBaselineFindings({
+        duplicates: attributedDuplicates,
+        unused: rawUnused,
+        outdated: rawOutdated,
+        risks: rawRisks
+    }, options.baseline);
+    const activeDuplicates = baselineFiltered.duplicates;
+    const unused = baselineFiltered.unused;
+    const outdated = baselineFiltered.outdated;
+    const risks = baselineFiltered.risks;
     const score = calculateHealthScore({
-        duplicates: duplicates.length,
+        duplicates: activeDuplicates.length,
         unused: unused.length,
         outdated: outdated.length,
         risks: risks.length,
@@ -42,17 +59,19 @@ export async function analyzeProject(options = {}) {
         riskWeight: config.scoring.riskWeight
     });
     const scoreBreakdown = buildScoreBreakdown({
-        duplicates: duplicates.length,
+        duplicates: activeDuplicates.length,
         unused: unused.length,
         outdated: outdated.length,
         risks: risks.length
     }, config);
     const suggestions = [
-        ...packages.flatMap((pkg) => pkg.suggestions.map((suggestion) => `[${pkg.name}] ${suggestion}`))
+        ...unused.map((item) => `Remove ${item.name} from ${item.section}`),
+        ...activeDuplicates.map((item) => `Consider consolidating ${item.name} to one version`),
+        ...outdated.map((item) => `Review ${item.name}: ${item.current} -> ${item.latest} (${item.updateType})`)
     ].slice(0, config.report.maxSuggestions);
     const policy = evaluatePolicy({
         score,
-        duplicates: duplicates.length,
+        duplicates: activeDuplicates.length,
         unused: unused.length,
         outdated: outdated.length,
         risks: risks.length
@@ -63,12 +82,23 @@ export async function analyzeProject(options = {}) {
         score,
         scoreBreakdown,
         policy,
-        duplicates,
+        ownershipSummary: buildOwnershipSummary({
+            duplicates: activeDuplicates,
+            unused,
+            outdated,
+            risks
+        }),
+        duplicates: activeDuplicates,
         unused,
         outdated,
         risks,
         suggestions,
-        topIssues: buildTopIssues({ duplicates, unused, outdated, risks }),
+        topIssues: buildTopIssues({
+            duplicates: activeDuplicates,
+            unused,
+            outdated,
+            risks
+        }),
         config,
         packages
     };
@@ -139,59 +169,71 @@ async function analyzeSingleProject(rootDir, config, options = {}) {
     const unused = mapUnusedIssues(issueGroups.unused);
     const outdated = mapOutdatedIssues(issueGroups.outdated);
     const risks = mapRiskIssues(issueGroups.risks);
+    const scopedUnused = options.packageName && options.packageName.trim().length > 0
+        ? unused.map((item) => ({ ...item, package: options.packageName }))
+        : unused;
+    const scopedOutdated = options.packageName && options.packageName.trim().length > 0
+        ? outdated.map((item) => ({ ...item, package: options.packageName }))
+        : outdated;
+    const scopedRisks = options.packageName && options.packageName.trim().length > 0
+        ? risks.map((item) => ({ ...item, package: options.packageName }))
+        : risks;
+    const baselineFiltered = filterBaselineFindings({
+        duplicates,
+        unused: scopedUnused,
+        outdated: scopedOutdated,
+        risks: scopedRisks
+    }, options.baseline);
     const score = calculateHealthScore({
-        duplicates: duplicates.length,
-        unused: unused.length,
-        outdated: outdated.length,
-        risks: risks.length,
+        duplicates: baselineFiltered.duplicates.length,
+        unused: baselineFiltered.unused.length,
+        outdated: baselineFiltered.outdated.length,
+        risks: baselineFiltered.risks.length,
         duplicateWeight: config.scoring.duplicateWeight,
         outdatedWeight: config.scoring.outdatedWeight,
         unusedWeight: config.scoring.unusedWeight,
         riskWeight: config.scoring.riskWeight
     });
     const scoreBreakdown = buildScoreBreakdown({
-        duplicates: duplicates.length,
-        unused: unused.length,
-        outdated: outdated.length,
-        risks: risks.length
+        duplicates: baselineFiltered.duplicates.length,
+        unused: baselineFiltered.unused.length,
+        outdated: baselineFiltered.outdated.length,
+        risks: baselineFiltered.risks.length
     }, config);
     const suggestions = [
-        ...unused.map((item) => `Remove ${item.name} from ${item.section}`),
-        ...duplicates.map((item) => `Consider consolidating ${item.name} to one version`),
-        ...outdated.map((item) => `Review ${item.name}: ${item.current} -> ${item.latest} (${item.updateType})`)
+        ...baselineFiltered.unused.map((item) => `Remove ${item.name} from ${item.section}`),
+        ...baselineFiltered.duplicates.map((item) => `Consider consolidating ${item.name} to one version`),
+        ...baselineFiltered.outdated.map((item) => `Review ${item.name}: ${item.current} -> ${item.latest} (${item.updateType})`)
     ].slice(0, config.report.maxSuggestions);
     const policy = evaluatePolicy({
         score,
-        duplicates: duplicates.length,
-        unused: unused.length,
-        outdated: outdated.length,
-        risks: risks.length
+        duplicates: baselineFiltered.duplicates.length,
+        unused: baselineFiltered.unused.length,
+        outdated: baselineFiltered.outdated.length,
+        risks: baselineFiltered.risks.length
     }, config);
-    const scopedUnused = options.packageName && options.packageName.trim().length > 0
-        ? unused.map((item) => ({ ...item, package: options.packageName }))
-        : unused;
-    const scopedOutdated = options.packageName && options.packageName.trim().length > 0
-        ? outdated.map((item) => ({ ...item, package: options.packageName }))
-        : outdated;
-    const scopedRisks = options.packageName && options.packageName.trim().length > 0
-        ? risks.map((item) => ({ ...item, package: options.packageName }))
-        : risks;
     return {
         outputVersion: OUTPUT_VERSION,
         rootDir,
         score,
         scoreBreakdown,
         policy,
-        duplicates,
-        unused: scopedUnused,
-        outdated: scopedOutdated,
-        risks: scopedRisks,
+        ownershipSummary: buildOwnershipSummary({
+            duplicates: baselineFiltered.duplicates,
+            unused: baselineFiltered.unused,
+            outdated: baselineFiltered.outdated,
+            risks: baselineFiltered.risks
+        }),
+        duplicates: baselineFiltered.duplicates,
+        unused: baselineFiltered.unused,
+        outdated: baselineFiltered.outdated,
+        risks: baselineFiltered.risks,
         suggestions,
         topIssues: buildTopIssues({
-            duplicates,
-            unused: scopedUnused,
-            outdated: scopedOutdated,
-            risks: scopedRisks
+            duplicates: baselineFiltered.duplicates,
+            unused: baselineFiltered.unused,
+            outdated: baselineFiltered.outdated,
+            risks: baselineFiltered.risks
         }),
         config
     };
@@ -272,6 +314,8 @@ function mapDuplicateIssues(issues) {
         instances: Array.isArray(issue.meta?.instances)
             ? issue.meta?.instances
             : [],
+        workspaceUsage: normalizeWorkspaceUsage(issue.meta?.workspaceUsage),
+        rootCause: normalizeStringArray(issue.meta?.rootCause),
         confidence: normalizeConfidence(issue.confidence),
         reasonCodes: normalizeStringArray(issue.reasonCodes),
         explanation: normalizeStringArray(issue.explanation),
@@ -437,6 +481,62 @@ function compareTrustScore(left, right) {
     const rank = { low: 3, medium: 2, high: 1, undefined: 0 };
     return rank[left ?? "undefined"] - rank[right ?? "undefined"];
 }
+function addWorkspaceAttribution(duplicates, workspaceGraphs) {
+    return duplicates.map((item) => {
+        const usage = [];
+        for (const workspace of workspaceGraphs) {
+            const runtimeVersion = workspace.graph.dependencies[item.name];
+            if (runtimeVersion) {
+                usage.push({
+                    workspace: workspace.name,
+                    section: "dependencies",
+                    declaredVersion: runtimeVersion
+                });
+            }
+            const devVersion = workspace.graph.devDependencies[item.name];
+            if (devVersion) {
+                usage.push({
+                    workspace: workspace.name,
+                    section: "devDependencies",
+                    declaredVersion: devVersion
+                });
+            }
+        }
+        return {
+            ...item,
+            workspaceUsage: usage,
+            rootCause: usage.map((entry) => `${entry.workspace} -> ${item.name}@${entry.declaredVersion}`)
+        };
+    });
+}
+function buildOwnershipSummary(input) {
+    return {
+        duplicates: input.duplicates.length,
+        unused: input.unused.length,
+        outdated: input.outdated.length,
+        risks: input.risks.length
+    };
+}
+function filterBaselineFindings(findings, baseline) {
+    if (!baseline) {
+        return findings;
+    }
+    return {
+        duplicates: findings.duplicates.filter((item) => !(baseline.duplicates ?? []).some((entry) => entry.name === item.name)),
+        unused: findings.unused.filter((item) => !(baseline.unused ?? []).some((entry) => entry.name === item.name &&
+            optionalMatches(entry.section, item.section) &&
+            optionalMatches(entry.package, item.package))),
+        outdated: findings.outdated.filter((item) => !(baseline.outdated ?? []).some((entry) => entry.name === item.name &&
+            optionalMatches(entry.current, item.current) &&
+            optionalMatches(entry.latest, item.latest) &&
+            optionalMatches(entry.package, item.package))),
+        risks: findings.risks.filter((item) => !(baseline.risks ?? []).some((entry) => entry.name === item.name &&
+            optionalMatches(entry.package, item.package)))
+    };
+}
+function optionalMatches(expected, actual) {
+    return expected === undefined || expected === actual;
+}
 function normalizeConfidence(value) {
     if (typeof value !== "number" || Number.isNaN(value)) {
         return 0.5;
@@ -479,6 +579,29 @@ function normalizeRiskFactors(value) {
             : "unknown"
     };
 }
+function normalizeWorkspaceUsage(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+            return null;
+        }
+        const usage = entry;
+        if (typeof usage.workspace !== "string" ||
+            typeof usage.declaredVersion !== "string" ||
+            (usage.section !== "dependencies" && usage.section !== "devDependencies")) {
+            return null;
+        }
+        return {
+            workspace: usage.workspace,
+            section: usage.section,
+            declaredVersion: usage.declaredVersion
+        };
+    })
+        .filter((entry) => entry !== null);
+}
 function buildScoreBreakdown(counts, config) {
     return {
         baseScore: 100,

package/dist/core/graph-builder.js

@@ -1,8 +1,11 @@
 import path from "node:path";
+import { promises as fs } from "node:fs";
 import { readJsonFile } from "../utils/file-parser.js";
 export async function buildDependencyGraph(rootDir) {
     const packageJsonPath = path.join(rootDir, "package.json");
     const lockfilePath = path.join(rootDir, "package-lock.json");
+    const pnpmLockfilePath = path.join(rootDir, "pnpm-lock.yaml");
+    const yarnLockfilePath = path.join(rootDir, "yarn.lock");
     const packageJson = await readJsonFile(packageJsonPath);
     const lockPackages = new Map();
     try {
@@ -29,13 +32,15 @@ export async function buildDependencyGraph(rootDir) {
         }
     }
     catch {
+        const fallbackLockfile = await readAlternativeLockfile(pnpmLockfilePath, yarnLockfilePath);
         return {
             rootDir,
             packageJsonPath,
+            lockfilePath: fallbackLockfile.lockfilePath,
             dependencies: packageJson.dependencies ?? {},
             devDependencies: packageJson.devDependencies ?? {},
             scripts: packageJson.scripts ?? {},
-            lockPackages: {}
+            lockPackages: fallbackLockfile.lockPackages
         };
     }
     return {
@@ -51,6 +56,30 @@ export async function buildDependencyGraph(rootDir) {
         ]))
     };
 }
+async function readAlternativeLockfile(pnpmLockfilePath, yarnLockfilePath) {
+    try {
+        const content = await fs.readFile(pnpmLockfilePath, "utf8");
+        return {
+            lockfilePath: pnpmLockfilePath,
+            lockPackages: parsePnpmLockfile(content)
+        };
+    }
+    catch {
+        // Try yarn.lock below.
+    }
+    try {
+        const content = await fs.readFile(yarnLockfilePath, "utf8");
+        return {
+            lockfilePath: yarnLockfilePath,
+            lockPackages: parseYarnLockfile(content)
+        };
+    }
+    catch {
+        return {
+            lockPackages: {}
+        };
+    }
+}
 function extractPackageName(packagePath) {
     if (!packagePath) {
         return null;
@@ -61,3 +90,66 @@ function extractPackageName(packagePath) {
     }
     return match[1];
 }
+function parsePnpmLockfile(content) {
+    const lockPackages = new Map();
+    for (const line of content.split(/\r?\n/)) {
+        const match = line.match(/^\s{2}(?:'|")?\/((?:@[^/]+\/)?[^/@'"]+)@([^('":]+)[^:]*:(?:'|")?\s*$/);
+        if (!match) {
+            continue;
+        }
+        addLockPackage(lockPackages, match[1], `pnpm-lock:${match[0].trim()}`, match[2]);
+    }
+    return toLockPackageRecord(lockPackages);
+}
+function parseYarnLockfile(content) {
+    const lockPackages = new Map();
+    let currentNames = [];
+    for (const line of content.split(/\r?\n/)) {
+        if (line.trim().length === 0 || line.startsWith("#")) {
+            continue;
+        }
+        if (!line.startsWith(" ") && line.endsWith(":")) {
+            currentNames = extractYarnEntryNames(line.slice(0, -1));
+            continue;
+        }
+        const versionMatch = line.match(/^\s+version\s+"?([^"\s]+)"?\s*$/);
+        if (!versionMatch) {
+            continue;
+        }
+        for (const name of currentNames) {
+            addLockPackage(lockPackages, name, `yarn-lock:${name}@${versionMatch[1]}`, versionMatch[1]);
+        }
+    }
+    return toLockPackageRecord(lockPackages);
+}
+function extractYarnEntryNames(entry) {
+    const names = new Set();
+    const unquoted = entry.replace(/^["']|["']$/g, "");
+    for (const selector of unquoted.split(/,\s*/)) {
+        const normalized = selector.replace(/^["']|["']$/g, "");
+        const withoutProtocol = normalized.replace(/@npm:/, "@");
+        if (withoutProtocol.startsWith("@")) {
+            const scoped = withoutProtocol.match(/^(@[^/]+\/[^@]+)/);
+            if (scoped) {
+                names.add(scoped[1]);
+            }
+            continue;
+        }
+        const unscoped = withoutProtocol.match(/^([^@]+)/);
+        if (unscoped?.[1]) {
+            names.add(unscoped[1]);
+        }
+    }
+    return Array.from(names);
+}
+function addLockPackage(lockPackages, name, packagePath, version) {
+    const instances = lockPackages.get(name) ?? new Map();
+    instances.set(packagePath, { path: packagePath, version });
+    lockPackages.set(name, instances);
+}
+function toLockPackageRecord(lockPackages) {
+    return Object.fromEntries(Array.from(lockPackages.entries()).map(([name, instances]) => [
+        name,
+        Array.from(instances.values()).sort((left, right) => left.path.localeCompare(right.path))
+    ]));
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { analyzeProject } from "./core/analyzer.js";
-export type { AnalysisOptions, AnalysisResult, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, Recommendation, ScoreBreakdown, RiskDependency, TopIssue, UnusedDependency } from "./core/analyzer.js";
+export type { AnalysisOptions, AnalysisResult, DepBrainBaseline, DuplicateDependency, OutdatedDependency, PolicyResult, PackageAnalysisResult, Recommendation, RiskFactors, ScoreBreakdown, RiskDependency, TopIssue, TrustScore, UnusedDependency, WorkspaceDependencyUsage, WorkspaceOwnershipSummary } from "./core/analyzer.js";
 export { OUTPUT_VERSION } from "./core/analyzer.js";
 export type { AnalysisContext, CheckResult, Issue } from "./core/types.js";
 export type { DepBrainConfig, DepBrainConfigOverrides } from "./utils/config.js";

package/dist/reporters/console.js

@@ -20,10 +20,10 @@ export function renderConsoleReport(result) {
         lines.push("");
         lines.push("Packages:");
         for (const pkg of result.packages) {
-            lines.push(`- ${pkg.name}: ${pkg.score}/100, D:${pkg.duplicates.length} U:${pkg.unused.length} O:${pkg.outdated.length} R:${pkg.risks.length}`);
+            lines.push(`- ${pkg.name}: ${pkg.score}/100, D:${pkg.ownershipSummary.duplicates} U:${pkg.ownershipSummary.unused} O:${pkg.ownershipSummary.outdated} R:${pkg.ownershipSummary.risks}`);
         }
     }
-    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => formatEntry(`${item.name}: ${item.versions.join(", ")}`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => formatEntry(`${item.name}: ${item.versions.join(", ")}${item.rootCause.length > 0 ? ` | via ${item.rootCause.join("; ")}` : ""}`, item.confidence, item.explanation, item.recommendation)));
     appendSection(lines, "Unused dependencies", result.unused.map((item) => formatEntry(item.package
         ? `${item.name} (${item.section}) [${item.package}]`
         : `${item.name} (${item.section})`, item.confidence, item.explanation, item.recommendation)));

package/dist/reporters/markdown.js

@@ -17,7 +17,7 @@ export function renderMarkdownReport(result) {
     if (result.packages && result.packages.length > 0) {
         lines.push("## Packages");
         for (const pkg of result.packages) {
-            lines.push(`- ${pkg.name}: ${pkg.score}/100 (D:${pkg.duplicates.length} U:${pkg.unused.length} O:${pkg.outdated.length} R:${pkg.risks.length})`);
+            lines.push(`- ${pkg.name}: ${pkg.score}/100 (D:${pkg.ownershipSummary.duplicates} U:${pkg.ownershipSummary.unused} O:${pkg.ownershipSummary.outdated} R:${pkg.ownershipSummary.risks})`);
         }
         lines.push("");
     }
@@ -27,7 +27,7 @@ export function renderMarkdownReport(result) {
     lines.push(`- Outdated: ${result.outdated.length}`);
     lines.push(`- Risks: ${result.risks.length}`);
     lines.push("");
-    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => formatEntry(`${item.name}: ${item.versions.join(", ")}`, item.confidence, item.explanation, item.recommendation)));
+    appendSection(lines, "Duplicate dependencies", result.duplicates.map((item) => formatEntry(`${item.name}: ${item.versions.join(", ")}${item.rootCause.length > 0 ? ` | via ${item.rootCause.join("; ")}` : ""}`, item.confidence, item.explanation, item.recommendation)));
     appendSection(lines, "Unused dependencies", result.unused.map((item) => formatEntry(item.package
         ? `${item.name} (${item.section}) [${item.package}]`
         : `${item.name} (${item.section})`, item.confidence, item.explanation, item.recommendation)));

package/dist/reporters/sarif.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult } from "../core/analyzer.js";
+export declare function renderSarifReport(result: AnalysisResult): string;

package/dist/reporters/sarif.js

@@ -0,0 +1,126 @@
+export function renderSarifReport(result) {
+    const rules = [
+        {
+            id: "dep-brain-unused",
+            shortDescription: { text: "Unused Dependency" },
+            fullDescription: { text: "A dependency was detected but does not appear to be used in the source code." },
+            helpUri: "https://github.com/prakashu51/dep-brain"
+        },
+        {
+            id: "dep-brain-duplicate",
+            shortDescription: { text: "Duplicate Dependency" },
+            fullDescription: { text: "Multiple versions of the same dependency exist in the lockfile." },
+            helpUri: "https://github.com/prakashu51/dep-brain"
+        },
+        {
+            id: "dep-brain-outdated",
+            shortDescription: { text: "Outdated Dependency" },
+            fullDescription: { text: "A newer version of the dependency is available." },
+            helpUri: "https://github.com/prakashu51/dep-brain"
+        },
+        {
+            id: "dep-brain-risk",
+            shortDescription: { text: "Risky Dependency" },
+            fullDescription: { text: "A dependency exhibits supply-chain risk signals." },
+            helpUri: "https://github.com/prakashu51/dep-brain"
+        }
+    ];
+    const results = [];
+    const mapLevel = (priority) => {
+        switch (priority) {
+            case "high": return "error";
+            case "medium": return "warning";
+            case "low": return "note";
+            default: return "none";
+        }
+    };
+    for (const item of result.unused) {
+        results.push({
+            ruleId: "dep-brain-unused",
+            level: mapLevel(item.recommendation.priority),
+            message: {
+                text: `[Unused] ${item.name}\n\n${item.recommendation.summary}\nReasons:\n- ${item.recommendation.reasons.join('\n- ')}`
+            },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: {
+                            uri: item.package ? `packages/${item.package}/package.json` : "package.json"
+                        }
+                    }
+                }
+            ]
+        });
+    }
+    for (const item of result.duplicates) {
+        results.push({
+            ruleId: "dep-brain-duplicate",
+            level: mapLevel(item.recommendation.priority),
+            message: {
+                text: `[Duplicate] ${item.name} (${item.versions.join(", ")})\n\n${item.recommendation.summary}`
+            },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: {
+                            uri: "package-lock.json"
+                        }
+                    }
+                }
+            ]
+        });
+    }
+    for (const item of result.outdated) {
+        results.push({
+            ruleId: "dep-brain-outdated",
+            level: mapLevel(item.recommendation.priority),
+            message: {
+                text: `[Outdated] ${item.name}: ${item.current} -> ${item.latest} (${item.updateType})\n\n${item.recommendation.summary}`
+            },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: {
+                            uri: item.package ? `packages/${item.package}/package.json` : "package.json"
+                        }
+                    }
+                }
+            ]
+        });
+    }
+    for (const item of result.risks) {
+        results.push({
+            ruleId: "dep-brain-risk",
+            level: mapLevel(item.recommendation.priority),
+            message: {
+                text: `[Risk] ${item.name} (Trust: ${item.trustScore})\n\n${item.recommendation.summary}\nReasons:\n- ${item.recommendation.reasons.join('\n- ')}`
+            },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: {
+                            uri: item.package ? `packages/${item.package}/package.json` : "package.json"
+                        }
+                    }
+                }
+            ]
+        });
+    }
+    const sarif = {
+        version: "2.1.0",
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "Dependency Brain",
+                        informationUri: "https://github.com/prakashu51/dep-brain",
+                        rules
+                    }
+                },
+                results
+            }
+        ]
+    };
+    return JSON.stringify(sarif, null, 2);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dep-brain",
-  "version": "0.8.0",
-  "description": "CLI and library for dependency health analysis",
+  "version": "1.0.0",
+  "description": "CLI and library for explainable dependency intelligence",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,7 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "action.yml",
     "depbrain.config.json",
     "depbrain.config.schema.json",
     "depbrain.output.schema.json"